kaparoo-python

Personally common and useful Python features.

📦 Installation

Requires Python 3.14+.

# 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), ensure_* validators, make_dir(s) (with a destructive clean reset option), dir_empty(s), reserve_path(s) guards for not-yet-existing destinations, StagedFile / StagedDirectory for safe (atomic) writes, path stringification, and a small exception hierarchy.

kaparoo.filesystem.search

Filesystem traversal with composable filters. Includes search_paths / search_files / search_dirs, a Filter family (pattern, multi-pattern, logical) that round-trips through JSON-friendly dicts, and an extension hook for custom filter kinds.

kaparoo.utils

Timer / SegmentTimer context-manager-and-decorator timers (with lap-split and measure-block timings); Aggregator for nested, pluggable metric aggregation (the batch → epoch → run pattern); plus a small family of helpers for working with 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, WindowedSequence), file-backed templates (FileFolderSequence, SingleFileSequence), and generate_batches.

🎯 Quick example

from kaparoo.filesystem import search_files
from kaparoo.filesystem.search.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")))),
)

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.