kaparoo-python 0.1.12__tar.gz → 0.2.1__tar.gz

{kaparoo_python-0.1.12 → kaparoo_python-0.2.1}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2023 Jaewoo Park
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2023 Jaewoo Park
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

kaparoo_python-0.2.1/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: kaparoo-python
+Version: 0.2.1
+Summary: Personally common and useful Python features
+Keywords: filesystem,pathlib,paths,utilities
+Author: Jaewoo Park
+Author-email: Jaewoo Park <kaparoo2001@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Project-URL: GitHub, https://www.github.com/kaparoo/kaparoo-python
+Project-URL: Issues, https://www.github.com/kaparoo/kaparoo-python/issues
+Description-Content-Type: text/markdown
+
+# kaparoo-python
+
+[![PyPI version](https://img.shields.io/pypi/v/kaparoo-python.svg)](https://pypi.org/project/kaparoo-python/)
+[![Downloads](https://pepy.tech/badge/kaparoo-python)](https://pypi.org/project/kaparoo-python/)
+[![Python](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-orange.json)](https://github.com/copier-org/copier)
+
+*Personally common and useful Python features.*
+
+## 📦 Installation
+
+Requires Python 3.14+.
+
+```bash
+# With uv (recommended)
+uv add kaparoo-python
+
+# With pip
+pip install kaparoo-python
+```
+
+## 🧩 Modules
+
+### `kaparoo.filesystem`
+
+`pathlib`-based filesystem helpers.
+
+- **`existence`** — existence checks (`*_exists`) and `ensure_*` validators.
+- **`directory`** — `make_dir(s)`, `dir_empty(s)` (with `_unsafe` variants).
+- **`utils`** — `stringify_path(s)`, `wrap_path(s)`.
+- **`exceptions`** — `DirectoryNotFoundError`, `NotAFileError`.
+- **`types`** — `StrPath`, `StrPaths`.
+
+### `kaparoo.filesystem.search`
+
+Filesystem traversal with composable filters.
+
+- **Entry points** — `search_paths`, `search_files`, `search_dirs`.
+- **Pattern filters** — `Equals`, `StartsWith`, `EndsWith`, `Contains`,
+  `Regex`, `Glob`.
+- **Multi-pattern filters** — `EqualsAny`, `StartsWithAny`, `EndsWithAny`,
+  `ContainsAny`.
+- **Logical filters** — `And`, `Or`, `Not`.
+- **Serialization** — `Filter.to_dict()` / `Filter.from_dict()` round-trip
+  via a `"kind"` discriminator; `Filter.parse()` accepts a `Filter` or a
+  `FilterDict`; `register_filter(kind)` extends the dispatcher with
+  custom subclasses. `FilterDict` family lives at
+  `kaparoo.filesystem.search.filters.types`.
+- **Deprecated** — `get_paths`, `get_files`, `get_dirs` (use `search_*`).
+
+### `kaparoo.utils`
+
+- **`timer`** — `Timer` and `LapTimer` context-manager / decorator timers.
+- **`optional`** — `replace_if_none`, `factory_if_none`, `unwrap_or_*`.
+
+## 📋 TODO
+
+See [TODO.md](./TODO.md) for tracked open items.
+
+## 📜 Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for the version history.
+
+## ⚖️ License
+
+This project is distributed under the terms of the [MIT](./LICENSE) license.

kaparoo_python-0.2.1/README.md

@@ -0,0 +1,70 @@
+# kaparoo-python
+
+[![PyPI version](https://img.shields.io/pypi/v/kaparoo-python.svg)](https://pypi.org/project/kaparoo-python/)
+[![Downloads](https://pepy.tech/badge/kaparoo-python)](https://pypi.org/project/kaparoo-python/)
+[![Python](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-orange.json)](https://github.com/copier-org/copier)
+
+*Personally common and useful Python features.*
+
+## 📦 Installation
+
+Requires Python 3.14+.
+
+```bash
+# With uv (recommended)
+uv add kaparoo-python
+
+# With pip
+pip install kaparoo-python
+```
+
+## 🧩 Modules
+
+### `kaparoo.filesystem`
+
+`pathlib`-based filesystem helpers.
+
+- **`existence`** — existence checks (`*_exists`) and `ensure_*` validators.
+- **`directory`** — `make_dir(s)`, `dir_empty(s)` (with `_unsafe` variants).
+- **`utils`** — `stringify_path(s)`, `wrap_path(s)`.
+- **`exceptions`** — `DirectoryNotFoundError`, `NotAFileError`.
+- **`types`** — `StrPath`, `StrPaths`.
+
+### `kaparoo.filesystem.search`
+
+Filesystem traversal with composable filters.
+
+- **Entry points** — `search_paths`, `search_files`, `search_dirs`.
+- **Pattern filters** — `Equals`, `StartsWith`, `EndsWith`, `Contains`,
+  `Regex`, `Glob`.
+- **Multi-pattern filters** — `EqualsAny`, `StartsWithAny`, `EndsWithAny`,
+  `ContainsAny`.
+- **Logical filters** — `And`, `Or`, `Not`.
+- **Serialization** — `Filter.to_dict()` / `Filter.from_dict()` round-trip
+  via a `"kind"` discriminator; `Filter.parse()` accepts a `Filter` or a
+  `FilterDict`; `register_filter(kind)` extends the dispatcher with
+  custom subclasses. `FilterDict` family lives at
+  `kaparoo.filesystem.search.filters.types`.
+- **Deprecated** — `get_paths`, `get_files`, `get_dirs` (use `search_*`).
+
+### `kaparoo.utils`
+
+- **`timer`** — `Timer` and `LapTimer` context-manager / decorator timers.
+- **`optional`** — `replace_if_none`, `factory_if_none`, `unwrap_or_*`.
+
+## 📋 TODO
+
+See [TODO.md](./TODO.md) for tracked open items.
+
+## 📜 Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for the version history.
+
+## ⚖️ License
+
+This project is distributed under the terms of the [MIT](./LICENSE) license.

kaparoo_python-0.1.12/kaparoo/data/files/base.py → kaparoo_python-0.2.1/kaparoo/data/sequence.py

@@ -1,45 +1,39 @@
-from __future__ import annotations
-
-__all__ = ("DataSequence",)
-
-from abc import abstractmethod
-from collections.abc import Sequence
-from typing import TYPE_CHECKING, overload
-
-from kaparoo.utils.types import T_co
-
-if TYPE_CHECKING:
-    from typing import Self
-
-    from kaparoo.filesystem.types import StrPath
-
-
-class DataSequence(Sequence[T_co]):
-    @abstractmethod
-    def __init__(self: Self, path: StrPath) -> None:
-        raise NotImplementedError
-
-    @abstractmethod
-    def __len__(self: Self) -> int:
-        raise NotImplementedError
-
-    @overload
-    def __getitem__(self: Self, index: int, /) -> T_co:
-        pass
-
-    @overload
-    def __getitem__(self: Self, index: slice, /) -> Sequence[T_co]:
-        pass
-
-    def __getitem__(self: Self, index: int | slice, /) -> T_co | Sequence[T_co]:
-        if isinstance(index, slice):
-            start, stop, step = index.indices(len(self))
-            return self.by_indices(range(start, stop, step))
-        return self.by_index(index)
-
-    @abstractmethod
-    def by_index(self: Self, index: int) -> T_co:
-        raise NotImplementedError
-
-    def by_indices(self: Self, indices: Sequence[int]) -> Sequence[T_co]:
-        return [self.by_index(index) for index in indices]
+from __future__ import annotations
+
+__all__ = ("DataSequence",)
+
+from abc import abstractmethod
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, overload
+
+if TYPE_CHECKING:
+    from kaparoo.filesystem.types import StrPath
+
+
+class DataSequence[T](Sequence[T]):
+    @abstractmethod
+    def __init__(self, path: StrPath) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def __len__(self) -> int:
+        raise NotImplementedError
+
+    @overload
+    def __getitem__(self, index: int, /) -> T: ...
+
+    @overload
+    def __getitem__(self, index: slice, /) -> Sequence[T]: ...
+
+    def __getitem__(self, index: int | slice, /) -> T | Sequence[T]:
+        if isinstance(index, slice):
+            start, stop, step = index.indices(len(self))
+            return self.by_indices(range(start, stop, step))
+        return self.by_index(index)
+
+    @abstractmethod
+    def by_index(self, index: int) -> T:
+        raise NotImplementedError
+
+    def by_indices(self, indices: Sequence[int]) -> Sequence[T]:
+        return [self.by_index(index) for index in indices]

{kaparoo_python-0.1.12 → kaparoo_python-0.2.1}/kaparoo/data/utils.py

@@ -1,49 +1,46 @@
-from __future__ import annotations
-
-__all__ = ("generate_batches",)
-
-from typing import TYPE_CHECKING
-
-from kaparoo.utils.optional import replace_if_none
-
-if TYPE_CHECKING:
-    from collections.abc import Generator, Sequence
-    from typing import Any
-
-    from kaparoo.utils.types import T_co
-
-
-def generate_batches(
-    sequence: Sequence[T_co],
-    size: int,
-    step: int = 1,
-    skip: int = 1,
-    start: int = 0,
-    stop: int | None = None,
-    *,
-    drop_last: bool = True,
-) -> Generator[Sequence[T_co], Any, None]:
-    def die_if_not_positive(name: str, value: int) -> None:
-        if value <= 0:
-            raise ValueError(f"{name} must be positive (got {value})")
-
-    die_if_not_positive("size", size)
-    die_if_not_positive("step", step)
-    die_if_not_positive("skip", skip)
-
-    stop = replace_if_none(stop, len_ := len(sequence))
-    if not (start < stop <= len_ and start >= 0):
-        raise ValueError(
-            f"invalid range [{start}, {stop}) for sequence of length {len_}"
-        )
-
-    head = start
-    tail = head + (size - 1) * skip + 1
-
-    while tail <= stop:
-        yield sequence[head:tail:skip]
-        head += step
-        tail += step
-
-    if not drop_last and head < stop:
-        yield sequence[head:tail:skip]
+from __future__ import annotations
+
+__all__ = ("generate_batches",)
+
+from typing import TYPE_CHECKING
+
+from kaparoo.utils.optional import replace_if_none
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Sequence
+
+
+def generate_batches[T](
+    sequence: Sequence[T],
+    size: int,
+    step: int = 1,
+    skip: int = 1,
+    start: int = 0,
+    stop: int | None = None,
+    *,
+    drop_last: bool = True,
+) -> Iterator[Sequence[T]]:
+    def die_if_not_positive(name: str, value: int) -> None:
+        if value <= 0:
+            msg = f"{name} must be positive (got {value})"
+            raise ValueError(msg)
+
+    die_if_not_positive("size", size)
+    die_if_not_positive("step", step)
+    die_if_not_positive("skip", skip)
+
+    stop = replace_if_none(stop, len_ := len(sequence))
+    if not (start < stop <= len_ and start >= 0):
+        msg = f"invalid range [{start}, {stop}) for sequence of length {len_}"
+        raise ValueError(msg)
+
+    head = start
+    tail = head + (size - 1) * skip + 1
+
+    while tail <= stop:
+        yield sequence[head:tail:skip]
+        head += step
+        tail += step
+
+    if not drop_last and head < stop:
+        yield sequence[head:tail:skip]

{kaparoo_python-0.1.12 → kaparoo_python-0.2.1}/kaparoo/filesystem/__init__.py

@@ -1,56 +1,73 @@
-__all__ = (
-    # utils
-    "prepend_path",
-    "prepend_paths",
-    "stringify_path",
-    "stringify_paths",
-    # existence
-    "ensure_dir_exists",
-    "ensure_dirs_exist",
-    "ensure_path_exists",
-    "ensure_paths_exist",
-    "ensure_file_exists",
-    "ensure_files_exist",
-    "dir_exists",
-    "dirs_exist",
-    "file_exists",
-    "files_exist",
-    "path_exists",
-    "paths_exist",
-    # directory
-    "dir_empty",
-    "dirs_empty",
-    "get_dirs",
-    "get_files",
-    "get_paths",
-    "make_dirs",
-)
-
-from kaparoo.filesystem.directory import (
-    dir_empty,
-    dirs_empty,
-    get_dirs,
-    get_files,
-    get_paths,
-    make_dirs,
-)
-from kaparoo.filesystem.existence import (
-    dir_exists,
-    dirs_exist,
-    ensure_dir_exists,
-    ensure_dirs_exist,
-    ensure_file_exists,
-    ensure_files_exist,
-    ensure_path_exists,
-    ensure_paths_exist,
-    file_exists,
-    files_exist,
-    path_exists,
-    paths_exist,
-)
-from kaparoo.filesystem.utils import (
-    prepend_path,
-    prepend_paths,
-    stringify_path,
-    stringify_paths,
-)
+__all__ = (
+    "DirectoryNotFoundError",
+    "NotAFileError",
+    "dir_empty",
+    "dir_empty_unsafe",
+    "dir_exists",
+    "dirs_empty",
+    "dirs_empty_unsafe",
+    "dirs_exist",
+    "ensure_dir_exists",
+    "ensure_dirs_exist",
+    "ensure_file_exists",
+    "ensure_files_exist",
+    "ensure_path_exists",
+    "ensure_paths_exist",
+    "file_exists",
+    "files_exist",
+    "get_dirs",
+    "get_files",
+    "get_paths",
+    "make_dir",
+    "make_dirs",
+    "path_exists",
+    "paths_exist",
+    "search_dirs",
+    "search_files",
+    "search_paths",
+    "stringify_path",
+    "stringify_paths",
+    "wrap_path",
+    "wrap_paths",
+)
+
+from kaparoo.filesystem.directory import (
+    dir_empty,
+    dir_empty_unsafe,
+    dirs_empty,
+    dirs_empty_unsafe,
+    make_dir,
+    make_dirs,
+)
+from kaparoo.filesystem.exceptions import (
+    DirectoryNotFoundError,
+    NotAFileError,
+)
+from kaparoo.filesystem.existence import (
+    dir_exists,
+    dirs_exist,
+    ensure_dir_exists,
+    ensure_dirs_exist,
+    ensure_file_exists,
+    ensure_files_exist,
+    ensure_path_exists,
+    ensure_paths_exist,
+    file_exists,
+    files_exist,
+    path_exists,
+    paths_exist,
+)
+from kaparoo.filesystem.search import (
+    get_dirs,
+    get_files,
+    get_paths,
+    search_dirs,
+    search_files,
+    search_paths,
+)
+from kaparoo.filesystem.utils import (
+    stringify_path,
+    stringify_paths,
+    wrap_path,
+    wrap_paths,
+)