ez
A cross-platform Python utility library for easy shell interaction and common programming tasks on Linux, macOS, and Windows.
Installation
pip install ez
Requires Python 3.11+.
Quick Start
from ez import *
# File operations
files = ls('~/Documents', r'\.py$')
cp('source.txt', '~/backup/')
mv('old_name.txt', 'new_name.txt')
rm('temp/')
# Path utilities
print(cwd()) # current working directory
print(jp('~', 'Documents', 'file')) # join path components
print(sp('/path/to/file.txt')) # => ['/path/to', 'file', '.txt']
# Execute shell commands
execute('ls -la')
output = execute2('echo hello')
esp('echo %s', 'world')
# Read/write spreadsheets
data = readx('data.xlsx')
savex('output.xlsx', data, header=['Name', 'Age'])
Features
File & Directory Operations
| Function |
Description |
ls([path[, regex]], full=True, dotfile=False) |
List files in a directory, filtered by regex. |
lsd([path[, regex]], full=False, dotfolder=False) |
List subdirectories. |
fls([path[, regex]]) |
Recursively list all files (walks subdirectories). Regex matches filename only, case-sensitive. |
mkdir(path) |
Create a directory and any missing parents (like mkdir -p). |
cp(src, dst) |
Copy file(s) or a folder; supports wildcards and vectorization. |
mv(src, dst) |
Move file(s) or a folder; supports wildcards and vectorization. |
rm(path) |
Delete a file or folder; supports wildcards and vectorization. |
rn(old, new) |
Rename a file or directory. |
exists(path) |
Check whether a path exists (returns 0 or 1). |
tree([path, sum=True, save=None, sort=True, case=True]) |
Print a directory tree. sum=True shows only folders; sum=False includes files. |
Path Utilities
| Function |
Description |
fullpath(path) / fp(path) |
Resolve the full absolute path (expands ~, ..). |
pwd() / cwd() |
Return the current working directory. |
csd() |
Return the directory of the currently running script. |
csf() |
Return the current script filename without its extension. |
parentdir(path) / pr(path) |
Return the parent directory of a path. |
joinpath(*parts) / jp(*parts) |
Join path components; supports vectorization. |
splitpath(path) / sp(path) |
Split a path into [directory, filename, extension]; supports vectorization. |
cd(path) |
Change the current working directory. |
stepfolder(n) |
Navigate up or down the directory hierarchy by n levels. |
String Utilities
| Function |
Description |
trim(string, how[, chars]) |
Strip whitespace or specific characters. |
quote(string) |
Wrap a string in quotes. |
join(sep, *strings) / join(sep, array) |
Concatenate strings with a separator; supports vectorization. |
sort(array) |
Sort a list. |
replace(lst, item, replacement) |
Replace an element in a list. |
remove(lst, item) |
Remove an element from a list. |
Shell Execution
| Function |
Description |
execute(cmd) |
Run a shell command without capturing output (subprocess.call). |
execute1(cmd) |
Run a shell command and discard its output. |
execute2(cmd) |
Run a shell command and return the captured output (subprocess.Popen). |
sprintf(fmt, *args, **kwargs) |
Format a string (like C's sprintf). |
esp(fmt, ...) / esp1(...) / esp2(...) |
Execute a sprintf-formatted shell command. |
espR(fmt, ...) / espR1(...) / espR2(...) |
Execute sprintf-formatted R code. |
evaluate(exp) |
Evaluate and execute a shell expression. |
Spreadsheet & Data I/O
| Function |
Description |
readx(path, sheet=0, r=[1,], c=None) |
Read a .xlsx, .xls, or .csv file into a list. |
savex(path, data, header=None, delimiter=",", sheet_name='Sheet1') |
Write a list of lists to a .xlsx, .xls, or .csv file. |
Regular Expressions
| Function |
Description |
regexp(string, pattern) |
Return [starts, ends] match positions; also accepts method='split' or method='match'. |
regexpi(string, pattern) |
Case-insensitive variant of regexp. |
regexprep(string, pattern, replace, count=0) |
Replace pattern matches in a string. |
regexprepi(string, pattern, replace, count=0) |
Case-insensitive variant of regexprep. |
Utility & Debugging
| Function |
Description |
debug(1/0) |
Toggle simulation mode. 1 simulates cp, mv, and execute (prints without running); 0 executes for real. |
error(msg) |
Raise an error with a message. |
pprint(text, color='green') |
Color-coded console print. |
ppprint(obj) |
Pretty-print arbitrary Python data structures. |
beep() |
Emit a system beep. |
which(name) |
Locate a module, or show which Python interpreter is active (e.g., which('python')). |
help(name) / doc(name) |
Print a module, class, or function docstring. |
ver(pkg) / version(pkg) |
Check a package's installed version (pkg can be 'python'). |
whos([name]) |
List imported functions and packages. |
with nooutput(): |
Context manager that suppresses stdout within the block. |
Logging
| Function |
Description |
logon(file="log.txt", mode='a', status=True, timestamp=True) |
Begin logging stdout to a file. |
logoff() |
Stop logging. |
Randomization
| Function |
Description |
Randomize(x) / randomize(x) |
Seed the random number generator. |
RandomizeArray(lst) / randomizearray(lst) |
Shuffle a list in place. |
Random(a, b) / random(a, b) |
Return a random integer N such that a ≤ N ≤ b. |
RandomChoice(seq) / randomchoice(seq) |
Return a random element from a sequence. |
Permute(iterable) / permute(iterable) |
Return all permutations as a list. |
Set Operations
All set operations preserve the original order of elements.
| Function |
Description |
unique(seq) |
Remove duplicates. unique('abracadaba') → ['a', 'b', 'r', 'c', 'd'] |
union(seq1, seq2) |
Set union. |
intersect(seq1, seq2) |
Set intersection. |
setdiff(seq1, seq2) |
Elements in seq1 not in seq2. Note: setdiff(a, b) ≠ setdiff(b, a) in general. |
duplicate(seq) |
Return only elements that appear more than once. duplicate([1,5,2,3,2,1,5,6,5]) → [2, 1, 5] |
Clipboard
| Function |
Description |
SetClip(content) / setclip(content) |
Write content to the system clipboard. |
GetClip() / getclip() |
Read content from the system clipboard. |
Miscellaneous
| Function |
Description |
num(string) |
Convert a string to a number. |
isempty(s) |
Check if a value is empty. |
iff(expr, result1, result2) / ifelse(...) |
Inline conditional (ternary) expression. |
clear(module, recursive=False) |
Reload a module. |
lines(path='.', pattern='\.py$', recursive=True) |
Count lines of code (including empty lines) matching a file pattern. |
keygen(length=8, complexity=3) |
Generate a random key string. |
hashes(filename) |
Calculate and print a file's MD5 and SHA1 hashes; memory-efficient for large files. |
encoding_detect(path) |
Detect the character encoding of a file. |
encoding_convert(path) |
Convert a file's encoding. |
JDict() |
A custom ordered dictionary with convenient attribute access and helper methods. Use help(JDict) for details. |
Moment(timezone) |
Return the current datetime in a specified timezone, or a local naive datetime if omitted. |
Pipe
Chain operations using a pipe-style syntax:
# Basic pipe
[1, 2, 3, 0] > ez.pipe | len | str
# Countdown example
ez.pipe | (range, -1) | reversed | ez.pipetools.foreach('{0}...') | ' '.join | '{0} boom'
General Notes
- Almost all path-related commands support
~, .., ., ?, and *. The exceptions are ls and fls, which use regular expressions for filtering.
- File operations target symbolic links themselves, not the underlying files they point to.
License
GNU General Public License v3 or later (GPLv3+)
