kaparoo-python 0.1.11__tar.gz → 0.2.0__tar.gz

{kaparoo_python-0.1.11 → kaparoo_python-0.2.0}/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.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: kaparoo-python
+Version: 0.2.0
+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`.
+- **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.0/README.md

@@ -0,0 +1,65 @@
+# 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`.
+- **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.0/kaparoo/data/sequence.py

@@ -0,0 +1,39 @@
+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.11 → kaparoo_python-0.2.0}/kaparoo/data/utils.py

@@ -7,14 +7,11 @@ 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 collections.abc import Iterator, Sequence
 
-    from kaparoo.utils.types import T_co
 
-
-def generate_batches(
-    sequence: Sequence[T_co],
+def generate_batches[T](
+    sequence: Sequence[T],
     size: int,
     step: int = 1,
     skip: int = 1,
@@ -22,10 +19,11 @@ def generate_batches(
     stop: int | None = None,
     *,
     drop_last: bool = True,
-) -> Generator[Sequence[T_co], Any, None]:
+) -> Iterator[Sequence[T]]:
     def die_if_not_positive(name: str, value: int) -> None:
         if value <= 0:
-            raise ValueError(f"{name} must be positive (got {value})")
+            msg = f"{name} must be positive (got {value})"
+            raise ValueError(msg)
 
     die_if_not_positive("size", size)
     die_if_not_positive("step", step)
@@ -33,9 +31,8 @@ def generate_batches(
 
     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_}"
-        )
+        msg = f"invalid range [{start}, {stop}) for sequence of length {len_}"
+        raise ValueError(msg)
 
     head = start
     tail = head + (size - 1) * skip + 1

{kaparoo_python-0.1.11 → kaparoo_python-0.2.0}/kaparoo/filesystem/__init__.py

@@ -1,39 +1,48 @@
 __all__ = (
-    # utils
-    "prepend_path",
-    "prepend_paths",
-    "stringify_path",
-    "stringify_paths",
-    # existence
+    "DirectoryNotFoundError",
+    "NotAFileError",
+    "dir_empty",
+    "dir_empty_unsafe",
+    "dir_exists",
+    "dirs_empty",
+    "dirs_empty_unsafe",
+    "dirs_exist",
     "ensure_dir_exists",
     "ensure_dirs_exist",
-    "ensure_path_exists",
-    "ensure_paths_exist",
     "ensure_file_exists",
     "ensure_files_exist",
-    "dir_exists",
-    "dirs_exist",
+    "ensure_path_exists",
+    "ensure_paths_exist",
     "file_exists",
     "files_exist",
-    "path_exists",
-    "paths_exist",
-    # directory
-    "dir_empty",
-    "dirs_empty",
     "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,
-    get_dirs,
-    get_files,
-    get_paths,
+    dirs_empty_unsafe,
+    make_dir,
     make_dirs,
 )
+from kaparoo.filesystem.exceptions import (
+    DirectoryNotFoundError,
+    NotAFileError,
+)
 from kaparoo.filesystem.existence import (
     dir_exists,
     dirs_exist,
@@ -48,9 +57,17 @@ from kaparoo.filesystem.existence import (
     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 (
-    prepend_path,
-    prepend_paths,
     stringify_path,
     stringify_paths,
+    wrap_path,
+    wrap_paths,
 )

kaparoo_python-0.2.0/kaparoo/filesystem/directory.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+__all__ = (
+    "dir_empty",
+    "dir_empty_unsafe",
+    "dirs_empty",
+    "dirs_empty_unsafe",
+    "make_dir",
+    "make_dirs",
+)
+
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, overload
+
+from kaparoo.filesystem.existence import (
+    _join_root_if_provided,
+    _validate_mode,
+    ensure_dir_exists,
+    ensure_dirs_exist,
+)
+from kaparoo.filesystem.utils import stringify_path, stringify_paths
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from typing import Literal
+
+    from kaparoo.filesystem.types import StrPath, StrPaths
+
+
+# ========================== #
+#            Make            #
+# ========================== #
+
+
+@overload
+def make_dir(
+    path: StrPath,
+    *,
+    mode: int = 0o777,
+    exist_ok: bool = False,
+    stringify: Literal[False] = False,
+) -> Path: ...
+
+
+@overload
+def make_dir(
+    path: StrPath,
+    *,
+    mode: int = 0o777,
+    exist_ok: bool = False,
+    stringify: Literal[True],
+) -> str: ...
+
+
+@overload
+def make_dir(
+    path: StrPath,
+    *,
+    mode: int = 0o777,
+    exist_ok: bool = False,
+    stringify: bool,
+) -> Path | str: ...
+
+
+def make_dir(
+    path: StrPath,
+    *,
+    mode: int = 0o777,
+    exist_ok: bool = False,
+    stringify: bool = False,
+) -> Path | str:
+    """Recursively create a directory.
+
+    Args:
+        path: The directory path to create.
+        mode: The mode to use when creating the directory. Defaults to 0o777.
+        exist_ok: Whether to suppress OSError if the path already exists.
+            Defaults to False.
+        stringify: Whether to return the path as a string. Defaults to False.
+
+    Returns:
+        The created directory path as a Path object or a string,
+            depending on the value of `stringify`.
+
+    Raises:
+        ValueError: If `mode` is outside the range 0o1-0o7777
+            (not checked on Windows, where the mode is ignored).
+        NotADirectoryError: If the path exists but is not a directory.
+        OSError: If `exist_ok` is False and the path already exists.
+    """
+    _validate_mode(mode)
+    path = Path(path)
+    if path.exists() and not path.is_dir():
+        msg = f"not a directory: {path}"
+        raise NotADirectoryError(msg)
+    path.mkdir(mode=mode, parents=True, exist_ok=exist_ok)
+    return stringify_path(path) if stringify else path
+
+
+@overload
+def make_dirs(
+    paths: StrPaths,
+    *,
+    root: StrPath | None = None,
+    mode: int = 0o777,
+    exist_ok: bool = False,
+    stringify: Literal[False] = False,
+) -> Sequence[Path]: ...
+
+
+@overload
+def make_dirs(
+    paths: StrPaths,
+    *,
+    root: StrPath | None = None,
+    mode: int = 0o777,
+    exist_ok: bool = False,
+    stringify: Literal[True],
+) -> Sequence[str]: ...
+
+
+@overload
+def make_dirs(
+    paths: StrPaths,
+    *,
+    root: StrPath | None = None,
+    mode: int = 0o777,
+    exist_ok: bool = False,
+    stringify: bool,
+) -> Sequence[Path] | Sequence[str]: ...
+
+
+def make_dirs(
+    paths: StrPaths,
+    *,
+    root: StrPath | None = None,
+    mode: int = 0o777,
+    exist_ok: bool = False,
+    stringify: bool = False,
+) -> Sequence[Path] | Sequence[str]:
+    """Recursively create directories.
+
+    Args:
+        paths: The directory paths to create.
+        root: The root directory to prepend to each path. Defaults to None.
+        mode: The mode to use when creating the directories. Defaults to 0o777.
+        exist_ok: Whether to suppress OSError if any of the paths already exist.
+            Defaults to False.
+        stringify: Whether to return the paths as strings. Defaults to False.
+
+    Returns:
+        The created directory paths as Path objects or strings,
+            depending on the value of `stringify`.
+
+    Raises:
+        ValueError: If `mode` is outside the range 0o1-0o7777
+            (not checked on Windows, where the mode is ignored).
+        DirectoryNotFoundError: If `root` is provided and does not exist.
+        NotADirectoryError: If `root` is provided and is not a directory.
+        ValueError: If `root` is provided and any of the paths are absolute.
+        OSError: If `exist_ok` is False and any of the paths already exist.
+        OSError: If any of the paths are not directories.
+    """
+    _validate_mode(mode)
+    paths = _join_root_if_provided(paths, root)
+    directories = [Path(p) for p in paths]
+    for directory in directories:
+        directory.mkdir(mode=mode, parents=True, exist_ok=exist_ok)
+    return stringify_paths(directories) if stringify else directories
+
+
+# ========================== #
+#            Empty           #
+# ========================== #
+
+
+def dir_empty_unsafe(path: StrPath) -> bool:
+    """Check if a directory is empty without existence checks."""
+    with os.scandir(path) as it:
+        return not any(it)
+
+
+def dirs_empty_unsafe(paths: StrPaths, *, root: StrPath | None = None) -> bool:
+    """Check if directories are empty without existence checks."""
+    if root is not None:
+        paths = [Path(root) / p for p in paths]
+    return all(dir_empty_unsafe(p) for p in paths)
+
+
+def dir_empty(path: StrPath) -> bool:
+    """Check if a directory is empty.
+
+    Args:
+        path: The directory path to check.
+
+    Returns:
+        True if the directory is empty, False otherwise.
+
+    Raises:
+        DirectoryNotFoundError: If the path does not exist.
+        NotADirectoryError: If the path is not a directory.
+    """
+    path = ensure_dir_exists(path)
+    return dir_empty_unsafe(path)
+
+
+def dirs_empty(paths: StrPaths, *, root: StrPath | None = None) -> bool:
+    """Check if directories are empty.
+
+    Args:
+        paths: A sequence of directory paths to check.
+        root: The root directory to prepend to each path. Defaults to None.
+
+    Returns:
+        True if all directories are empty, False otherwise.
+
+    Raises:
+        DirectoryNotFoundError: If `root` is provided and does not exist.
+        DirectoryNotFoundError: If any of the paths do not exist.
+        NotADirectoryError: If `root` is provided and is not a directory.
+        NotADirectoryError: If any of the paths are not directories.
+        ValueError: If `root` is provided and any of the paths are absolute.
+    """
+    paths = ensure_dirs_exist(paths, root=root)
+    return all(dir_empty_unsafe(p) for p in paths)

{kaparoo_python-0.1.11 → kaparoo_python-0.2.0}/kaparoo/filesystem/exceptions.py

@@ -1,8 +1,10 @@
+from __future__ import annotations
+
 __all__ = ("DirectoryNotFoundError", "NotAFileError")
 
 
 class DirectoryNotFoundError(FileNotFoundError):
-    """Exception to raise when a dictionary does not exist.
+    """Raised when a directory does not exist.
 
     Note:
         Since this exception inherits from `FileNotFoundError`,
@@ -12,4 +14,4 @@ class DirectoryNotFoundError(FileNotFoundError):
 
 
 class NotAFileError(OSError):
-    """Exception to raise when a path exists but is not a file."""
+    """Raised when a path exists but is not a file."""