kaparoo-python 0.6.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

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/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/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/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.6.0.dist-info → kaparoo_python-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kaparoo-python
-Version: 0.6.0
+Version: 0.7.0
 Summary: Personally common and useful Python features
 Keywords: filesystem,pathlib,paths,utilities
 Author: Jaewoo Park
@@ -65,7 +65,7 @@ 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;
 experimental); plus a small family of helpers for working with

{kaparoo_python-0.6.0.dist-info → kaparoo_python-0.7.0.dist-info}/RECORD

@@ -5,7 +5,7 @@ kaparoo/data/sequences/base.py,sha256=m2JcIcT-SLrTzsjFCtgrQ9I5XVpB6PYBigyooEpg4V
 kaparoo/data/sequences/composers.py,sha256=eaWW8VKyVq4zzJAvIh_LKYt6g-R-HqzzpoV4NKtFeqc,13373
 kaparoo/data/sequences/templates.py,sha256=9a_vM-c9OaF-9qY0ybqRaGkVkywJzrQbNlEHfe39MHU,9572
 kaparoo/data/sequences/utils.py,sha256=oe0qWwnAjsf-9CBUPSlkxkeuQS8kjn1sYhx2eDIwPKI,2808
-kaparoo/filesystem/__init__.py,sha256=uES_e8DYBE0db5z-_E7N2-vSGvi9-uJiSOWnKHdtuPs,1797
+kaparoo/filesystem/__init__.py,sha256=p1keuLIE0zJCh7lh6KXW9EyeEFMpnMrBzSOVjT3ic-M,1853
 kaparoo/filesystem/directory.py,sha256=Pr15aMl0tz2-VU14rkaFzsV0Zo2oqaevDM0JLW-ZOwk,10421
 kaparoo/filesystem/exceptions.py,sha256=dWzD7d30bUEAxKWMYtJWmIg8tK3meEFz84NhWmWXb6k,464
 kaparoo/filesystem/existence.py,sha256=6AafbDmY_sXrePLs9Vg8gQgT7jS8ETAqxz7TysV8WJ4,12564
@@ -22,13 +22,13 @@ kaparoo/filesystem/search/filters/utils.py,sha256=j-AfVu298t5GuQDb1UCOtb0L7R2Hm9
 kaparoo/filesystem/search/wrappers.py,sha256=CDLvw9IhVNZLtMSdGnldJLum9tt8UTSQoRphOxg0qD8,10782
 kaparoo/filesystem/staged.py,sha256=VXjzszo-FAjQaO9aSPelorIVOyxIUS5SPDank5wQupM,18275
 kaparoo/filesystem/types.py,sha256=Cm1MLEAujVRyB9uciJ-uUxC0hw6j-ycxVPKS9KFmJnw,202
-kaparoo/filesystem/utils.py,sha256=nSy_7RDPljP5FTZjRipkWEi6PAOLsYr0MubwCNfXm6s,10850
+kaparoo/filesystem/utils.py,sha256=x9R42WLCyHdJHC1dwzSd7SxYh3HnPl2ZotfxjUnwdlE,12882
 kaparoo/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kaparoo/utils/__init__.py,sha256=QR-aXuDvxCtOXZLiqHNrKozLlzg_v60UaKI6x2S3YtU,785
+kaparoo/utils/__init__.py,sha256=lkLwehMw3oOjMq8SPq-DQ6XCrBvsVfXJuLYchjJDwzA,773
 kaparoo/utils/aggregate.py,sha256=8apzZiqLAxoSO51DDDMsOnkrsEaejudXDTc6h3uKRZc,13953
 kaparoo/utils/optional.py,sha256=UgNhGDzl317PE_ESt9hW7yl9MYcdL0nV6Ly0mpqIz0U,4224
-kaparoo/utils/timer.py,sha256=n2RenrYik51v1Dmo9JmZpG3_cPafRDgGMbxdvNoRhgs,17001
-kaparoo_python-0.6.0.dist-info/licenses/LICENSE,sha256=hb6LWYP2rtcoz4V2HpawmblDfHwjwsg9N3cz0c5JQJE,1067
-kaparoo_python-0.6.0.dist-info/WHEEL,sha256=V5-3dKee3Zs8C4JP6swr6zdqriLsOpItBEQxe6_oWpY,81
-kaparoo_python-0.6.0.dist-info/METADATA,sha256=I9qqiuRdVQeIh0cHdadR_3UQlyLgtKpTLJ-ycLtYWjQ,4327
-kaparoo_python-0.6.0.dist-info/RECORD,,
+kaparoo/utils/timer.py,sha256=IVkQxbSJqexEAPPiGW234M_e4-lW5lrXSBAnXIbQCVo,16906
+kaparoo_python-0.7.0.dist-info/licenses/LICENSE,sha256=hb6LWYP2rtcoz4V2HpawmblDfHwjwsg9N3cz0c5JQJE,1067
+kaparoo_python-0.7.0.dist-info/WHEEL,sha256=wXwAVsgVaOZ_pwDFqQm5Rd6PID-Fc74nkLc8X8gHiDo,81
+kaparoo_python-0.7.0.dist-info/METADATA,sha256=k5XknG0Oi_MGDKSDrbpxJCohfiWit-NPm1ql2Wvtd5c,4324
+kaparoo_python-0.7.0.dist-info/RECORD,,

{kaparoo_python-0.6.0.dist-info → kaparoo_python-0.7.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.11.18
+Generator: uv 0.11.19
 Root-Is-Purelib: true
 Tag: py3-none-any