kaparoo-python 0.1.12__py3-none-any.whl → 0.2.0__py3-none-any.whl

kaparoo/data/{files/base.py → sequence.py}

@@ -6,40 +6,34 @@ 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]):
+class DataSequence[T](Sequence[T]):
     @abstractmethod
-    def __init__(self: Self, path: StrPath) -> None:
+    def __init__(self, path: StrPath) -> None:
         raise NotImplementedError
 
     @abstractmethod
-    def __len__(self: Self) -> int:
+    def __len__(self) -> int:
         raise NotImplementedError
 
     @overload
-    def __getitem__(self: Self, index: int, /) -> T_co:
-        pass
+    def __getitem__(self, index: int, /) -> T: ...
 
     @overload
-    def __getitem__(self: Self, index: slice, /) -> Sequence[T_co]:
-        pass
+    def __getitem__(self, index: slice, /) -> Sequence[T]: ...
 
-    def __getitem__(self: Self, index: int | slice, /) -> T_co | Sequence[T_co]:
+    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: Self, index: int) -> T_co:
+    def by_index(self, index: int) -> T:
         raise NotImplementedError
 
-    def by_indices(self: Self, indices: Sequence[int]) -> Sequence[T_co]:
+    def by_indices(self, indices: Sequence[int]) -> Sequence[T]:
         return [self.by_index(index) for index in indices]

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/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/filesystem/directory.py

@@ -1,33 +1,28 @@
 from __future__ import annotations
 
 __all__ = (
-    # make
-    "make_dirs",
-    # empty
     "dir_empty",
+    "dir_empty_unsafe",
     "dirs_empty",
-    # search
-    "get_paths",
-    "get_files",
-    "get_dirs",
+    "dirs_empty_unsafe",
+    "make_dir",
+    "make_dirs",
 )
 
 import os
-import random
 from pathlib import Path
 from typing import TYPE_CHECKING, overload
 
 from kaparoo.filesystem.existence import (
     _join_root_if_provided,
-    dir_exists,
+    _validate_mode,
     ensure_dir_exists,
     ensure_dirs_exist,
-    file_exists,
 )
-from kaparoo.filesystem.utils import stringify_paths
+from kaparoo.filesystem.utils import stringify_path, stringify_paths
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Sequence
+    from collections.abc import Sequence
     from typing import Literal
 
     from kaparoo.filesystem.types import StrPath, StrPaths
@@ -38,13 +33,112 @@ if TYPE_CHECKING:
 # ========================== #
 
 
+@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,
-) -> StrPaths:
+    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:
@@ -53,21 +147,27 @@ def make_dirs(
         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 directory paths that were created.
+        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)
-    for path in paths:
-        os.makedirs(path, mode, exist_ok)
-    return paths
+    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
 
 
 # ========================== #
@@ -81,10 +181,10 @@ def dir_empty_unsafe(path: StrPath) -> bool:
         return not any(it)
 
 
-def dirs_empty_unsafe(paths: StrPaths, root: StrPath | None = None) -> bool:
+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 = [os.path.join(root, p) for p in paths]
+        paths = [Path(root) / p for p in paths]
     return all(dir_empty_unsafe(p) for p in paths)
 
 
@@ -105,7 +205,7 @@ def dir_empty(path: StrPath) -> bool:
     return dir_empty_unsafe(path)
 
 
-def dirs_empty(paths: StrPaths, root: StrPath | None = None) -> bool:
+def dirs_empty(paths: StrPaths, *, root: StrPath | None = None) -> bool:
     """Check if directories are empty.
 
     Args:
@@ -117,303 +217,10 @@ def dirs_empty(paths: StrPaths, root: StrPath | None = None) -> bool:
 
     Raises:
         DirectoryNotFoundError: If `root` is provided and does not exist.
-        DirectoryNotEmptyError: If any of the paths do 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)
-
-
-# ========================== #
-#           Search           #
-# ========================== #
-
-
-@overload
-def get_paths(
-    root: StrPath,
-    *,
-    pattern: str = "*",
-    excludes: StrPaths | None = None,
-    condition: Callable[[StrPath], bool] | None = None,
-    num_samples: int | None = None,
-    recursive: bool = False,
-    stringify: Literal[False] = False,
-) -> Sequence[Path]:
-    ...
-
-
-@overload
-def get_paths(
-    root: StrPath,
-    *,
-    pattern: str = "*",
-    excludes: StrPaths | None = None,
-    condition: Callable[[StrPath], bool] | None = None,
-    num_samples: int | None = None,
-    recursive: bool = False,
-    stringify: Literal[True],
-) -> Sequence[str]:
-    ...
-
-
-@overload
-def get_paths(
-    root: StrPath,
-    *,
-    pattern: str = "*",
-    excludes: StrPaths | None = None,
-    condition: Callable[[StrPath], bool] | None = None,
-    num_samples: int | None = None,
-    recursive: bool = False,
-    stringify: bool,
-) -> Sequence[Path] | Sequence[str]:
-    ...
-
-
-def get_paths(
-    root: StrPath,
-    *,
-    pattern: str = "*",
-    excludes: StrPaths | None = None,
-    condition: Callable[[StrPath], bool] | None = None,
-    num_samples: int | None = None,
-    recursive: bool = False,
-    stringify: bool = False,
-) -> Sequence[Path] | Sequence[str]:
-    """Get paths that match the specified criteria.
-
-    The criteria are applied in the following order:
-        `pattern` -> `excludes` -> `condition` -> `num_samples`
-
-    Args:
-        root: The root directory to search.
-        pattern: The glob pattern to search for. Defaults to "*".
-        excludes: A sequence of paths to exclude from the search. Both absolute
-            and relative paths are supported. Defaults to None.
-        condition: A predicate function to filter the paths. Only paths that satisfy
-            the predicate are returned. Defaults to None.
-        num_samples: The maximum number of paths to return. If provided, only the
-            `num_samples` paths are randomly selected and returned. Defaults to None.
-        recursive: Whether to search recursively in the root directory. Defaults to False.
-        stringify: Whether to return the paths as strings. Defaults to False.
-
-    Returns:
-        The paths that match the specified criteria as a sequence of Path objects
-            or strings, depending on the value of `stringify`.
-
-    Raises:
-        DirectoryNotFoundError: If the root directory does not exist.
-        NotADirectoryError: If the root directory is not a directory.
-        ValueError: If `num_samples` is not greater than 0.
-    """
-    root = ensure_dir_exists(root)
-
-    paths = list(root.rglob(pattern) if recursive else root.glob(pattern))
-
-    excludes_set = {root}
-    if excludes:
-        resolve = lambda p: p if p.is_relative_to(root) else root / p  # noqa: E731
-        excludes_set.update(resolve(Path(e)) for e in excludes)
-
-    paths = [p for p in paths if p not in excludes_set]
-
-    if callable(condition):
-        paths = [p for p in paths if condition(p)]
-
-    if isinstance(num_samples, int) and num_samples < len(paths):
-        if num_samples <= 0:
-            raise ValueError(f"num_samples must be greater than 0 (got {num_samples})")
-        paths = random.sample(paths, num_samples)
-
-    return stringify_paths(paths) if stringify else paths
-
-
-@overload
-def get_files(
-    root: StrPath,
-    *,
-    pattern: str = "*",
-    excludes: StrPaths | None = None,
-    condition: Callable[[StrPath], bool] | None = None,
-    num_samples: int | None = None,
-    recursive: bool = False,
-    stringify: Literal[False] = False,
-) -> Sequence[Path]:
-    ...
-
-
-@overload
-def get_files(
-    root: StrPath,
-    *,
-    pattern: str = "*",
-    excludes: StrPaths | None = None,
-    condition: Callable[[StrPath], bool] | None = None,
-    num_samples: int | None = None,
-    recursive: bool = False,
-    stringify: Literal[True],
-) -> Sequence[str]:
-    ...
-
-
-@overload
-def get_files(
-    root: StrPath,
-    *,
-    pattern: str = "*",
-    excludes: StrPaths | None = None,
-    condition: Callable[[StrPath], bool] | None = None,
-    num_samples: int | None = None,
-    recursive: bool = False,
-    stringify: bool,
-) -> Sequence[Path] | Sequence[str]:
-    ...
-
-
-def get_files(
-    root: StrPath,
-    *,
-    pattern: str = "*",
-    excludes: StrPaths | None = None,
-    condition: Callable[[StrPath], bool] | None = None,
-    num_samples: int | None = None,
-    recursive: bool = False,
-    stringify: bool = False,
-) -> Sequence[Path] | Sequence[str]:
-    """Get file paths that match the specified criteria.
-
-    The criteria are applied in the following order:
-        `pattern` -> `excludes` -> `condition` -> `num_samples`
-
-    Args:
-        root: The root directory to search.
-        pattern: The glob pattern to search for. Defaults to "*".
-        excludes: A sequence of paths to exclude from the search. Both absolute
-            and relative paths are supported. Defaults to None.
-        condition: A predicate function to filter the paths. Only paths that satisfy
-            the predicate are returned. Defaults to None.
-        num_samples: The maximum number of paths to return. If provided, only the
-            `num_samples` paths are randomly selected and returned. Defaults to None.
-        recursive: Whether to search recursively in the root directory. Defaults to False.
-        stringify: Whether to return the paths as strings. Defaults to False.
-
-    Returns:
-        The file paths that match the specified criteria as a sequence of Path objects
-            or strings, depending on the value of `stringify`.
-
-    Raises:
-        DirectoryNotFoundError: If the root directory does not exist.
-        NotADirectoryError: If the root directory is not a directory.
-        ValueError: If `num_samples` is not greater than 0.
-    """
-    if callable(condition):
-        file_condition = lambda path: file_exists(path) and condition(path)  # noqa: E731
-    else:
-        file_condition = file_exists
-
-    return get_paths(
-        root,
-        pattern=pattern,
-        excludes=excludes,
-        condition=file_condition,
-        num_samples=num_samples,
-        recursive=recursive,
-        stringify=stringify,
-    )
-
-
-@overload
-def get_dirs(
-    root: StrPath,
-    *,
-    pattern: str = "*",
-    excludes: StrPaths | None = None,
-    condition: Callable[[StrPath], bool] | None = None,
-    num_samples: int | None = None,
-    recursive: bool = False,
-    stringify: Literal[False] = False,
-) -> Sequence[Path]:
-    ...
-
-
-@overload
-def get_dirs(
-    root: StrPath,
-    *,
-    pattern: str = "*",
-    excludes: StrPaths | None = None,
-    condition: Callable[[StrPath], bool] | None = None,
-    num_samples: int | None = None,
-    recursive: bool = False,
-    stringify: Literal[True],
-) -> Sequence[str]:
-    ...
-
-
-@overload
-def get_dirs(
-    root: StrPath,
-    *,
-    pattern: str = "*",
-    excludes: StrPaths | None = None,
-    condition: Callable[[StrPath], bool] | None = None,
-    num_samples: int | None = None,
-    recursive: bool = False,
-    stringify: bool,
-) -> Sequence[Path] | Sequence[str]:
-    ...
-
-
-def get_dirs(
-    root: StrPath,
-    *,
-    pattern: str = "*",
-    excludes: StrPaths | None = None,
-    condition: Callable[[StrPath], bool] | None = None,
-    num_samples: int | None = None,
-    recursive: bool = False,
-    stringify: bool = False,
-) -> Sequence[Path] | Sequence[str]:
-    """Get directory paths that match the specified criteria.
-
-    The criteria are applied in the following order:
-        `pattern` -> `excludes` -> `condition` -> `num_samples`
-
-    Args:
-        root: The root directory to search.
-        pattern: The glob pattern to search for. Defaults to "*".
-        excludes: A sequence of paths to exclude from the search. Both absolute
-            and relative paths are supported. Defaults to None.
-        condition: A predicate function to filter the paths. Only paths that satisfy
-            the predicate are returned. Defaults to None.
-        num_samples: The maximum number of paths to return. If provided, only the
-            `num_samples` paths are randomly selected and returned. Defaults to None.
-        recursive: Whether to search recursively in the root directory. Defaults to False.
-        stringify: Whether to return the paths as strings. Defaults to False.
-
-    Returns:
-        The directory paths that match the specified criteria as a sequence of
-            Path objects or strings, depending on the value of `stringify`.
-
-    Raises:
-        DirectoryNotFoundError: If the root directory does not exist.
-        NotADirectoryError: If the root directory is not a directory.
-        ValueError: If `num_samples` is not greater than 0.
-    """
-    if callable(condition):
-        dir_condition = lambda path: dir_exists(path) and condition(path)  # noqa: E731
-    else:
-        dir_condition = dir_exists
-
-    return get_paths(
-        root,
-        pattern=pattern,
-        excludes=excludes,
-        condition=dir_condition,
-        num_samples=num_samples,
-        recursive=recursive,
-        stringify=stringify,
-    )

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."""