kaparoo-python 0.8.0__tar.gz → 0.9.0__tar.gz

{kaparoo_python-0.8.0 → kaparoo_python-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kaparoo-python
-Version: 0.8.0
+Version: 0.9.0
 Summary: Personally common and useful Python features
 Keywords: filesystem,pathlib,paths,glob,filters,pattern-matching,dataset,sequence,batching,timer,aggregation,metrics,utilities,typed
 Author: Jaewoo Park
@@ -61,7 +61,8 @@ Each submodule ships its own README with focused examples.
 `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.
+path stringification, extension helpers (`ensure_file_extension`,
+`file_extension`, `normalize_extension(s)`), and a small exception hierarchy.
 
 ### [`kaparoo.filesystem.search`](https://github.com/kaparoo/kaparoo-python/tree/main/kaparoo/filesystem/search)
 

{kaparoo_python-0.8.0 → kaparoo_python-0.9.0}/README.md

@@ -33,7 +33,8 @@ Each submodule ships its own README with focused examples.
 `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.
+path stringification, extension helpers (`ensure_file_extension`,
+`file_extension`, `normalize_extension(s)`), and a small exception hierarchy.
 
 ### [`kaparoo.filesystem.search`](https://github.com/kaparoo/kaparoo-python/tree/main/kaparoo/filesystem/search)
 

{kaparoo_python-0.8.0 → kaparoo_python-0.9.0}/kaparoo/data/sequences/composers.py

@@ -150,10 +150,11 @@ class TransformedSequence[T_in, M_in, T_out = T_in, M_out = M_in](
 
     @override
     def get_meta(self, index: int) -> M_out:
-        """Pass `source`'s metadata through unchanged (valid only when `M_out == M_in`)."""
-        # Passthrough -- correct only when M_out == M_in. A subclass with a
-        # different M_out MUST override this; the cast cannot catch a missing
-        # override, since generics are erased at runtime.
+        """Pass `source`'s metadata through unchanged.
+
+        A subclass whose `M_out` differs from `M_in` must override this.
+        """
+        # The cast cannot catch a missing override -- generics are erased at runtime.
         return cast("M_out", self._source.get_meta(index))
 
 

{kaparoo_python-0.8.0 → kaparoo_python-0.9.0}/kaparoo/data/sequences/templates.py

@@ -46,7 +46,7 @@ class FileListSequence[T, M = Path](DataSequence[T, M]):
 
     @cached_property
     def files(self) -> tuple[Path, ...]:
-        """Immutable snapshot of the full file paths, in order (built once)."""
+        """Immutable snapshot of the full file paths, in order."""
         return tuple(self.get_file(i) for i in range(len(self)))
 
     def get_file(self, index: int) -> Path:
@@ -130,7 +130,7 @@ class FileFolderSequence[T, M = Path](FileListSequence[T, M]):
 
     @abstractmethod
     def list_files(self, root: Path) -> list[Path]:
-        """Return the full Path of every file to expose, in order.
+        """Return the full `Path` of every file to expose, in order.
 
         Called once from `__init__` after `root` has been validated.
         Every returned path must be under `root`; construction raises

{kaparoo_python-0.8.0 → kaparoo_python-0.9.0}/kaparoo/filesystem/README.md

@@ -9,6 +9,7 @@
 - [Exception hierarchy](#exception-hierarchy)
 - [Creating and emptying directories](#creating-and-emptying-directories)
 - [Path manipulation](#path-manipulation)
+- [Extensions](#extensions)
 - [Reserving a destination](#reserving-a-destination)
 - [Safe (atomic) writes](#safe-atomic-writes)
 - [Platform notes](#platform-notes)
@@ -22,10 +23,12 @@
   `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)`, `ensure_file_extension`
+  `reserve_path(s)`, and the extension helpers `ensure_file_extension` /
+  `file_extension` / `normalize_extension(s)`
 - [`staged`](./staged.py) — `StagedFile` / `StagedDirectory`, safe
   (atomic) writers usable as a context manager or explicitly
-- [`exceptions`](./exceptions.py) — `DirectoryNotFoundError`, `NotAFileError`
+- [`exceptions`](./exceptions.py) — `DirectoryNotFoundError`, `NotAFileError`,
+  `UnsupportedExtensionError`
 - [`types`](./types.py) — `StrPath`, `StrPaths` type aliases
 - [`units`](./units.py) — byte-size multipliers (`KB` / `MB` / `GB` / `TB`,
   `KIB` / `MIB` / `GIB` / `TIB`)
@@ -78,6 +81,10 @@ except FileNotFoundError:  # catches DirectoryNotFoundError too
     ...
 ```
 
+`UnsupportedExtensionError` (raised by `ensure_file_extension`, see
+[Extensions](#extensions)) likewise subclasses `ValueError`, so an
+`except ValueError` catches it.
+
 ## Creating and emptying directories
 
 ```python
@@ -136,25 +143,49 @@ stringify_paths(["data/a.txt", "data/b.txt"], after="data")  # ["a.txt", "b.txt"
 wrap_path("logs", prepend="var", append="server.log")  # var/logs/server.log
 ```
 
+## Extensions
+
+`normalize_extension` cleans up an extension string — it strips surrounding
+whitespace and leading dots, keeping case unless `lowercase=True`.
+`normalize_extensions` maps it over an iterable (empties and duplicates are
+deliberately kept — that policy is the caller's). `file_extension` reads a
+path's trailing suffix(es): the last `level` of them, dot-joined and
+normalized (lower-cased by default).
+
+```python
+from kaparoo.filesystem import (
+    file_extension, normalize_extension, normalize_extensions,
+)
+
+normalize_extension("  .TAR ")                          # "TAR" (case kept)
+normalize_extension(".PNG", lowercase=True)             # "png"
+normalize_extensions([".jpg", "PNG"], lowercase=True)   # ["jpg", "png"]
+
+file_extension("photo.JPG")                             # "jpg" (lower-cased)
+file_extension("data.tar.gz", level=2)                  # "tar.gz"
+file_extension("README")                                # ""    (no suffix)
+```
+
 `ensure_file_extension` is a pure (no filesystem) extension check: it
-requires a `.<ext>` final suffix, raising `ValueError` otherwise. `ext` may
-be a single extension or an iterable of acceptable ones; the leading dot is
-optional and the match is case-insensitive. `add=True` mirrors `make` on
-`ensure_dir_exists` — it appends the (first) extension when the path has no
-suffix (`np.save`-style) instead of raising; a *wrong* suffix still raises.
+requires a `.<ext>` final suffix, raising `UnsupportedExtensionError` (a
+`ValueError` subclass) otherwise. `ext` may be a single extension or an
+iterable of acceptable ones; the leading dot is optional and the match is
+case-insensitive. `add=True` mirrors `make` on `ensure_dir_exists` — it
+appends the (first) extension when the path has no suffix (`np.save`-style)
+instead of raising; a *wrong* suffix still raises.
 
 ```python
 from kaparoo.filesystem import ensure_file_extension
 
 ensure_file_extension("data.bin", "bin")             # Path("data.bin")
-ensure_file_extension("data.txt", "bin")             # ValueError
-ensure_file_extension("out/00000_phase", "bin")      # ValueError (no suffix)
+ensure_file_extension("data.txt", "bin")             # UnsupportedExtensionError
+ensure_file_extension("out/00000_phase", "bin")      # UnsupportedExtensionError (no suffix)
 
 # Any of several accepted extensions:
 ensure_file_extension("img.jpeg", ("jpg", "jpeg", "png"))  # Path("img.jpeg")
 
 ensure_file_extension("out/00000_phase", "bin", add=True)  # Path("out/00000_phase.bin")
-ensure_file_extension("out/data.txt", "bin", add=True)     # ValueError (wrong suffix)
+ensure_file_extension("out/data.txt", "bin", add=True)     # UnsupportedExtensionError (wrong suffix)
 ```
 
 ## Reserving a destination

{kaparoo_python-0.8.0 → kaparoo_python-0.9.0}/kaparoo/filesystem/__init__.py

@@ -3,6 +3,7 @@ __all__ = (
     "NotAFileError",
     "StagedDirectory",
     "StagedFile",
+    "UnsupportedExtensionError",
     "dir_empty",
     "dir_empty_unsafe",
     "dir_exists",
@@ -21,9 +22,12 @@ __all__ = (
     "ensure_path_exists",
     "ensure_paths_exist",
     "file_exists",
+    "file_extension",
     "files_exist",
     "make_dir",
     "make_dirs",
+    "normalize_extension",
+    "normalize_extensions",
     "path_exists",
     "paths_exist",
     "reserve_path",
@@ -49,7 +53,11 @@ from kaparoo.filesystem.directory import (
     make_dir,
     make_dirs,
 )
-from kaparoo.filesystem.exceptions import DirectoryNotFoundError, NotAFileError
+from kaparoo.filesystem.exceptions import (
+    DirectoryNotFoundError,
+    NotAFileError,
+    UnsupportedExtensionError,
+)
 from kaparoo.filesystem.existence import (
     dir_exists,
     dirs_exist,
@@ -68,6 +76,9 @@ from kaparoo.filesystem.search import search_dirs, search_files, search_paths
 from kaparoo.filesystem.staged import StagedDirectory, StagedFile
 from kaparoo.filesystem.utils import (
     ensure_file_extension,
+    file_extension,
+    normalize_extension,
+    normalize_extensions,
     reserve_path,
     reserve_paths,
     stringify_path,

{kaparoo_python-0.8.0 → kaparoo_python-0.9.0}/kaparoo/filesystem/directory.py

@@ -243,7 +243,7 @@ def make_dirs(
 
 
 def dir_empty_unsafe(path: StrPath) -> bool:
-    """Check if a directory is empty, skipping the existence check.
+    """Test whether a directory is empty, skipping the existence check.
 
     The caller must guarantee `path` is an existing directory; otherwise the
     underlying `os.scandir` raises (`FileNotFoundError`, `NotADirectoryError`).
@@ -253,7 +253,7 @@ def dir_empty_unsafe(path: StrPath) -> bool:
 
 
 def dirs_empty_unsafe(paths: StrPaths, *, root: StrPath | None = None) -> bool:
-    """Check if directories are empty, skipping existence checks.
+    """Test whether directories are empty, skipping existence checks.
 
     Each path carries the same caller obligation as `dir_empty_unsafe`.
     """
@@ -261,7 +261,7 @@ def dirs_empty_unsafe(paths: StrPaths, *, root: StrPath | None = None) -> bool:
 
 
 def dir_empty(path: StrPath) -> bool:
-    """Check if a directory is empty.
+    """Test whether a directory is empty.
 
     Args:
         path: The directory path to check.
@@ -278,7 +278,7 @@ def dir_empty(path: StrPath) -> bool:
 
 
 def dirs_empty(paths: StrPaths, *, root: StrPath | None = None) -> bool:
-    """Check if directories are empty.
+    """Test whether directories are empty.
 
     Args:
         paths: A sequence of directory paths to check.
@@ -299,7 +299,7 @@ def dirs_empty(paths: StrPaths, *, root: StrPath | None = None) -> bool:
 
 
 def dir_not_empty_unsafe(path: StrPath) -> bool:
-    """Check if a directory is not empty, skipping the existence check.
+    """Test whether a directory is not empty, skipping the existence check.
 
     Same caller obligation as `dir_empty_unsafe`.
     """
@@ -307,7 +307,7 @@ def dir_not_empty_unsafe(path: StrPath) -> bool:
 
 
 def dirs_not_empty_unsafe(paths: StrPaths, *, root: StrPath | None = None) -> bool:
-    """Check if directories are not empty, skipping existence checks.
+    """Test whether directories are not empty, skipping existence checks.
 
     Each path carries the same caller obligation as `dir_empty_unsafe`.
     """
@@ -315,7 +315,7 @@ def dirs_not_empty_unsafe(paths: StrPaths, *, root: StrPath | None = None) -> bo
 
 
 def dir_not_empty(path: StrPath) -> bool:
-    """Check if a directory is not empty.
+    """Test whether a directory is not empty.
 
     Args:
         path: The directory path to check.
@@ -332,7 +332,7 @@ def dir_not_empty(path: StrPath) -> bool:
 
 
 def dirs_not_empty(paths: StrPaths, *, root: StrPath | None = None) -> bool:
-    """Check if directories are not empty.
+    """Test whether directories are not empty.
 
     Args:
         paths: A sequence of directory paths to check.

kaparoo_python-0.9.0/kaparoo/filesystem/exceptions.py

@@ -0,0 +1,67 @@
+"""Filesystem exception types (`NotAFileError`, `UnsupportedExtensionError`, ...)."""
+
+from __future__ import annotations
+
+__all__ = (
+    "DirectoryNotFoundError",
+    "NotAFileError",
+    "UnsupportedExtensionError",
+)
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+
+class DirectoryNotFoundError(FileNotFoundError):
+    """Raised when a directory does not exist.
+
+    Note:
+        Since this inherits from `FileNotFoundError`, catch it before
+        `FileNotFoundError` in any combined `except` block.
+    """
+
+
+class NotAFileError(OSError):
+    """Raised when a path exists but is not a file."""
+
+
+class UnsupportedExtensionError(ValueError):
+    """Raised when an extension is none of the supported ones.
+
+    A `ValueError` subclass, so existing `except ValueError` handlers still
+    catch it. `ext` and each entry of `supported` are normalized alike --
+    surrounding whitespace and leading dots are stripped, with case preserved
+    -- after which `supported` is de-duplicated and empty entries are dropped
+    (so `".jpg"`, `"jpg "`, and `"jpg"` collapse to a single `"jpg"`). The
+    optional `kind` (whitespace-stripped) names what the extension is for and,
+    when given, is woven into the message as `for <kind>`.
+
+    Raises:
+        ValueError: If `supported` names no usable extension -- empty, or
+            every entry normalizes to "".
+    """
+
+    def __init__(self, ext: str, supported: Iterable[str], kind: str = "") -> None:
+        def normalize(ext: str) -> str:
+            return ext.strip().lstrip(".")
+
+        supported = (normalize(ext) for ext in supported)
+        supported = tuple(dict.fromkeys(ext for ext in supported if ext))
+        if not supported:
+            msg = "supported must list at least one extension"
+            raise ValueError(msg)
+
+        self.ext = normalize(ext)
+        self.supported = supported
+        self.kind = kind.strip()
+
+        msg = f"unsupported extension {self.ext!r}"
+
+        if self.kind:
+            msg += f" for {self.kind}"
+
+        msg += f" (supported: {', '.join(repr(ext) for ext in self.supported)})"
+
+        super().__init__(msg)

{kaparoo_python-0.8.0 → kaparoo_python-0.9.0}/kaparoo/filesystem/existence.py

@@ -63,7 +63,7 @@ def ensure_path_exists(path: StrPath, *, stringify: bool) -> Path | str: ...
 
 
 def ensure_path_exists(path: StrPath, *, stringify: bool = False) -> Path | str:
-    """Check if a given path exists and return it.
+    """Ensure a given path exists and return it.
 
     Args:
         path: The path to check for existence.
@@ -94,7 +94,7 @@ def ensure_file_exists(path: StrPath, *, stringify: bool) -> Path | str: ...
 
 
 def ensure_file_exists(path: StrPath, *, stringify: bool = False) -> Path | str:
-    """Check if a given path exists and is a file, and return it.
+    """Ensure a given path exists and is a file, and return it.
 
     Args:
         path: The file path to check for existence.
@@ -146,7 +146,7 @@ def ensure_dir_exists(
 def ensure_dir_exists(
     path: StrPath, *, make: bool | int = False, stringify: bool = False
 ) -> Path | str:
-    """Check if a given path exists and is a directory, and return it.
+    """Ensure a given path exists and is a directory, and return it.
 
     Args:
         path: The directory path to check for existence.
@@ -269,7 +269,7 @@ def ensure_paths_exist(
 def ensure_paths_exist(
     paths: StrPaths, *, root: StrPath | None = None, stringify: bool = False
 ) -> list[Path] | list[str]:
-    """Check if all of the given paths exist and return them.
+    """Ensure all of the given paths exist and return them.
 
     Args:
         paths: The paths to check for existence.
@@ -311,7 +311,7 @@ def ensure_files_exist(
 def ensure_files_exist(
     paths: StrPaths, *, root: StrPath | None = None, stringify: bool = False
 ) -> list[Path] | list[str]:
-    """Check if all of the given paths exist and are files, and return them.
+    """Ensure all of the given paths exist and are files, and return them.
 
     Args:
         paths: The file paths to check for existence.
@@ -370,7 +370,7 @@ def ensure_dirs_exist(
     make: bool | int = False,
     stringify: bool = False,
 ) -> list[Path] | list[str]:
-    """Check if all of the given paths exist and are directories, and return them.
+    """Ensure all of the given paths exist and are directories, and return them.
 
     Args:
         paths: The directory paths to check for existence.

{kaparoo_python-0.8.0 → kaparoo_python-0.9.0}/kaparoo/filesystem/hierarchy/README.md

@@ -630,9 +630,32 @@ cannot be satisfied and raises. `Together` creates all its members
 Files are created **empty** (the skeleton, not its contents). Creation is
 **idempotent**: an existing directory is descended unchanged and an existing
 file is never clobbered, so only newly created paths are returned and a
-re-run is a no-op. A path that exists with the wrong kind (a file where a
-directory is described, or vice versa) is a conflict and raises. `dry_run`
-runs every check but no write, returning the paths that *would* be created.
+re-run is a no-op. A path that exists with the wrong kind raises
+`NotADirectoryError` (a file where a directory is described) or `NotAFileError`
+(a directory where a file is described). `dry_run` runs every check but no
+write, returning the paths that *would* be created.
+
+Failure is **best-effort**: a mid-run raise — a conflict, an unsatisfiable
+`required` node, or an `on_create` callback that raises — leaves the paths
+already created in place. There is no rollback, but because creation is
+idempotent a re-run resumes safely.
+
+Two options shape what gets written. **`on_create`** is a callback run once
+for each file *actually* created — `on_create(path, file_node)`, the seam for
+writing a file's content (scaffold only makes the skeleton). It is not called
+for an untouched existing file, under `dry_run`, or with `dirs_only`.
+**`dirs_only=True`** writes only the directory skeleton, skipping every file
+(including `required` ones); pairing it with `on_create` raises `ValueError`.
+
+```python
+# Fill each created file from its spec node, then build the tree.
+def fill(path, node):
+    if path.name == "README.md":
+        path.write_text("# Project\n")
+
+scaffold(spec, "/tmp/out", on_create=fill)
+scaffold(spec, "/tmp/out", dirs_only=True)   # directories only, no files
+```
 
 ## See also
 

{kaparoo_python-0.8.0 → kaparoo_python-0.9.0}/kaparoo/filesystem/hierarchy/entry.py

@@ -205,6 +205,16 @@ class Entry(Node, ABC):
         """The deepest level below the parent (`None` is unbounded)."""
         return self._depth[1]
 
+    @property
+    def is_direct_child(self) -> bool:
+        """Whether the entry is pinned to exactly depth 1 (a direct child).
+
+        True only when `min_depth` and `max_depth` are both 1 -- the default,
+        unranged position. Any wider or deeper depth (`depth=2`, `depth=None`,
+        `depth=(1, 3)`, ...) is False.
+        """
+        return self.min_depth == 1 and self.max_depth == 1
+
     @property
     def required(self) -> bool:
         """Whether this entry must be present (vs optional)."""
@@ -256,7 +266,7 @@ class Entry(Node, ABC):
         `Filter` / `Condition` `_payload`, which is the *whole* field set.
         """
         payload: dict[str, Any] = {}
-        if self._depth != (1, 1):
+        if not self.is_direct_child:
             payload["depth"] = list(self._depth)
         if self._required:
             payload["required"] = True