kaparoo-python 0.5.0__tar.gz → 0.7.0__tar.gz

{kaparoo_python-0.5.0 → kaparoo_python-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kaparoo-python
-Version: 0.5.0
+Version: 0.7.0
 Summary: Personally common and useful Python features
 Keywords: filesystem,pathlib,paths,utilities
 Author: Jaewoo Park
@@ -65,18 +65,19 @@ hook for custom filter kinds.
 
 ### [`kaparoo.utils`](https://github.com/kaparoo/kaparoo-python/tree/main/kaparoo/utils)
 
-`Timer` / `SegmentTimer` context-manager-and-decorator timers (with
+`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); plus a
-small family of helpers for working with `Optional[T]` values
-(`replace_if_none`, `unwrap_or_default`, ...).
+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`](https://github.com/kaparoo/kaparoo-python/tree/main/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`.
+`TransformedSequence`, `WindowedSequence`, `ZippedSequence`), file-backed
+templates (`FileFolderSequence`, `FileListSequence`, `SingleFileSequence`),
+and `generate_batches`.
 
 ## 🎯 Quick example
 

{kaparoo_python-0.5.0 → kaparoo_python-0.7.0}/README.md

@@ -44,18 +44,19 @@ hook for custom filter kinds.
 
 ### [`kaparoo.utils`](https://github.com/kaparoo/kaparoo-python/tree/main/kaparoo/utils)
 
-`Timer` / `SegmentTimer` context-manager-and-decorator timers (with
+`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); plus a
-small family of helpers for working with `Optional[T]` values
-(`replace_if_none`, `unwrap_or_default`, ...).
+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`](https://github.com/kaparoo/kaparoo-python/tree/main/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`.
+`TransformedSequence`, `WindowedSequence`, `ZippedSequence`), file-backed
+templates (`FileFolderSequence`, `FileListSequence`, `SingleFileSequence`),
+and `generate_batches`.
 
 ## 🎯 Quick example
 

{kaparoo_python-0.5.0 → kaparoo_python-0.7.0}/kaparoo/data/README.md

@@ -7,7 +7,8 @@ small set of composers, and ready-to-subclass file-backed templates.
 
 - [`sequences/base`](./sequences/base.py) — `DataSequence[T, M]` abstract base
 - [`sequences/composers`](./sequences/composers.py) — `SlicedSequence`,
-  `ConcatSequence`, `WindowedSequence`
+  `TransformedSequence`, `ConcatSequence`, `WindowedSequence`,
+  `ZippedSequence`
 - [`sequences/templates`](./sequences/templates.py) — `FileFolderSequence`,
   `FileListSequence`, `SingleFileSequence`
 - [`sequences/utils`](./sequences/utils.py) — `generate_batches`
@@ -83,18 +84,49 @@ combined = ConcatSequence(train_a, train_b, train_c)
 len(combined)  # == len(train_a) + len(train_b) + len(train_c)
 ```
 
+### `TransformedSequence`
+
+A lazy view that applies a `transform` callable to each item of
+`source`. The transform is called on demand in `get_item` -- nothing
+is computed at construction. `get_meta` passes through `source.get_meta`
+unchanged by default; override it in a subclass when `M_out` differs
+from `M_in`.
+
+```python
+from kaparoo.data.sequences import TransformedSequence
+
+# Item transform only -- metadata type is unchanged.
+normalized = TransformedSequence(image_folder, normalize_fn)
+
+# Meta transform via subclassing:
+class Augmented(TransformedSequence[ndarray, Path, ndarray, AugMeta]):
+    def get_meta(self, index: int) -> AugMeta:
+        return AugMeta(path=self.source.get_meta(index), applied="normalize")
+```
+
+Chaining two `TransformedSequence` instances applies the transforms in
+order:
+
+```python
+resized    = TransformedSequence(raw, resize)
+normalized = TransformedSequence(resized, normalize)
+```
+
+`T_out` and `M_out` default to `T_in` and `M_in` respectively (PEP 696),
+so you only need to specify them when the type actually changes.
+
 ### `WindowedSequence`
 
 An abstract sliding-window view: each item is a `tuple[T, ...]` of
 `size` frames from `source`. Per-frame `M_in` and window-level
-`M_out` are independent type parameters, so subclasses decide how
-metadata aggregates.
+`M_out` are independent type parameters (`M_out` defaults to `M_in`),
+so subclasses decide how metadata aggregates.
 
 ```python
 from pathlib import Path
 from kaparoo.data.sequences import WindowedSequence
 
-class FirstFrameMeta(WindowedSequence[bytes, Path, Path]):
+class FirstFrameMeta(WindowedSequence[bytes, Path]):
     def get_meta(self, index):
         # window's metadata is its first frame's metadata
         index = self._normalize_index(index)
@@ -109,6 +141,27 @@ windows.get_meta(0)   # frames.get_meta(0)
 `size`, `step`, `skip` follow the same semantics as
 [`generate_batches`](#generate_batches).
 
+### `ZippedSequence`
+
+Element-wise zip of two sequences — item `i` is `(first[i], second[i])`
+and metadata `i` is the `(M1, M2)` tuple. This is the "paired image +
+label" pattern that `ConcatSequence` (end-to-end) cannot express. With
+`strict=True` (the default) the lengths must match or construction raises
+`ValueError`; pass `strict=False` to truncate to the shorter length, like
+the builtin `zip`. For a different combined metadata shape, subclass and
+override `get_meta`.
+
+```python
+from kaparoo.data.sequences import ZippedSequence
+
+pairs = ZippedSequence(images, labels)
+pairs[0]            # (images[0], labels[0])
+pairs.get_meta(0)   # (images.get_meta(0), labels.get_meta(0))
+```
+
+For three or more, nest: `ZippedSequence(a, ZippedSequence(b, c))` yields
+`(a[i], (b[i], c[i]))`.
+
 ## Templates
 
 ### `FileFolderSequence`

{kaparoo_python-0.5.0 → kaparoo_python-0.7.0}/kaparoo/data/__init__.py

@@ -5,7 +5,9 @@ __all__ = (
     "FileListSequence",
     "SingleFileSequence",
     "SlicedSequence",
+    "TransformedSequence",
     "WindowedSequence",
+    "ZippedSequence",
     "generate_batches",
 )
 
@@ -16,6 +18,8 @@ from kaparoo.data.sequences import (
     FileListSequence,
     SingleFileSequence,
     SlicedSequence,
+    TransformedSequence,
     WindowedSequence,
+    ZippedSequence,
     generate_batches,
 )

{kaparoo_python-0.5.0 → kaparoo_python-0.7.0}/kaparoo/data/sequences/__init__.py

@@ -7,7 +7,9 @@ __all__ = (
     "FileListSequence",
     "SingleFileSequence",
     "SlicedSequence",
+    "TransformedSequence",
     "WindowedSequence",
+    "ZippedSequence",
     "generate_batches",
 )
 
@@ -15,7 +17,9 @@ from kaparoo.data.sequences.base import DataSequence
 from kaparoo.data.sequences.composers import (
     ConcatSequence,
     SlicedSequence,
+    TransformedSequence,
     WindowedSequence,
+    ZippedSequence,
 )
 from kaparoo.data.sequences.templates import (
     FileFolderSequence,

{kaparoo_python-0.5.0 → kaparoo_python-0.7.0}/kaparoo/data/sequences/composers.py

@@ -1,15 +1,21 @@
 from __future__ import annotations
 
-__all__ = ("ConcatSequence", "SlicedSequence", "WindowedSequence")
+__all__ = (
+    "ConcatSequence",
+    "SlicedSequence",
+    "TransformedSequence",
+    "WindowedSequence",
+    "ZippedSequence",
+)
 
 from abc import abstractmethod
 from bisect import bisect_right
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 from kaparoo.data.sequences.base import DataSequence
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Callable, Sequence
 
 
 class SlicedSequence[T, M](DataSequence[T, M]):
@@ -59,6 +65,61 @@ class SlicedSequence[T, M](DataSequence[T, M]):
         return self._source.get_meta(self._indices[index])
 
 
+class TransformedSequence[T_in, M_in, T_out = T_in, M_out = M_in](
+    DataSequence[T_out, M_out]
+):
+    """A view of `source` with `transform` applied lazily to each item.
+
+    `transform` is called on demand in `get_item`; nothing is loaded or
+    converted at construction time. `get_meta` passes through
+    `source.get_meta` unchanged by default -- override it in a subclass
+    when `M_out` differs from `M_in`.
+
+    Type Parameters:
+        T_in: Item type of `source`.
+        M_in: Metadata type of `source`.
+        T_out: Item type after the transform. Defaults to `T_in`.
+        M_out: Metadata type exposed by this view. Defaults to `M_in`.
+            When `M_out != M_in`, override `get_meta` in a subclass;
+            the default passthrough is only safe when `M_out == M_in`.
+
+    Example:
+        >>> # Item-only transform; metadata passes through unchanged.
+        >>> normalized = TransformedSequence(image_folder, normalize)
+
+        >>> # Meta transform via subclassing:
+        >>> class Augmented(TransformedSequence[ndarray, Path, ndarray, AugMeta]):
+        ...     def get_meta(self, index: int) -> AugMeta:
+        ...         return AugMeta(
+        ...             path=self.source.get_meta(index),
+        ...             applied="normalize",
+        ...         )
+    """
+
+    def __init__(
+        self,
+        source: DataSequence[T_in, M_in],
+        transform: Callable[[T_in], T_out],
+    ) -> None:
+        self._source = source
+        self._transform = transform
+
+    @property
+    def source(self) -> DataSequence[T_in, M_in]:
+        """The wrapped sequence."""
+        return self._source
+
+    def __len__(self) -> int:
+        return len(self._source)
+
+    def get_item(self, index: int) -> T_out:
+        return self._transform(self._source.get_item(index))
+
+    def get_meta(self, index: int) -> M_out:
+        # Passthrough by default. Override when M_out != M_in.
+        return cast("M_out", self._source.get_meta(index))
+
+
 class ConcatSequence[T, M](DataSequence[T, M]):
     """The end-to-end concatenation of zero or more `sources`.
 
@@ -112,7 +173,7 @@ class ConcatSequence[T, M](DataSequence[T, M]):
         return source.get_meta(local)
 
 
-class WindowedSequence[T, M_in, M_out](DataSequence[tuple[T, ...], M_out]):
+class WindowedSequence[T, M_in, M_out = M_in](DataSequence[tuple[T, ...], M_out]):
     """An abstract sliding-window view over `source`.
 
     Each item is a tuple of `size` items from `source`, starting at
@@ -130,8 +191,8 @@ class WindowedSequence[T, M_in, M_out](DataSequence[tuple[T, ...], M_out]):
         T: Item type of `source` (also the per-frame type within each
             window).
         M_in: Metadata type of `source` (per-frame metadata).
-        M_out: Metadata type of the window. Determined by the
-            subclass's `get_meta` return.
+        M_out: Metadata type of the window. Defaults to `M_in`.
+            Determined by the subclass's `get_meta` return.
 
     Args:
         source: The sequence to window over.
@@ -219,3 +280,115 @@ class WindowedSequence[T, M_in, M_out](DataSequence[tuple[T, ...], M_out]):
     @abstractmethod
     def get_meta(self, index: int) -> M_out:
         raise NotImplementedError
+
+
+class ZippedSequence[T1, T2, M1 = None, M2 = None](
+    DataSequence[tuple[T1, T2], tuple[M1, M2]]
+):
+    """Element-wise zip of two sequences.
+
+    Item `i` is `(first[i], second[i])` and metadata `i` is
+    `(first.get_meta(i), second.get_meta(i))` -- the "paired image + label"
+    pattern that `ConcatSequence` (end-to-end) cannot express.
+
+    With `strict=True` (the default) the two sequences must have the same
+    length; a mismatch raises `ValueError` at construction. With
+    `strict=False` the view is truncated to the shorter length, like the
+    builtin `zip`. For a different combined-metadata shape, subclass and
+    override `get_meta`.
+
+    Type Parameters:
+        T1: Item type of the first source.
+        T2: Item type of the second source.
+        M1: Metadata type of the first source. Defaults to `None`.
+        M2: Metadata type of the second source. Defaults to `None`.
+
+    Args:
+        first: The first sequence.
+        second: The second sequence.
+        strict: When True (default), require equal lengths and raise on a
+            mismatch. When False, truncate to the shorter length.
+
+    Raises:
+        ValueError: If `strict` is True and the sequences differ in length.
+
+    Example:
+        >>> pairs = ZippedSequence(images, labels)
+        >>> pairs[0]  # (images[0], labels[0])
+        >>> pairs.get_meta(0)  # (images.get_meta(0), labels.get_meta(0))
+    """
+
+    def __init__(
+        self,
+        first: DataSequence[T1, M1],
+        second: DataSequence[T2, M2],
+        *,
+        strict: bool = True,
+    ) -> None:
+        if strict and len(first) != len(second):
+            msg = f"sequences differ in length: {len(first)} != {len(second)}"
+            raise ValueError(msg)
+        self._first = first
+        self._second = second
+        self._length = len(first) if strict else min(len(first), len(second))
+
+    @property
+    def first(self) -> DataSequence[T1, M1]:
+        """The first wrapped sequence."""
+        return self._first
+
+    @property
+    def second(self) -> DataSequence[T2, M2]:
+        """The second wrapped sequence."""
+        return self._second
+
+    def __len__(self) -> int:
+        return self._length
+
+    def _normalize_index(self, index: int) -> int:
+        """Normalize a possibly-negative index and validate range.
+
+        Indices resolve against the zipped length (the shorter source when
+        `strict=False`), so they address the same position in both sources.
+
+        Raises:
+            IndexError: If `index` is outside `[-len(self), len(self))`.
+        """
+        n = self._length
+        original = index
+        if index < 0:
+            index += n
+        if not 0 <= index < n:
+            msg = f"index {original} out of range for length {n}"
+            raise IndexError(msg)
+        return index
+
+    def get_item(self, index: int) -> tuple[T1, T2]:
+        index = self._normalize_index(index)
+        return self._first.get_item(index), self._second.get_item(index)
+
+    def get_items(self, indices: Sequence[int]) -> Sequence[tuple[T1, T2]]:
+        # Normalize, then bulk-delegate so each source's `get_items`
+        # optimization is used.
+        normalized = [self._normalize_index(i) for i in indices]
+        return list(
+            zip(
+                self._first.get_items(normalized),
+                self._second.get_items(normalized),
+                strict=True,
+            )
+        )
+
+    def get_meta(self, index: int) -> tuple[M1, M2]:
+        index = self._normalize_index(index)
+        return self._first.get_meta(index), self._second.get_meta(index)
+
+    def get_metas(self, indices: Sequence[int]) -> Sequence[tuple[M1, M2]]:
+        normalized = [self._normalize_index(i) for i in indices]
+        return list(
+            zip(
+                self._first.get_metas(normalized),
+                self._second.get_metas(normalized),
+                strict=True,
+            )
+        )

{kaparoo_python-0.5.0 → kaparoo_python-0.7.0}/kaparoo/data/sequences/templates.py

@@ -14,11 +14,92 @@ if TYPE_CHECKING:
     from kaparoo.filesystem.types import StrPath, StrPaths
 
 
-class FileFolderSequence[T, M = Path](DataSequence[T, M]):
-    """A folder-rooted `DataSequence` whose items live in individual files.
+class FileListSequence[T, M = Path](DataSequence[T, M]):
+    """A `DataSequence` over an explicit, ordered list of files.
+
+    Items live one-per-file; subclasses implement `load_file` and `get_meta`.
+    The files are given directly rather than discovered under a `root`, so
+    they may live in unrelated directories -- or, on Windows, on different
+    drives. (`FileFolderSequence` is the special case where the list is
+    discovered under a single root and stored relative to it.)
+
+    The given order is preserved verbatim and duplicates are kept; sort the
+    input yourself (`sorted(files, key=...)`) if a particular order is
+    needed. Paths are not checked for existence at construction; `load_file`
+    is called lazily on each `get_item`.
+
+    The base exposes:
+
+    - `files: tuple[Path, ...]` — full paths as an immutable snapshot.
+    - `get_file(index) -> Path` — full path of the i-th file.
 
-    The base class handles file discovery, indexing, and root-relative
-    path bookkeeping. Subclasses are responsible for three things:
+    Type Parameters:
+        T: Item type returned by `get_item`.
+        M: Per-item metadata type. Defaults to `Path`; override when the
+            metadata is something else (label, line number, ...).
+
+    Args:
+        files: The file paths to expose, in order.
+
+    Example:
+        >>> from pathlib import Path
+        >>> class BytesList(FileListSequence[bytes]):
+        ...     def get_meta(self, index: int) -> Path:
+        ...         return self.get_file(index)
+        ...
+        ...     def load_file(self, path: Path) -> bytes:
+        ...         return path.read_bytes()
+        >>>
+        >>> data = BytesList(["images/a.png", "/other/b.png"])
+    """
+
+    def __init__(self, files: StrPaths) -> None:
+        self._files = list(stringify_paths(files))
+
+    def __len__(self) -> int:
+        return len(self._files)
+
+    @property
+    def files(self) -> tuple[Path, ...]:
+        """Immutable snapshot of the full file paths, in order.
+
+        Returns a fresh `tuple[Path, ...]` on each access.
+        """
+        return tuple(self.get_file(i) for i in range(len(self)))
+
+    def get_file(self, index: int) -> Path:
+        """Full Path of the file at `index`."""
+        return Path(self._files[index])
+
+    def get_item(self, index: int) -> T:
+        return self.load_file(self.get_file(index))
+
+    @abstractmethod
+    def get_meta(self, index: int) -> M:
+        raise NotImplementedError
+
+    @abstractmethod
+    def load_file(self, path: Path) -> T:
+        """Decode a single file into an item of type `T`.
+
+        Called lazily on each `get_item` -- not at construction time.
+        Subclasses may freely use external libraries (PIL, librosa,
+        cv2, ...) to decode.
+        """
+        raise NotImplementedError
+
+
+class FileFolderSequence[T, M = Path](FileListSequence[T, M]):
+    """A `FileListSequence` whose file list is discovered under a root.
+
+    The special case of `FileListSequence` where every file lives under one
+    base directory. The list is produced by `list_files(root)`, validated to
+    be under `root`, and stored in root-relative form so memory stays low for
+    large datasets and the paths survive a `root` relocation; `get_file`
+    transparently re-prepends `root`. `load_file`, `get_item`, `files`, and
+    `__len__` are inherited unchanged.
+
+    Subclasses are responsible for three things:
 
     - **`list_files(self, root)`** (abstract): return the full `Path`
       of every file to expose, in the desired order. Called once from
@@ -33,16 +114,9 @@ class FileFolderSequence[T, M = Path](DataSequence[T, M]):
       to `Path` and `get_meta(i)` can be the one-liner
       `return self.get_file(i)`.
 
-    The base exposes:
+    The base adds, on top of `FileListSequence`:
 
     - `root: Path` — the base directory.
-    - `files: tuple[Path, ...]` — full paths as an immutable snapshot.
-    - `get_file(index) -> Path` — full path of the i-th file.
-
-    Paths are kept internally in their root-relative form so that
-    memory stays low for large datasets and the sequence survives
-    `root` relocations; the conversion is transparent to subclasses
-    and external callers.
 
     Parameterized subclasses:
         When a subclass needs instance-level options (e.g. `pattern`,
@@ -94,48 +168,20 @@ class FileFolderSequence[T, M = Path](DataSequence[T, M]):
 
     def __init__(self, root: StrPath) -> None:
         self._root = ensure_dir_exists(root)
-        self._files = list(
-            stringify_paths(self.list_files(self._root), after=self._root)
-        )
-
-    def __len__(self) -> int:
-        return len(self._files)
+        # `after=root` makes each path root-relative and raises ValueError if
+        # any file is not under `root`. The base then stores the relative
+        # form; `get_file` re-prepends `root`.
+        super().__init__(stringify_paths(self.list_files(self._root), after=self._root))
 
     @property
     def root(self) -> Path:
         """The base directory the sequence was constructed from."""
         return self._root
 
-    @property
-    def files(self) -> tuple[Path, ...]:
-        """Immutable snapshot of the full file paths this sequence exposes.
-
-        Returns a fresh `tuple[Path, ...]` on each access, in the order
-        established by `list_files`.
-        """
-        return tuple(self.get_file(i) for i in range(len(self)))
-
     def get_file(self, index: int) -> Path:
         """Full Path of the file at `index`."""
         return wrap_path(self._files[index], prepend=self._root)
 
-    def get_item(self, index: int) -> T:
-        return self.load_file(self.get_file(index))
-
-    @abstractmethod
-    def get_meta(self, index: int) -> M:
-        raise NotImplementedError
-
-    @abstractmethod
-    def load_file(self, path: Path) -> T:
-        """Decode a single file into an item of type `T`.
-
-        Called lazily on each `get_item` -- not at construction time.
-        Subclasses may freely use external libraries (PIL, librosa,
-        cv2, ...) to decode.
-        """
-        raise NotImplementedError
-
     @abstractmethod
     def list_files(self, root: Path) -> list[Path]:
         """Return the full Path of every file to expose, in order.
@@ -149,82 +195,6 @@ class FileFolderSequence[T, M = Path](DataSequence[T, M]):
         raise NotImplementedError
 
 
-class FileListSequence[T, M = Path](DataSequence[T, M]):
-    """A `DataSequence` over an explicit, ordered list of files.
-
-    Like `FileFolderSequence`, items live one-per-file and subclasses
-    implement `load_file` and `get_meta`. Unlike it, the files are given
-    directly rather than discovered under a `root`, so they may live in
-    unrelated directories -- or, on Windows, on different drives -- which
-    `FileFolderSequence` cannot represent (it stores paths relative to one
-    root). There is no `list_files`: the input list *is* the listing.
-
-    The given order is preserved verbatim and duplicates are kept; sort the
-    input yourself (`sorted(files, key=...)`) if a particular order is
-    needed. Paths are not checked for existence at construction; `load_file`
-    is called lazily on each `get_item`.
-
-    The base exposes:
-
-    - `files: tuple[Path, ...]` — full paths as an immutable snapshot.
-    - `get_file(index) -> Path` — full path of the i-th file.
-
-    Type Parameters:
-        T: Item type returned by `get_item`.
-        M: Per-item metadata type. Defaults to `Path`; override when the
-            metadata is something else (label, line number, ...).
-
-    Args:
-        files: The file paths to expose, in order.
-
-    Example:
-        >>> from pathlib import Path
-        >>> class BytesList(FileListSequence[bytes]):
-        ...     def get_meta(self, index: int) -> Path:
-        ...         return self.get_file(index)
-        ...
-        ...     def load_file(self, path: Path) -> bytes:
-        ...         return path.read_bytes()
-        >>>
-        >>> data = BytesList(["images/a.png", "/other/b.png"])
-    """
-
-    def __init__(self, files: StrPaths) -> None:
-        self._files = list(stringify_paths(files))
-
-    def __len__(self) -> int:
-        return len(self._files)
-
-    @property
-    def files(self) -> tuple[Path, ...]:
-        """Immutable snapshot of the full file paths, in the given order.
-
-        Returns a fresh `tuple[Path, ...]` on each access.
-        """
-        return tuple(self.get_file(i) for i in range(len(self)))
-
-    def get_file(self, index: int) -> Path:
-        """Full Path of the file at `index`."""
-        return Path(self._files[index])
-
-    def get_item(self, index: int) -> T:
-        return self.load_file(self.get_file(index))
-
-    @abstractmethod
-    def get_meta(self, index: int) -> M:
-        raise NotImplementedError
-
-    @abstractmethod
-    def load_file(self, path: Path) -> T:
-        """Decode a single file into an item of type `T`.
-
-        Called lazily on each `get_item` -- not at construction time.
-        Subclasses may freely use external libraries (PIL, librosa,
-        cv2, ...) to decode.
-        """
-        raise NotImplementedError
-
-
 class SingleFileSequence[T, M = None](DataSequence[T, M]):
     """A `DataSequence` backed by a single file that holds multiple records.
 

{kaparoo_python-0.5.0 → kaparoo_python-0.7.0}/kaparoo/filesystem/README.md

@@ -10,7 +10,7 @@
   `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)`
+  `reserve_path(s)`, `ensure_file_extension`
 - [`staged`](./staged.py) — `StagedFile` / `StagedDirectory`, safe
   (atomic) writers usable as a context manager or explicitly
 - [`exceptions`](./exceptions.py) — `DirectoryNotFoundError`, `NotAFileError`
@@ -116,6 +116,27 @@ 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
 ```
 
+`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.
+
+```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)
+
+# 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)
+```
+
 ## Reserving a destination
 
 `reserve_path` guards a path that should *not* yet exist, so you don't

{kaparoo_python-0.5.0 → kaparoo_python-0.7.0}/kaparoo/filesystem/__init__.py

@@ -16,6 +16,7 @@ __all__ = (
     "ensure_dir_exists",
     "ensure_dirs_exist",
     "ensure_file_exists",
+    "ensure_file_extension",
     "ensure_files_exist",
     "ensure_path_exists",
     "ensure_paths_exist",
@@ -79,6 +80,7 @@ from kaparoo.filesystem.search import (
 )
 from kaparoo.filesystem.staged import StagedDirectory, StagedFile
 from kaparoo.filesystem.utils import (
+    ensure_file_extension,
     reserve_path,
     reserve_paths,
     stringify_path,

{kaparoo_python-0.5.0 → kaparoo_python-0.7.0}/kaparoo/filesystem/utils.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 __all__ = (
+    "ensure_file_extension",
     "reserve_path",
     "reserve_paths",
     "stringify_path",
@@ -15,7 +16,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING, overload
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Iterable, Sequence
     from typing import Literal
 
     from kaparoo.filesystem.types import StrPath, StrPaths
@@ -357,3 +358,54 @@ def reserve_paths(
         reserve_path(p, exist_ok=exist_ok, make_parents=make_parents) for p in paths
     ]
     return stringify_paths(paths) if stringify else paths
+
+
+def ensure_file_extension(
+    path: StrPath, ext: str | Iterable[str], *, add: bool = False
+) -> Path:
+    """Return `path` as a `Path`, requiring a case-insensitive `.<ext>` suffix.
+
+    A pure path check that never touches the filesystem. `ext` is a single
+    extension or an iterable of acceptable ones (e.g. `("jpg", "jpeg")`); the
+    leading dot on each is optional, so `"bin"` and `".bin"` behave the same.
+    Only the final suffix is considered: `archive.tar.gz` matches `ext="gz"`,
+    not `ext="tar.gz"`.
+
+    `add` mirrors `make` on `ensure_dir_exists`: when False (the default) a
+    path with no suffix raises like any other mismatch; when True, the missing
+    suffix is appended -- the *first* of `ext` when several are given, so pass
+    an ordered list/tuple if that matters. A *wrong* suffix always raises,
+    regardless of `add`.
+
+    Args:
+        path: The path to check.
+        ext: The required extension, or an iterable of acceptable ones, each
+            with or without a leading dot.
+        add: Whether to append the (first) extension when `path` has no
+            suffix, instead of raising. Defaults to False.
+
+    Returns:
+        The path as a Path object, guaranteed to end in an accepted `.<ext>`.
+
+    Raises:
+        ValueError: If `ext` is empty, or `path`'s final suffix is none of the
+            accepted extensions -- except the no-suffix case resolved by
+            `add=True`.
+    """
+    exts = [ext] if isinstance(ext, str) else list(ext)
+    exts = [e.removeprefix(".") for e in exts]
+
+    if not exts:
+        msg = "ext must name at least one extension"
+        raise ValueError(msg)
+
+    path = Path(path)
+    if add and not path.suffix:
+        return path.with_suffix(f".{exts[0]}")
+
+    if path.suffix.lower() not in {f".{e.lower()}" for e in exts}:
+        wanted = " / ".join(f".{e}" for e in exts)
+        msg = f"{path.name} must have a {wanted} extension (got {path.suffix!r})"
+        raise ValueError(msg)
+
+    return path

{kaparoo_python-0.5.0 → kaparoo_python-0.7.0}/kaparoo/utils/README.md

@@ -4,7 +4,7 @@ Small, focused helpers — not enough material for their own packages.
 
 ## Modules
 
-- [`timer`](./timer.py) — `Timer`, `SegmentTimer`, `SegmentRecord`
+- [`timer`](./timer.py) — `Timer`, `SpanTimer`, `SpanRecord`
 - [`aggregate`](./aggregate.py) — `Aggregator` + the `Reduction` family
   (`Mean`, `Sum`, `Min`, `Max`, `Last`, `Fold`)
 - [`optional`](./optional.py) — helpers for `T | None` values
@@ -47,29 +47,29 @@ with Timer("ms") as t:
     do_work()
 ```
 
-## SegmentTimer
+## SpanTimer
 
-`SegmentTimer` extends `Timer` with named time *segments*. Each segment
-is a `SegmentRecord` (a `TypedDict` with `label`, `duration`,
+`SpanTimer` extends `Timer` with named time *spans*. Each span
+is a `SpanRecord` (a `TypedDict` with `label`, `duration`,
 `total_time`) and is produced in one of two ways:
 
 - **`lap(label)` — split.** Each lap's `duration` is the time since the
   previous lap (or the start), so every instant belongs to exactly one
-  segment.
+  span.
 - **`measure(label)` — stopwatch.** Times only the wrapped block; time
-  spent outside any `measure` block is attributed to no segment.
+  spent outside any `measure` block is attributed to no span.
 
 ```python
-from kaparoo.utils.timer import SegmentTimer
+from kaparoo.utils.timer import SpanTimer
 
-with SegmentTimer("ms", ndigits=1) as st:
+with SpanTimer("ms", ndigits=1) as st:
     step_a()
     st.lap("A")               # split: time since start
     idle()                    # NOT counted by the next measure
     with st.measure("B"):     # stopwatch: only this block
         step_b()
 
-# Per-segment details:
+# Per-span details:
 for record in st.records:
     print(record["label"], record["duration"])
 
@@ -80,7 +80,7 @@ print(st.elapsed)   # total wall time of the `with` block
 
 ### `lap` vs `measure`
 
-`lap` splits the timeline into contiguous segments — the gap before a
+`lap` splits the timeline into contiguous spans — the gap before a
 lap is folded into that lap. `measure` brackets a region and ignores
 everything outside it, so untimed work between blocks is excluded from
 `summary`. Pick `lap` for back-to-back phases, `measure` for discrete
@@ -88,16 +88,16 @@ operations interleaved with untimed work. Pauses inside either are
 excluded; a `measure` block that raises records nothing.
 
 `measure` doubles as a decorator (every decorated call records one
-segment, as long as the timer is running when it is called):
+span, as long as the timer is running when it is called):
 
 ```python
-st = SegmentTimer("ms")
+st = SpanTimer("ms")
 
 @st.measure("load")
 def load() -> None: ...
 
 with st:
-    load()        # records a "load" segment each call
+    load()        # records a "load" span each call
 ```
 
 ### Same-label policies
@@ -111,7 +111,7 @@ with st:
 The policy applies to both `lap` and `measure`:
 
 ```python
-with SegmentTimer(on_same_label="separate") as st:
+with SpanTimer(on_same_label="separate") as st:
     st.lap("A")
     st.lap("A")   # recorded as "A (2)"
     st.lap("A")   # recorded as "A (3)"

{kaparoo_python-0.5.0 → kaparoo_python-0.7.0}/kaparoo/utils/__init__.py

@@ -6,8 +6,8 @@ __all__ = (
     "Mean",
     "Min",
     "Reduction",
-    "SegmentRecord",
-    "SegmentTimer",
+    "SpanRecord",
+    "SpanTimer",
     "Std",
     "Sum",
     "Timer",
@@ -42,4 +42,4 @@ from kaparoo.utils.optional import (
     unwrap_or_factories,
     unwrap_or_factory,
 )
-from kaparoo.utils.timer import SegmentRecord, SegmentTimer, Timer
+from kaparoo.utils.timer import SpanRecord, SpanTimer, Timer

{kaparoo_python-0.5.0 → kaparoo_python-0.7.0}/kaparoo/utils/timer.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-__all__ = ("SegmentRecord", "SegmentTimer", "Timer")
+__all__ = ("SpanRecord", "SpanTimer", "Timer")
 
 import time
 from abc import ABC, abstractmethod
@@ -22,20 +22,20 @@ _SCALES: dict[str, float] = {"s": 1e-9, "ms": 1e-6, "us": 1e-3, "ns": 1.0}
 _LABEL_POLICIES: frozenset[str] = frozenset({"merge", "separate", "reject"})
 
 
-class SegmentRecord(TypedDict):
-    """A single timing record produced by `SegmentTimer`.
+class SpanRecord(TypedDict):
+    """A single timing record produced by `SpanTimer`.
 
-    A segment is produced either by `lap` (the span since the previous
+    A span is produced either by `lap` (the span since the previous
     lap) or by `measure` (the span of a wrapped block).
 
     Attributes:
-        label: The segment's name. May carry a " (N)" suffix when produced
+        label: The span's name. May carry a " (N)" suffix when produced
             under `on_same_label="separate"`.
-        duration: Length of this segment, in the timer's `unit` and rounded
+        duration: Length of this span, in the timer's `unit` and rounded
             by `ndigits` if given. For `lap`, the time since the previous
             lap (or the timer start); for `measure`, the wrapped block's
             duration.
-        total_time: Time elapsed from the timer start to this segment's end,
+        total_time: Time elapsed from the timer start to this span's end,
             in the timer's `unit` and rounded by `ndigits` if given.
     """
 
@@ -45,14 +45,14 @@ class SegmentRecord(TypedDict):
 
 
 class BaseTimer(ContextDecorator, ABC):
-    """Abstract base for `Timer` and `SegmentTimer`.
+    """Abstract base for `Timer` and `SpanTimer`.
 
     Provides the shared timing machinery: unit/precision formatting,
     `pause`/`resume`/`suspend`, and a context-manager protocol that
     auto-resumes a paused timer on exit. Subclasses implement `_finalize`
     to record their final result, and may override the `_reset` hook to
     clear per-`with`-block state. Not part of the public API -- prefer
-    `Timer` or `SegmentTimer`.
+    `Timer` or `SpanTimer`.
 
     An instance is reusable but **not reentrant**: a single instance must
     not be nested within itself -- including as a decorator on a recursive
@@ -249,30 +249,30 @@ class Timer(BaseTimer):
         self.elapsed = self._format_time(elapsed_ns)
 
 
-class SegmentTimer(BaseTimer):
-    """A timer recording named time segments within one `with` block.
+class SpanTimer(BaseTimer):
+    """A timer recording named time spans within one `with` block.
 
-    Usable as a context manager or as a decorator. Segments are recorded
+    Usable as a context manager or as a decorator. Spans are recorded
     in two complementary ways:
 
         - `lap(label)` splits the timeline: each lap's `duration` is the
           time since the previous lap (or the start), so every instant is
-          attributed to exactly one segment.
+          attributed to exactly one span.
         - `measure(label)` brackets a region (as a `with` block or a
           decorator): only the wrapped span is recorded, and time spent
-          outside any `measure` block is attributed to no segment.
+          outside any `measure` block is attributed to no span.
 
     Both feed the same `records` / `summary`, honour `on_same_label`, and
     exclude paused intervals.
 
     Attributes:
         on_same_label: The same-label handling policy (see `__init__`).
-        records: The recorded segments, in call order.
+        records: The recorded spans, in call order.
         elapsed: The total measured duration, from start to exit.
             Defaults to 0.0 until the first exit.
 
     Example:
-        with SegmentTimer("ms", ndigits=1) as st:
+        with SpanTimer("ms", ndigits=1) as st:
             step_a()
             st.lap("A")              # split: time since start
             with st.measure("B"):    # block: only this region
@@ -288,7 +288,7 @@ class SegmentTimer(BaseTimer):
         ndigits: int | None = None,
         on_same_label: LabelPolicy = "merge",
     ) -> None:
-        """Initialize the lap timer.
+        """Initialize the span timer.
 
         Args:
             unit: The time unit for reported values. One of "s", "ms", "us",
@@ -313,7 +313,7 @@ class SegmentTimer(BaseTimer):
             raise ValueError(msg)
 
         self.on_same_label = on_same_label
-        self.records: list[SegmentRecord] = []
+        self.records: list[SpanRecord] = []
         self.elapsed: float = 0.0
 
         self._last_time: int = 0
@@ -323,8 +323,8 @@ class SegmentTimer(BaseTimer):
     def summary(self) -> dict[str, float]:
         """Per-label sum of `duration` across `records`.
 
-        Only recorded segments count: time outside every `lap` / `measure`
-        segment (e.g. after the last `lap`, or between `measure` blocks) is
+        Only recorded spans count: time outside every `lap` / `measure`
+        span (e.g. after the last `lap`, or between `measure` blocks) is
         not included. Each record's `duration` is already rounded by
         `ndigits` (when set); this property sums those rounded values and
         rounds the sum once more.
@@ -377,11 +377,11 @@ class SegmentTimer(BaseTimer):
             else label
         )
 
-    def _make_record(self, label: str) -> SegmentRecord:
+    def _make_record(self, label: str) -> SpanRecord:
         """Build a record stamped with the current time and advance `_last_time`."""
         current_time = time.perf_counter_ns()
 
-        record: SegmentRecord = {
+        record: SpanRecord = {
             "label": label,
             "duration": self._format_time(current_time - self._last_time),
             "total_time": self._format_time(current_time - self._start_time),
@@ -415,12 +415,12 @@ class SegmentTimer(BaseTimer):
 
     @contextmanager
     def measure(self, label: str = "Block") -> Iterator[None]:
-        """Record a segment covering only the wrapped block (stopwatch style).
+        """Record a span covering only the wrapped block (stopwatch style).
 
-        Unlike `lap`, which splits the timeline into contiguous segments,
+        Unlike `lap`, which splits the timeline into contiguous spans,
         `measure` times only the wrapped region; time spent outside any
-        `measure` block is attributed to no segment. Pauses inside the
-        block are excluded. A segment is recorded only on clean exit -- if
+        `measure` block is attributed to no span. Pauses inside the
+        block are excluded. A span is recorded only on clean exit -- if
         the block raises, nothing is recorded and the exception propagates.
         Repeated labels follow `on_same_label`, exactly as `lap`. Do not
         nest `measure` blocks: each resets the shared baseline, so an outer
@@ -428,23 +428,23 @@ class SegmentTimer(BaseTimer):
 
         Because `contextmanager` results are also `ContextDecorator`s, the
         returned object doubles as a decorator (every decorated call
-        records one segment, provided the timer is running when called):
+        records one span, provided the timer is running when called):
 
-            st = SegmentTimer("ms")
+            st = SpanTimer("ms")
 
             @st.measure("load")
             def load() -> None: ...
 
             with st:
-                load()                    # records a "load" segment
+                load()                    # records a "load" span
                 with st.measure("parse"):
-                    parse()               # records a "parse" segment
+                    parse()               # records a "parse" span
 
         Args:
-            label: The segment's name. Defaults to "Block".
+            label: The span's name. Defaults to "Block".
 
         Yields:
-            None. The wrapped block runs while the segment is timed.
+            None. The wrapped block runs while the span is timed.
 
         Raises:
             RuntimeError: If the timer has not been started, or is paused on

{kaparoo_python-0.5.0 → kaparoo_python-0.7.0}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "uv_build"
 
 [project]
 name = "kaparoo-python"
-version = "0.5.0"
+version = "0.7.0"
 description = "Personally common and useful Python features"
 readme = "README.md"
 requires-python = ">=3.14"