kaparoo-python 0.3.0__tar.gz → 0.4.0__tar.gz

{kaparoo_python-0.3.0 → kaparoo_python-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kaparoo-python
-Version: 0.3.0
+Version: 0.4.0
 Summary: Personally common and useful Python features
 Keywords: filesystem,pathlib,paths,utilities
 Author: Jaewoo Park
@@ -51,8 +51,10 @@ Each submodule ships its own README with focused examples.
 ### [`kaparoo.filesystem`](https://github.com/kaparoo/kaparoo-python/tree/main/kaparoo/filesystem)
 
 `pathlib`-based filesystem helpers: existence checks (`*_exists`),
-`ensure_*` validators, `make_dir(s)`, `dir_empty(s)`, path
-stringification, and a small exception hierarchy.
+`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`](https://github.com/kaparoo/kaparoo-python/tree/main/kaparoo/filesystem/search)
 
@@ -63,8 +65,10 @@ hook for custom filter kinds.
 
 ### [`kaparoo.utils`](https://github.com/kaparoo/kaparoo-python/tree/main/kaparoo/utils)
 
-`Timer` / `LapTimer` context-manager-and-decorator timers, plus a small
-family of helpers for working with `Optional[T]` values
+`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`](https://github.com/kaparoo/kaparoo-python/tree/main/kaparoo/data)

{kaparoo_python-0.3.0 → kaparoo_python-0.4.0}/README.md

@@ -30,8 +30,10 @@ Each submodule ships its own README with focused examples.
 ### [`kaparoo.filesystem`](https://github.com/kaparoo/kaparoo-python/tree/main/kaparoo/filesystem)
 
 `pathlib`-based filesystem helpers: existence checks (`*_exists`),
-`ensure_*` validators, `make_dir(s)`, `dir_empty(s)`, path
-stringification, and a small exception hierarchy.
+`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`](https://github.com/kaparoo/kaparoo-python/tree/main/kaparoo/filesystem/search)
 
@@ -42,8 +44,10 @@ hook for custom filter kinds.
 
 ### [`kaparoo.utils`](https://github.com/kaparoo/kaparoo-python/tree/main/kaparoo/utils)
 
-`Timer` / `LapTimer` context-manager-and-decorator timers, plus a small
-family of helpers for working with `Optional[T]` values
+`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`](https://github.com/kaparoo/kaparoo-python/tree/main/kaparoo/data)

kaparoo_python-0.4.0/kaparoo/filesystem/README.md

@@ -0,0 +1,230 @@
+# `kaparoo.filesystem`
+
+`pathlib`-based filesystem helpers.
+
+## Modules
+
+- [`existence`](./existence.py) — boolean predicates (`*_exists`) and
+  validating `ensure_*` variants
+- [`directory`](./directory.py) — `make_dir(s)`, `dir_empty(s)` /
+  `dir_not_empty(s)` with validation, plus `_unsafe` variants that skip
+  pre-checks
+- [`utils`](./utils.py) — `stringify_path(s)`, `wrap_path(s)`,
+  `reserve_path(s)`
+- [`staged`](./staged.py) — `StagedFile` / `StagedDirectory`, safe
+  (atomic) writers usable as a context manager or explicitly
+- [`exceptions`](./exceptions.py) — `DirectoryNotFoundError`, `NotAFileError`
+- [`types`](./types.py) — `StrPath`, `StrPaths` type aliases
+- [`search/`](./search/) — composable filesystem search (own README)
+
+All public symbols are re-exported from the top-level `kaparoo.filesystem`
+namespace.
+
+## Existence checks
+
+`*_exists` return a bool; `ensure_*` raise on failure and return the
+(optionally stringified) path.
+
+```python
+from kaparoo.filesystem import (
+    dir_exists, ensure_dir_exists, ensure_files_exist, file_exists,
+)
+
+if file_exists("config.toml"):
+    ...
+
+# Single path: raises FileNotFoundError / NotAFileError / NotADirectoryError
+config = ensure_dir_exists("var/cache", make=True)  # create if missing
+report = ensure_dir_exists("var/cache", make=0o755)  # mode bits: POSIX only
+
+# Bulk with a shared root; each entry is resolved relative to it.
+files = ensure_files_exist(
+    ["a.txt", "b.txt"],
+    root="data",
+)
+```
+
+## Exception hierarchy
+
+`DirectoryNotFoundError` subclasses `FileNotFoundError`, so callers may
+catch the broader type:
+
+```python
+from kaparoo.filesystem import DirectoryNotFoundError, ensure_dir_exists
+
+try:
+    ensure_dir_exists("var/missing")
+except FileNotFoundError:  # catches DirectoryNotFoundError too
+    ...
+```
+
+## Creating and emptying directories
+
+```python
+from kaparoo.filesystem import (
+    dir_empty, dir_not_empty, dirs_empty, make_dir, make_dirs,
+)
+
+cache_dir = make_dir("var/cache", exist_ok=True)
+
+# Start from a clean slate: wipe an existing directory's contents and
+# recreate it empty. Destructive, and only ever wipes a *directory* (a
+# non-directory at the path still raises). `clean=True` makes `exist_ok`
+# moot, since the directory is removed and remade.
+run_dir = make_dir("out/run_42", clean=True)
+
+# Bulk creation with a shared root
+make_dirs(["logs", "tmp"], root="var", exist_ok=True)
+
+# Empty checks (raise if missing or not a directory)
+assert dir_empty(cache_dir)
+assert dirs_empty(["logs", "tmp"], root="var")
+
+# ...and their negations
+(cache_dir / "data.bin").touch()
+assert dir_not_empty(cache_dir)
+```
+
+Each check has a negated counterpart (`dir_not_empty`, `dirs_not_empty`);
+`dirs_not_empty` is True only when *every* directory is non-empty. The
+`_unsafe` variants (`dir_empty_unsafe`, `dir_not_empty_unsafe`,
+`dirs_empty_unsafe`, `dirs_not_empty_unsafe`) skip existence/type
+validation and are intended for hot paths where the caller has already
+validated.
+
+## Path manipulation
+
+`stringify_path(s)` converts to forward-slash strings, optionally
+trimming a leading or trailing portion. `wrap_path(s)` prepends and/or
+appends path components, rejecting absolute inputs where ambiguous.
+
+```python
+from pathlib import Path
+from kaparoo.filesystem import stringify_path, stringify_paths, wrap_path
+
+# "path/to/file.txt" on every platform (including Windows)
+stringify_path(Path("path") / "to" / "file.txt")
+
+# Trim leading or trailing components
+stringify_path("a/b/c", after="a")     # "b/c"
+stringify_path("a/b/c", before="c")    # "a/b"
+
+# Bulk stringify with a shared base.
+stringify_paths(["data/a.txt", "data/b.txt"], after="data")  # ["a.txt", "b.txt"]
+
+# Compose paths without joining manually
+wrap_path("logs", prepend="var", append="server.log")  # var/logs/server.log
+```
+
+## Reserving a destination
+
+`reserve_path` guards a path that should *not* yet exist, so you don't
+clobber something when creating a new file or directory there. It only
+checks (and optionally creates the parent) — it never creates or deletes
+the target itself.
+
+```python
+from kaparoo.filesystem import reserve_path
+
+# Raises FileExistsError if out/run.json exists; otherwise creates the
+# missing parent directory and returns the path ready to write to.
+out = reserve_path("out/run.json", make_parents=True)
+out.write_text("{}")
+
+# `exist_ok` (named as in make_dir / Path.mkdir) is a non-destructive
+# bypass: it suppresses the conflict but deletes nothing, so a later write
+# overwrites in place.
+out = reserve_path("out/run.json", exist_ok=True)
+
+# `reserve_paths` is the bulk form (fail-fast on the first conflict). It
+# takes no `root`; compose with `wrap_paths` to share a base directory.
+from kaparoo.filesystem import reserve_paths, wrap_paths
+a, b = reserve_paths(wrap_paths(["a.bin", "b.bin"], prepend="out"))
+```
+
+For a *directory* destination, `make_dir(..., exist_ok=...)` both guards
+and creates it; for an exclusive *file* create, the stdlib `open(path,
+"x")` raises the same `FileExistsError` directly. Reach for `reserve_path`
+when you want the check (and parent setup) decoupled from the creation.
+
+`reserve_path` is intentionally **non-destructive** — it never removes an
+existing target. To start a directory from a clean slate, use the
+`clean` option on `make_dir` / `make_dirs` (see below), which is the only
+destructive operation here and is named to say so.
+
+## Safe (atomic) writes
+
+`StagedFile` saves a file safely: it stages the content in a temporary file
+in the destination's own directory and moves it into place only on commit.
+A reader never sees a half-written file, and a failed write leaves any
+existing file untouched. It works as a context manager — commit on a clean
+exit, discard on an exception — or explicitly, like a file object.
+
+```python
+from kaparoo.filesystem import StagedFile
+
+# Text (the default), as a context manager: commit on success, discard
+# on error.
+with StagedFile("out/report.json", encoding="utf-8") as f:
+    f.write(json.dumps(data))  # an exception here leaves out/ untouched
+
+# Binary mode, explicitly: write, then commit (or abort to discard).
+f = StagedFile("out/data.bin", binary=True)
+f.write(payload)
+f.commit()  # returns the destination Path; idempotent
+```
+
+The default is text (`StagedFile[str]`) with optional `encoding` / `newline`,
+as with `open`; pass `binary=True` for a binary writer (`StagedFile[bytes]`).
+The type parameter follows the mode, so `write` and `file` are typed `str`
+or `bytes` accordingly.
+
+With `overwrite=False` (the default) an existing destination raises
+`FileExistsError` up front, and the commit creates the file atomically —
+never clobbering a file that appeared meanwhile. With `overwrite=True` the
+destination is replaced in one atomic step, keeping its previous
+permissions. Pass `make_parents=True` to create the destination's parent
+directory if it is missing. An uncommitted writer (an explicit instance
+dropped without `commit()`) discards its staged file on garbage collection,
+so a partial write is never promoted by accident.
+
+The committed file gets the usual umask-based permissions.
+
+`StagedDirectory` is the directory counterpart: you populate its `workdir`
+(a temporary directory in the destination's parent) and it is moved into
+place on commit.
+
+```python
+from kaparoo.filesystem import StagedDirectory
+
+with StagedDirectory("out/dataset", make_parents=True) as d:
+    (d.workdir / "train.json").write_text(payload)
+    (d.workdir / "shards").mkdir()
+# out/dataset appears in one step; an exception would leave it absent
+```
+
+Creating a new directory (`overwrite=False`) is atomic — a single rename.
+Replacing an existing one (`overwrite=True`) is *not* fully atomic: the old
+directory is swapped aside and removed, so there is a brief window where the
+destination is absent and, on a rare failure mid-swap, the previous contents
+remain in a sibling `<name>.old` directory for recovery.
+
+## Platform notes
+
+- **Directory mode bits**: `mode` (on `make_dir` / `make_dirs`) and
+  `make=<int>` (on `ensure_dir_exists` / `ensure_dirs_exist`) are
+  validated against the `0o1`–`0o7777` range and applied to the created
+  directory on **POSIX systems only**. On Windows, mode values are still
+  accepted (so cross-platform code stays clean) but the range check is
+  skipped and the OS ignores the bits — see
+  [`os.mkdir`](https://docs.python.org/3/library/os.html#os.mkdir).
+- **Path separators**: `stringify_path` and `stringify_paths` normalize
+  backslashes to forward slashes on Windows. Functions that return
+  strings via `stringify=True` (`make_dir`, `ensure_dir_exists`,
+  `wrap_path`, ...) inherit this normalization. If you need a native
+  Windows path string, call `str(path)` directly on a `Path`.
+
+## See also
+
+- [`search/`](./search/) for filesystem traversal with filters
+- [`kaparoo.utils`](../utils/) for `Timer` and Optional helpers

{kaparoo_python-0.3.0 → kaparoo_python-0.4.0}/kaparoo/filesystem/__init__.py

@@ -1,12 +1,18 @@
 __all__ = (
     "DirectoryNotFoundError",
     "NotAFileError",
+    "StagedDirectory",
+    "StagedFile",
     "dir_empty",
     "dir_empty_unsafe",
     "dir_exists",
+    "dir_not_empty",
+    "dir_not_empty_unsafe",
     "dirs_empty",
     "dirs_empty_unsafe",
     "dirs_exist",
+    "dirs_not_empty",
+    "dirs_not_empty_unsafe",
     "ensure_dir_exists",
     "ensure_dirs_exist",
     "ensure_file_exists",
@@ -22,6 +28,8 @@ __all__ = (
     "make_dirs",
     "path_exists",
     "paths_exist",
+    "reserve_path",
+    "reserve_paths",
     "search_dirs",
     "search_files",
     "search_paths",
@@ -34,8 +42,12 @@ __all__ = (
 from kaparoo.filesystem.directory import (
     dir_empty,
     dir_empty_unsafe,
+    dir_not_empty,
+    dir_not_empty_unsafe,
     dirs_empty,
     dirs_empty_unsafe,
+    dirs_not_empty,
+    dirs_not_empty_unsafe,
     make_dir,
     make_dirs,
 )
@@ -65,7 +77,10 @@ from kaparoo.filesystem.search import (
     search_files,
     search_paths,
 )
+from kaparoo.filesystem.staged import StagedDirectory, StagedFile
 from kaparoo.filesystem.utils import (
+    reserve_path,
+    reserve_paths,
     stringify_path,
     stringify_paths,
     wrap_path,

{kaparoo_python-0.3.0 → kaparoo_python-0.4.0}/kaparoo/filesystem/directory.py

@@ -3,13 +3,18 @@ from __future__ import annotations
 __all__ = (
     "dir_empty",
     "dir_empty_unsafe",
+    "dir_not_empty",
+    "dir_not_empty_unsafe",
     "dirs_empty",
     "dirs_empty_unsafe",
+    "dirs_not_empty",
+    "dirs_not_empty_unsafe",
     "make_dir",
     "make_dirs",
 )
 
 import os
+import shutil
 from pathlib import Path
 from typing import TYPE_CHECKING, overload
 
@@ -39,6 +44,7 @@ def make_dir(
     *,
     mode: int = 0o777,
     exist_ok: bool = False,
+    clean: bool = False,
     stringify: Literal[False] = False,
 ) -> Path: ...
 
@@ -49,6 +55,7 @@ def make_dir(
     *,
     mode: int = 0o777,
     exist_ok: bool = False,
+    clean: bool = False,
     stringify: Literal[True],
 ) -> str: ...
 
@@ -59,6 +66,7 @@ def make_dir(
     *,
     mode: int = 0o777,
     exist_ok: bool = False,
+    clean: bool = False,
     stringify: bool,
 ) -> Path | str: ...
 
@@ -68,6 +76,7 @@ def make_dir(
     *,
     mode: int = 0o777,
     exist_ok: bool = False,
+    clean: bool = False,
     stringify: bool = False,
 ) -> Path | str:
     """Recursively create a directory.
@@ -77,6 +86,11 @@ def make_dir(
         mode: The mode to use when creating the directory. Defaults to 0o777.
         exist_ok: Whether to suppress OSError if the path already exists.
             Defaults to False.
+        clean: Whether to recreate the directory empty when it already exists,
+            removing its contents first. Only an existing *directory* is wiped;
+            a non-directory still raises. Because the directory is removed and
+            remade, `clean=True` makes `exist_ok` moot. **Destructive.**
+            Defaults to False.
         stringify: Whether to return the path as a string. Defaults to False.
 
     Returns:
@@ -87,13 +101,16 @@ def make_dir(
         ValueError: If `mode` is outside the range 0o1-0o7777
             (not checked on Windows, where the mode is ignored).
         NotADirectoryError: If the path exists but is not a directory.
-        OSError: If `exist_ok` is False and the path already exists.
+        OSError: If `exist_ok` is False, `clean` is False, and the path
+            already exists.
     """
     _validate_mode(mode)
     path = Path(path)
     if path.exists() and not path.is_dir():
         msg = f"not a directory: {path}"
         raise NotADirectoryError(msg)
+    if clean and path.is_dir():
+        shutil.rmtree(path)
     path.mkdir(mode=mode, parents=True, exist_ok=exist_ok)
     return stringify_path(path) if stringify else path
 
@@ -105,6 +122,7 @@ def make_dirs(
     root: StrPath | None = None,
     mode: int = 0o777,
     exist_ok: bool = False,
+    clean: bool = False,
     stringify: Literal[False] = False,
 ) -> Sequence[Path]: ...
 
@@ -116,6 +134,7 @@ def make_dirs(
     root: StrPath | None = None,
     mode: int = 0o777,
     exist_ok: bool = False,
+    clean: bool = False,
     stringify: Literal[True],
 ) -> Sequence[str]: ...
 
@@ -127,6 +146,7 @@ def make_dirs(
     root: StrPath | None = None,
     mode: int = 0o777,
     exist_ok: bool = False,
+    clean: bool = False,
     stringify: bool,
 ) -> Sequence[Path] | Sequence[str]: ...
 
@@ -137,6 +157,7 @@ def make_dirs(
     root: StrPath | None = None,
     mode: int = 0o777,
     exist_ok: bool = False,
+    clean: bool = False,
     stringify: bool = False,
 ) -> Sequence[Path] | Sequence[str]:
     """Recursively create directories.
@@ -147,6 +168,11 @@ def make_dirs(
         mode: The mode to use when creating the directories. Defaults to 0o777.
         exist_ok: Whether to suppress OSError if any of the paths already exist.
             Defaults to False.
+        clean: Whether to recreate each directory empty when it already exists,
+            removing its contents first. Only an existing *directory* is wiped;
+            a non-directory still raises. Because the directory is removed and
+            remade, `clean=True` makes `exist_ok` moot. **Destructive.**
+            Defaults to False.
         stringify: Whether to return the paths as strings. Defaults to False.
 
     Returns:
@@ -159,13 +185,16 @@ def make_dirs(
         DirectoryNotFoundError: If `root` is provided and does not exist.
         NotADirectoryError: If `root` is provided and is not a directory.
         ValueError: If `root` is provided and any of the paths are absolute.
-        OSError: If `exist_ok` is False and any of the paths already exist.
+        OSError: If `exist_ok` is False, `clean` is False, and any of the
+            paths already exist.
         OSError: If any of the paths are not directories.
     """
     _validate_mode(mode)
     paths = _join_root_if_provided(paths, root)
     directories = [Path(p) for p in paths]
     for directory in directories:
+        if clean and directory.is_dir():
+            shutil.rmtree(directory)
         directory.mkdir(mode=mode, parents=True, exist_ok=exist_ok)
     return stringify_paths(directories) if stringify else directories
 
@@ -224,3 +253,53 @@ def dirs_empty(paths: StrPaths, *, root: StrPath | None = None) -> bool:
     """
     paths = ensure_dirs_exist(paths, root=root)
     return all(dir_empty_unsafe(p) for p in paths)
+
+
+def dir_not_empty_unsafe(path: StrPath) -> bool:
+    """Check if a directory is not empty without existence checks."""
+    return not dir_empty_unsafe(path)
+
+
+def dirs_not_empty_unsafe(paths: StrPaths, *, root: StrPath | None = None) -> bool:
+    """Check if directories are not empty without existence checks."""
+    if root is not None:
+        paths = [Path(root) / p for p in paths]
+    return all(dir_not_empty_unsafe(p) for p in paths)
+
+
+def dir_not_empty(path: StrPath) -> bool:
+    """Check if a directory is not empty.
+
+    Args:
+        path: The directory path to check.
+
+    Returns:
+        True if the directory is not empty, False otherwise.
+
+    Raises:
+        DirectoryNotFoundError: If the path does not exist.
+        NotADirectoryError: If the path is not a directory.
+    """
+    path = ensure_dir_exists(path)
+    return dir_not_empty_unsafe(path)
+
+
+def dirs_not_empty(paths: StrPaths, *, root: StrPath | None = None) -> bool:
+    """Check if directories are not empty.
+
+    Args:
+        paths: A sequence of directory paths to check.
+        root: The root directory to prepend to each path. Defaults to None.
+
+    Returns:
+        True if all directories are not empty, False otherwise.
+
+    Raises:
+        DirectoryNotFoundError: If `root` is provided and does not exist.
+        DirectoryNotFoundError: If any of the paths do not exist.
+        NotADirectoryError: If `root` is provided and is not a directory.
+        NotADirectoryError: If any of the paths are not directories.
+        ValueError: If `root` is provided and any of the paths are absolute.
+    """
+    paths = ensure_dirs_exist(paths, root=root)
+    return all(dir_not_empty_unsafe(p) for p in paths)

{kaparoo_python-0.3.0 → kaparoo_python-0.4.0}/kaparoo/filesystem/search/classes.py

@@ -169,7 +169,7 @@ class Search(ABC):
 
         for dirpath, dirnames, filenames in root.walk():
             child_depth = len(dirpath.parts) - root_depth + 1
-            part = stringify_path(dirpath.relative_to(root))
+            part = stringify_path(dirpath, after=root)
 
             if child_depth >= min_depth and cls._filter_part(part, part_filter):
                 names = cls._select_names(dirnames, filenames)