yautil
Yet Another Python util — a grab bag of helpers grown out of day-to-day work: argparse extensions, file utilities, multiprocessing-friendly caches, Docker shell helpers, plotting wrappers, password/keyring helpers, and a transactional filesystem-mount API.
Failed sub-imports degrade to dummy modules (so import yautil works even if one optional dep is missing). Python ≥ 3.11.
Install
pip install -e .
Requires sh, matplotlib; optional: argcomplete, keyring, tqdm.
API
Top-level re-exports — from yautil import ...:
argparse extensions (yautil.argparse)
| Symbol |
Purpose |
OverridingAppendAction |
append-style action where a later flag replaces the accumulated list. |
SplitAppendAction |
append that splits each value on a delimiter (e.g. a,b,c). |
SmartAppendAction |
Heuristic combination of override + split semantics. |
ChoiceComb |
list[str] subclass used as choices= to allow comma-separated combinations. |
WarningAction |
--warning=foo,bar action with allowed-value validation. |
Files (yautil.file)
| Symbol |
Purpose |
find(root, ...) |
Non-recursive find with name patterns / type filter. |
find_recursive(root, name_patterns=None, ignored_dirs=None, type='any', depth=-1, sort=False) |
Recursive find with prune list. |
remove_contents(folder) |
Delete every entry inside folder without removing it. |
overwrite(src, dst) |
Replace dst with src atomically. |
get_memtmpdir(suffix=None, prefix=None, dir=None) |
TemporaryDirectory on /dev/shm (or tmpfs) when available. |
Writable |
File-like wrapper that proxies writes; useful for piping output. |
Decorators (yautil.decorators)
| Symbol |
Purpose |
static_vars(**kw) |
Attach mutable "static" attributes to a function on first call. |
Events (yautil.event)
| Symbol |
Purpose |
Event |
Listenable event object (+= handler to subscribe, call to fire). |
EventGenerator |
Mixin / factory that declares named Events on an object. |
Printing (yautil.print)
| Symbol |
Purpose |
decomment_cxx(text) |
Strip // and /* */ comments from C/C++/Java text. |
auto_print(string, max_len=-1, **kwargs) |
print with auto-truncation past max_len. |
strcompare(left, right, width=-1, highlight=True) -> str |
Side-by-side diff string with ANSI highlighting. |
Plotting (yautil.plot)
Thin matplotlib wrappers — all accept *data and a common set of styling kwargs.
| Symbol |
Plot type |
plot_cdf |
Cumulative distribution function. |
plot_linear |
Line plot. |
plot_scatter |
Scatter plot. |
plot_box |
Box plot. |
plot_stack |
Stacked area / bar plot. |
Caches
| Symbol |
Purpose |
lru_cache(...) (yautil.lru_cache_ext) |
Like functools.lru_cache but hashes list/dict arguments too. |
PersistentCache (yautil.persistent_cache) |
Disk-backed cache under ~/.cache/; survives process restarts. |
Passwords (yautil.passwd)
| Symbol |
Purpose |
create_w_password(...) |
Build an object that requires interactive password unlock. |
create_w_secrets(...) |
Build an object that pulls secrets from a password-protected store. |
(See the module for the exact constructor signatures — both wrap keyring and an encrypted local secrets file.)
Docker shell (yautil.docker_sh)
| Symbol |
Purpose |
docker_sh(...) |
sh-compatible Command that runs inside a built/pulled Docker image, with bind mounts, user-id pass-through, and interactive TTY support. |
AuthorizationError |
Raised when the daemon refuses (e.g. missing docker login). |
Git (yautil.git)
| Symbol |
Purpose |
git_expand(repo, dest, *checkout_targets, ignore_errors=False, iter=False) |
Shallow-clone (or update) repo into dest for each checkout_target (branch/tag/sha). |
git_merge_file(...) |
Three-way file merge wrapping git merge-file. |
IO (yautil.io)
| Symbol |
Purpose |
FilteredTextIO |
TextIO proxy that runs every write through a WriteCallback. |
Shell interop (yautil.pysh)
| Symbol |
Purpose |
compile_shargs(*args, **kwargs) |
Pack Python call args into the (args, kwargs) form sh.Command expects. |
get_cmd_args(cmd) |
Recover the argv that produced a given sh.Command invocation. |
Mount API (yautil.mount)
Filesystem-mount abstraction for disk images / archives, plus high-level mount / extract / archive helpers.
from yautil.mount import mount, extract, archive, DiskImage, LinuxDiskImage
| Symbol |
Purpose |
mount(target) |
Context manager that mounts target and yields the mount point. |
extract(target, dest) |
Extract contents of target into dest. |
archive(src, dest, type) |
Build an archive of src at dest. |
Mountable |
Base class for anything that can be mounted (loop devices, archives). |
Archive |
Mountable subclass for archive formats. |
MountableType, ArchiveType |
Enums of supported types. |
DiskImage, LinuxDiskImage |
Concrete Mountable for raw/Linux disk images (uses udisksctl). |
