Personally common and useful Python features
Requires Python 3.13 or newer.
# With uv (recommended)
uv add kaparoo-python
# With pip
pip install kaparoo-pythonSearch a tree with composable filters:
from kaparoo.filesystem import search_files
from kaparoo.filters import And, EndsWith, Equals, Not
# All .py files except __init__.py
py_files = search_files(
"src",
name_filter=And((EndsWith(".py"), Not(Equals("__init__.py")))),
)…or describe a tree declaratively and check a directory against it:
from kaparoo.filesystem.hierarchy import Directory, File, validate
from kaparoo.filters import Glob
spec = Directory("dataset", [
File("metadata.json"),
Directory("images", [File(Glob("*.png"))]),
])
report = validate(spec, "data/dataset", root_as_top=True)
assert report.ok # required entries present, nothing unexpectedSee each submodule's README for more.
Each submodule ships its own README with focused examples.
pathlib-based filesystem helpers: existence checks (*_exists), the
contains(subpath) predicate factory, ensure_* validators,
make_dir(s) (with a destructive clean reset option), prune_upward
for upward empty-parent removal, dir_empty(s), reserve_path(s)
guards for not-yet-existing destinations, StagedFile /
StagedDirectory for safe (atomic) writes (with CommitRetry to ride
out transient Windows locks, and STAGING to collect what an
interrupted run left behind), path stringification, extension helpers
(ensure_file_extension, file_extension, normalize_extension(s)),
and a small exception hierarchy.
Filesystem traversal with composable filters: search_paths /
search_files / search_dirs, wired to the kaparoo.filters DSL via
part_filter / name_filter / predicate, with min_depth /
max_depth control, a subtree-pruning exclude, a walk-narrowing
descend, and a SearchKwargs bundle for forwarding the shared
keywords; plus a path-aware select that filters an already-gathered
collection by an include / exclude name spec (exact subpaths,
.json / .txt files, patterns, or filters).
A declarative description of a filesystem tree: File / Directory
nodes whose names are drawn from the kaparoo.filters DSL (so one node
can stand for many regularly-named siblings), plus Exclusive /
Together constraints and per-node attribute conditions. It drives
four disk operations: locate (map on-disk paths to spec nodes),
validate (check a directory against the spec), conformer (build a
search predicate from a spec), and scaffold (create the tree on
disk). blueprint lists what scaffold would create, from the spec
alone, and nested_dirs builds one Directory per tier of a repeating
tree from a list of levels.
A declarative, composable string-matching DSL: a Filter family
(pattern, multi-pattern, logical, constant Any, and enumerable
Literal / OneOf / Template) that round-trips through JSON-friendly
dicts, plus an extension hook for custom filter kinds; and select /
resolve_selector, which filter a collection by an include /
exclude name spec. Used by kaparoo.filesystem.search for path
matching and kaparoo.filesystem.hierarchy for declaring trees.
Timer / SpanTimer context-manager-and-decorator timers (with
lap-split and measure-block timings); Aggregator for nested,
pluggable metric aggregation (the batch → epoch → run pattern);
ensure_one_of / ensure_in_range validation guards; resolve_enum /
literal_values for config-driven Enum / Literal sets; quantify
for pluralized counts and strrange for formatted number series; plus
helpers for Optional[T] values (replace_if_none,
unwrap_or_default, ...).
Building blocks for dataset code: DataSequence[T, M] ABC (item +
metadata), composers (SlicedSequence, ConcatSequence,
TransformedSequence, WindowedSequence, ZippedSequence),
file-backed templates (FileFolderSequence, FileListSequence,
SingleFileSequence), and generate_batches.
See TODO.md for tracked open items.
See CHANGELOG.md for the version history.
This project is distributed under the terms of the MIT license.