kaparoo-python

Personally common and useful Python features.

📦 Installation

Requires Python 3.13 or newer.

# With uv (recommended)
uv add kaparoo-python

# With pip
pip install kaparoo-python

🧩 Modules

Each submodule ships its own README with focused examples.

kaparoo.filesystem

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 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.

kaparoo.filesystem.search

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).

kaparoo.filesystem.hierarchy

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). nested_dirs builds one Directory per tier of a repeating tree from a list of levels.

kaparoo.filters

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.

kaparoo.utils

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, ...).

kaparoo.data

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.

🎯 Quick example

Search 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 unexpected

See each submodule's README for more.

📋 TODO

See TODO.md for tracked open items.

📜 Changelog

See CHANGELOG.md for the version history.

⚖️ License

This project is distributed under the terms of the MIT license.