Skip to content

README.md

Latest commit

 

History

History
104 lines (74 loc) · 4.35 KB

README.md

File metadata and controls

104 lines (74 loc) · 4.35 KB

kaparoo-python

PyPI version Downloads Python License: MIT uv Ruff ty Copier

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, wired to the kaparoo.filters DSL via part_filter / name_filter / predicate, with depth control and a deprecated get_* family.

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. The Expandable filters (Literal, OneOf, Template) also enumerate their names via expand. A representation layer (name-level matches / expand); the disk operations it is designed to drive are still to come.

kaparoo.filters

A declarative, composable string-matching DSL: a Filter family (pattern, multi-pattern, logical, and enumerable Literal / OneOf / Template) that round-trips through JSON-friendly dicts, plus an extension hook for custom filter kinds. 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; experimental); 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, TransformedSequence, WindowedSequence, ZippedSequence), file-backed templates (FileFolderSequence, FileListSequence, SingleFileSequence), and generate_batches.

🎯 Quick example

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

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.