kaparoo-python 0.1.0__py3-none-any.whl

kaparoo/__about__.py

@@ -0,0 +1,3 @@
+# -*- coding: utf-8 -*-
+
+__version__ = "0.1.0"

kaparoo/beartype/numerics.py

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+
+__all__ = (
+    "PosInt",
+    "NegInt",
+    "NonPosInt",
+    "NonNegInt",
+    "PositiveInt",
+    "NegativeInt",
+    "NonPositiveInt",
+    "NonNegativeInt",
+)
+
+from typing import Annotated, TypeAlias
+
+from beartype.vale import Is
+
+NegativeInt: TypeAlias = Annotated[int, Is[lambda x: x < 0]]
+PositiveInt: TypeAlias = Annotated[int, Is[lambda x: x > 0]]
+NonNegativeInt: TypeAlias = Annotated[int, Is[lambda x: x >= 0]]
+NonPositiveInt: TypeAlias = Annotated[int, Is[lambda x: x <= 0]]
+
+NegInt: TypeAlias = NegativeInt
+PosInt: TypeAlias = PositiveInt
+NonPosInt: TypeAlias = NonPositiveInt
+NonNegInt: TypeAlias = NonNegativeInt

kaparoo/filesystem/__init__.py

@@ -0,0 +1,51 @@
+# -*- coding: utf-8 -*-
+
+__all__ = (
+    # exceptions
+    "DirectoryNotFoundError",
+    "NotAFileError",
+    # types
+    "StrPath",
+    "StrPaths",
+    # path
+    # - stringify
+    "stringify_path",
+    "stringify_paths",
+    # - single existence
+    "check_if_path_exists",
+    "check_if_file_exists",
+    "check_if_dir_exists",
+    # - multiple existences
+    "check_if_paths_exist",
+    "check_if_files_exist",
+    "check_if_dirs_exist",
+    # - child path(s) search
+    "get_paths",
+    "get_files",
+    "get_dirs",
+    # - empty directory check
+    "is_empty_dir",
+    "is_empty_dir_unsafe",
+    "are_empty_dirs",
+    "are_empty_dirs_unsafe",
+)
+
+from kaparoo.filesystem.exceptions import DirectoryNotFoundError, NotAFileError
+from kaparoo.filesystem.path import (
+    are_empty_dirs,
+    are_empty_dirs_unsafe,
+    check_if_dir_exists,
+    check_if_dirs_exist,
+    check_if_file_exists,
+    check_if_files_exist,
+    check_if_path_exists,
+    check_if_paths_exist,
+    get_dirs,
+    get_files,
+    get_paths,
+    is_empty_dir,
+    is_empty_dir_unsafe,
+    stringify_path,
+    stringify_paths,
+)
+from kaparoo.filesystem.types import StrPath, StrPaths

kaparoo/filesystem/exceptions.py

@@ -0,0 +1,11 @@
+# -*- coding: utf-8 -*-
+
+__all__ = ("NotAFileError", "DirectoryNotFoundError")
+
+
+class NotAFileError(OSError):
+    pass
+
+
+class DirectoryNotFoundError(FileNotFoundError):
+    pass

kaparoo/filesystem/path.py

@@ -0,0 +1,760 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+__all__ = (
+    # stringify
+    "stringify_path",
+    "stringify_paths",
+    # single existence
+    "check_if_path_exists",
+    "check_if_file_exists",
+    "check_if_dir_exists",
+    # multiple existences
+    "check_if_paths_exist",
+    "check_if_files_exist",
+    "check_if_dirs_exist",
+    # child path(s) search
+    "get_paths",
+    "get_files",
+    "get_dirs",
+    # empty directory check
+    "is_empty_dir",
+    "is_empty_dir_unsafe",
+    "are_empty_dirs",
+    "are_empty_dirs_unsafe",
+)
+
+import os
+import random
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TYPE_CHECKING, overload
+
+from kaparoo.filesystem.exceptions import DirectoryNotFoundError, NotAFileError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from typing import Literal
+
+    from kaparoo.filesystem.types import StrPath, StrPaths
+
+
+# ========================== #
+#          Stringify         #
+# ========================== #
+
+
+def stringify_path(path: StrPath) -> str:
+    """Convert a path to a string representation."""
+    return os.fspath(path)
+
+
+def stringify_paths(paths: StrPaths) -> Sequence[str]:
+    """Convert a sequence of paths to a sequence of string representations."""
+    return [stringify_path(p) for p in paths]
+
+
+# ========================== #
+#      Single Existence      #
+# ========================== #
+
+
+@overload
+def check_if_path_exists(path: StrPath, *, stringify: Literal[False] = False) -> Path:
+    ...
+
+
+@overload
+def check_if_path_exists(path: StrPath, *, stringify: Literal[True]) -> str:
+    ...
+
+
+@overload
+def check_if_path_exists(path: StrPath, *, stringify: bool) -> Path | str:
+    ...
+
+
+def check_if_path_exists(path: StrPath, *, stringify: bool = False) -> Path | str:
+    """Check if a given path exists and return it as a `Path` object.
+
+    Args:
+        path: The path to check for existence.
+        stringify: Whether to return the path as a string. Defaults to `False`.
+
+    Returns:
+        The path as a `Path` object or a string, depending on the value of `stringify`.
+
+    Raises:
+        FileNotFoundError: If the path does not exist.
+    """
+
+    if not (path := Path(path)).exists():
+        raise FileNotFoundError(f"no such path: {path}")
+
+    return stringify_path(path) if stringify else path
+
+
+@overload
+def check_if_file_exists(path: StrPath, *, stringify: Literal[False] = False) -> Path:
+    ...
+
+
+@overload
+def check_if_file_exists(path: StrPath, *, stringify: Literal[True]) -> str:
+    ...
+
+
+@overload
+def check_if_file_exists(path: StrPath, *, stringify: bool) -> Path | str:
+    ...
+
+
+def check_if_file_exists(path: StrPath, *, stringify: bool = False) -> Path | str:
+    """Check if a given path exists and is a file, and return it as a `Path` object.
+
+    Args:
+        path: The file path to check for existence.
+        stringify: Whether to return the path as a string. Defaults to `False`.
+
+    Returns:
+        The path as a `Path` object or a string, depending on the value of `stringify`.
+
+    Raises:
+        FileNotFoundError: If the path does not exist.
+        NotAFileError: If the path exists but is not a file.
+    """
+
+    if not (path := Path(path)).exists():
+        raise FileNotFoundError(f"no such file: {path}")
+    elif not path.is_file():
+        raise NotAFileError(f"not a file: {path}")
+
+    return stringify_path(path) if stringify else path
+
+
+@overload
+def check_if_dir_exists(
+    path: StrPath, *, make: bool | int = False, stringify: Literal[False] = False
+) -> Path:
+    ...
+
+
+@overload
+def check_if_dir_exists(
+    path: StrPath, *, make: bool | int = False, stringify: Literal[True]
+) -> str:
+    ...
+
+
+@overload
+def check_if_dir_exists(
+    path: StrPath, *, make: bool | int = False, stringify: bool
+) -> Path | str:
+    ...
+
+
+def check_if_dir_exists(
+    path: StrPath, *, make: bool | int = False, stringify: bool = False
+) -> Path | str:
+    """Check if a given path exists and is a directory, and return it as a `Path` object.
+
+    Args:
+        path: The directory path to check for existence.
+        make: Whether to create the directory if it does not exist. If an `int` is provided,
+            use it as the octal mode for the directory. Defaults to `False`.
+        stringify: Whether to return the path as a string. Defaults to `False`.
+
+    Returns:
+        The path as a `Path` object or a string, depending on the value of `stringify`.
+
+    Raises:
+        DirectoryNotFoundError: If the path does not exist and `make` is False.
+        NotADirectoryError: If the path exists but is not a directory.
+    """  # noqa: E501
+
+    if not (path := Path(path)).exists():
+        if make is False:
+            raise DirectoryNotFoundError(f"no such directory: {path}")
+        path.mkdir(mode=511 if make is True else make, parents=True)  # 511 == 0o777
+    elif not path.is_dir():
+        raise NotADirectoryError(f"not a directory: {path}")
+
+    return stringify_path(path) if stringify else path
+
+
+# ========================== #
+#    Multiple Existences     #
+# ========================== #
+
+
+@overload
+def check_if_paths_exist(
+    paths: StrPaths,
+    *,
+    root: StrPath | None = None,
+    stringify: Literal[False] = False,
+) -> Sequence[Path]:
+    ...
+
+
+@overload
+def check_if_paths_exist(
+    paths: StrPaths, *, root: StrPath | None = None, stringify: Literal[True]
+) -> Sequence[str]:
+    ...
+
+
+@overload
+def check_if_paths_exist(
+    paths: StrPaths, *, root: StrPath | None = None, stringify: bool
+) -> Sequence[Path] | Sequence[str]:
+    ...
+
+
+def check_if_paths_exist(
+    paths: StrPaths, *, root: StrPath | None = None, stringify: bool = False
+) -> Sequence[Path] | Sequence[str]:
+    """Check if multiple paths exist and return them as a sequence of `Path` objects.
+
+    Args:
+        paths: A sequence of paths to check for existence.
+        root: The root directory to resolve relative paths. If provided, the `paths`
+            will be resolved relative to the `root` directory. Defaults to `None`.
+        stringify: Whether to return a sequence of strings. Defaults to `False`.
+
+    Returns:
+        The paths as a sequence of `Path` objects or a sequence of strings,
+            depending on the value of `stringify`.
+
+    Raises:
+        DirectoryNotFoundError: If the `root` directory does not exist.
+        NotADirectoryError: If `root` exists but is not a directory.
+        FileNotFoundError: If any of the paths does not exist.
+    """
+
+    if root is not None:
+        root = check_if_dir_exists(root)
+        paths = [root / p for p in paths]
+
+    paths = [check_if_path_exists(p) for p in paths]
+
+    return stringify_paths(paths) if stringify else paths
+
+
+@overload
+def check_if_files_exist(
+    paths: StrPaths,
+    *,
+    root: StrPath | None = None,
+    stringify: Literal[False] = False,
+) -> Sequence[Path]:
+    ...
+
+
+@overload
+def check_if_files_exist(
+    paths: StrPaths, *, root: StrPath | None = None, stringify: Literal[True]
+) -> Sequence[str]:
+    ...
+
+
+@overload
+def check_if_files_exist(
+    paths: StrPaths, *, root: StrPath | None = None, stringify: bool
+) -> Sequence[Path] | Sequence[str]:
+    ...
+
+
+def check_if_files_exist(
+    paths: StrPaths, *, root: StrPath | None = None, stringify: bool = False
+) -> Sequence[Path] | Sequence[str]:
+    """Check if multiple files exist and return them as a sequence of `Path` objects.
+
+    Args:
+        paths: A sequence of file paths to check for existence.
+        root: The root directory to resolve relative paths. If provided, the `paths`
+            will be resolved relative to the `root` directory. Defaults to `None`.
+        stringify: Whether to return a sequence of strings. Defaults to `False`.
+
+    Returns:
+        The file paths as a sequence of `Path` objects or a sequence of strings,
+            depending on the value of `stringify`.
+
+    Raises:
+        DirectoryNotFoundError: If the `root` directory does not exist.
+        NotADirectoryError: If `root` exists but is not a directory.
+        FileNotFoundError: If any of the file paths does not exist.
+        NotAFileError: If any of the paths exists but is not a file.
+    """  # noqa: E501
+
+    if root is not None:
+        root = check_if_dir_exists(root)
+        paths = [root / p for p in paths]
+
+    paths = [check_if_file_exists(p) for p in paths]
+
+    return stringify_paths(paths) if stringify else paths
+
+
+@overload
+def check_if_dirs_exist(
+    paths: StrPaths,
+    *,
+    root: StrPath | None = None,
+    make: bool | int = False,
+    stringify: Literal[False] = False,
+) -> Sequence[Path]:
+    ...
+
+
+@overload
+def check_if_dirs_exist(
+    paths: StrPaths,
+    *,
+    root: StrPath | None = None,
+    make: bool | int = False,
+    stringify: Literal[True],
+) -> Sequence[str]:
+    ...
+
+
+@overload
+def check_if_dirs_exist(
+    paths: StrPaths,
+    *,
+    root: StrPath | None = None,
+    make: bool | int = False,
+    stringify: bool,
+) -> Sequence[Path] | Sequence[str]:
+    ...
+
+
+def check_if_dirs_exist(
+    paths: StrPaths,
+    *,
+    root: StrPath | None = None,
+    make: bool | int = False,
+    stringify: bool = False,
+) -> Sequence[Path] | Sequence[str]:
+    """Check if multiple directories exist and return them as a sequence of `Path` objects.
+
+    Args:
+        paths: A sequence of directory paths to check for existence.
+        root: The root directory to resolve relative paths. If provided, the `paths`
+            will be resolved relative to the `root` directory. Defaults to `None`.
+        make: Whether to create the directory if it does not exist. If an `int` is provided,
+            use it as the octal mode for the directory. Defaults to `False`.
+        stringify: Whether to return a sequence of strings. Defaults to `False`.
+
+    Returns:
+        The directory paths as a sequence of `Path` objects or a sequence of strings,
+            depending on the value of `stringify`.
+
+    Raises:
+        DirectoryNotFoundError: If the `root` directory does not exist
+        DirectoryNotFoundError: If any of the directory paths does not exist.
+        NotADirectoryError: If `root` exists but is not a directory.
+        NotADirectoryError: If any of the paths exists but is not a directory.
+    """  # noqa: E501
+
+    if root is not None:
+        root = check_if_dir_exists(root)
+        paths = [root / p for p in paths]
+
+    paths = [check_if_dir_exists(p, make=make) for p in paths]
+
+    return stringify_paths(paths) if stringify else paths
+
+
+# ========================== #
+#    Child Path(s) Search    #
+# ========================== #
+
+
+@overload
+def get_paths(
+    root: StrPath,
+    *,
+    pattern: str | None = None,
+    num_samples: int | None = None,
+    ignores: StrPaths | None = None,
+    condition: Callable[[Path], bool] | None = None,
+    recursive: bool = True,
+    stringify: Literal[False] = False,
+) -> Sequence[Path]:
+    ...
+
+
+@overload
+def get_paths(
+    root: StrPath,
+    *,
+    pattern: str | None = None,
+    num_samples: int | None = None,
+    ignores: StrPaths | None = None,
+    condition: Callable[[Path], bool] | None = None,
+    recursive: bool = True,
+    stringify: Literal[True],
+) -> Sequence[str]:
+    ...
+
+
+@overload
+def get_paths(
+    root: StrPath,
+    *,
+    pattern: str | None = None,
+    num_samples: int | None = None,
+    ignores: StrPaths | None = None,
+    condition: Callable[[Path], bool] | None = None,
+    recursive: bool = True,
+    stringify: bool,
+) -> Sequence[Path] | Sequence[str]:
+    ...
+
+
+def get_paths(
+    root: StrPath,
+    *,
+    pattern: str | None = None,
+    num_samples: int | None = None,
+    ignores: StrPaths | None = None,
+    condition: Callable[[Path], bool] | None = None,
+    recursive: bool = True,
+    stringify: bool = False,
+) -> Sequence[Path] | Sequence[str]:
+    """Get paths of files or directories in a given directory.
+
+    Args:
+        root: The directory to search for paths.
+        pattern: A glob pattern to match the paths against. Defaults to `None` and
+            automatically uses "*" to list all paths included in the `root` directory.
+        num_samples: A maximum number of paths to return. If given and its value is
+            smaller than the total number of paths, only the `num_samples` paths of the
+            total are randomly selected and returned. Hence, even using the same value
+            of `num_samples`, may return a different result. Defaults to `None`.
+        ignores: A sequence of paths to ignore. If any path in `ignores` does not start
+            with `root`, it is treated as a relative path. For example, `any/path` is
+            treated as `root/any/path`. Defaults to `None`.
+        condition: A predicate that takes a `Path` object and decides whether to include
+            the path in the results. Defaults to `None`.
+        recursive: Whether to search for paths recursively in subdirectories of the
+            `root` directory. Defaults to `True`.
+        stringify: Whether to return a sequence of strings. Defaults to `False`.
+
+    Returns:
+        The paths that match the specified criteria as a sequence of `Path` objects or a
+            sequence of strings, depending on the value of `stringify`.
+
+    Raises:
+        DirectoryNotFoundError: If `root` does not exist.
+        NotADirectoryError: If `root` exists but is not a directory.
+        ValueError: If `num_samples` is not a positive int.
+    """  # noqa: E501
+
+    root = check_if_dir_exists(root)
+
+    if not isinstance(pattern, str):
+        pattern = "*"
+
+    matched = root.rglob(pattern) if recursive else root.glob(pattern)
+    paths = [p for p in matched]
+
+    if root in paths:
+        paths.remove(root)
+
+    if not ignores:
+        ignores = []
+
+    for ignore in ignores:
+        ignore_path = Path(ignore)
+        if root not in ignore_path.parents:
+            ignore_path = root / ignore_path
+
+        if ignore_path in paths:
+            paths.remove(ignore_path)
+
+    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("`num_samples` must be a positive int")
+        paths = random.sample(paths, num_samples)
+
+    return stringify_paths(paths) if stringify else paths
+
+
+@overload
+def get_files(
+    root: StrPath,
+    *,
+    pattern: str | None = None,
+    num_samples: int | None = None,
+    ignores: StrPaths | None = None,
+    condition: Callable[[Path], bool] | None = None,
+    recursive: bool = True,
+    stringify: Literal[False] = False,
+) -> Sequence[Path]:
+    ...
+
+
+@overload
+def get_files(
+    root: StrPath,
+    *,
+    pattern: str | None = None,
+    num_samples: int | None = None,
+    ignores: StrPaths | None = None,
+    condition: Callable[[Path], bool] | None = None,
+    recursive: bool = True,
+    stringify: Literal[True],
+) -> Sequence[str]:
+    ...
+
+
+@overload
+def get_files(
+    root: StrPath,
+    *,
+    pattern: str | None = None,
+    num_samples: int | None = None,
+    ignores: StrPaths | None = None,
+    condition: Callable[[Path], bool] | None = None,
+    recursive: bool = True,
+    stringify: bool,
+) -> Sequence[Path] | Sequence[str]:
+    ...
+
+
+def get_files(
+    root: StrPath,
+    *,
+    pattern: str | None = None,
+    num_samples: int | None = None,
+    ignores: StrPaths | None = None,
+    condition: Callable[[Path], bool] | None = None,
+    recursive: bool = True,
+    stringify: bool = False,
+) -> Sequence[Path] | Sequence[str]:
+    """Get paths of files in a given directory.
+
+    Args:
+        root: The directory to search for paths.
+        pattern: A glob pattern to match the paths against. Defaults to `None` and
+            automatically uses "*" to list all paths included in the `root` directory.
+        num_samples: A maximum number of paths to return. If given and its value is
+            smaller than the total number of paths, only the `num_samples` paths of the
+            total are randomly selected and returned. Hence, even using the same value
+            of `num_samples`, may return a different result. Defaults to `None`.
+        ignores: A sequence of paths to ignore. If any path in `ignores` does not start
+            with `root`, it is treated as a relative path. For example, `any/path` is
+            treated as `root/any/path`. Defaults to `None`.
+        condition: A predicate that takes a `Path` object and decides whether to include
+            the path in the results. Defaults to `None`.
+        recursive: Whether to search for paths recursively in subdirectories of the
+            `root` directory. Defaults to `True`.
+        stringify: Whether to return a sequence of strings. Defaults to `False`.
+
+    Returns:
+        The file paths that match the specified criteria as a sequence of `Path` objects
+            or a sequence of strings, depending on the value of `stringify`.
+
+    Raises:
+        DirectoryNotFoundError: If `root` does not exist.
+        NotADirectoryError: If `root` exists but is not a directory.
+        ValueError: If `num_samples` is not a positive int.
+    """  # noqa: E501
+
+    if not callable(condition):
+        file_condition = lambda p: p.is_file()  # noqa: E731
+    else:
+        file_condition = lambda p: p.is_file() and condition(p)  # type: ignore[misc] # noqa: E501, E731
+
+    file_paths = get_paths(
+        root,
+        pattern=pattern,
+        num_samples=num_samples,
+        ignores=ignores,
+        condition=file_condition,
+        recursive=recursive,
+        stringify=stringify,
+    )
+
+    return file_paths
+
+
+@overload
+def get_dirs(
+    root: StrPath,
+    *,
+    pattern: str | None = None,
+    num_samples: int | None = None,
+    ignores: StrPaths | None = None,
+    condition: Callable[[Path], bool] | None = None,
+    recursive: bool = True,
+    stringify: Literal[False] = False,
+) -> Sequence[Path]:
+    ...
+
+
+@overload
+def get_dirs(
+    root: StrPath,
+    *,
+    pattern: str | None = None,
+    num_samples: int | None = None,
+    ignores: StrPaths | None = None,
+    condition: Callable[[Path], bool] | None = None,
+    recursive: bool = True,
+    stringify: Literal[True],
+) -> Sequence[str]:
+    ...
+
+
+@overload
+def get_dirs(
+    root: StrPath,
+    *,
+    pattern: str | None = None,
+    num_samples: int | None = None,
+    ignores: StrPaths | None = None,
+    condition: Callable[[Path], bool] | None = None,
+    recursive: bool = True,
+    stringify: bool,
+) -> Sequence[Path] | Sequence[str]:
+    ...
+
+
+def get_dirs(
+    root: StrPath,
+    *,
+    pattern: str | None = None,
+    num_samples: int | None = None,
+    ignores: StrPaths | None = None,
+    condition: Callable[[Path], bool] | None = None,
+    recursive: bool = True,
+    stringify: bool = False,
+) -> Sequence[Path] | Sequence[str]:
+    """Get paths of directories in a given directory.
+
+    Args:
+        root: The directory to search for paths.
+        pattern: A glob pattern to match the paths against. Defaults to `None` and
+            automatically uses "*" to list all paths included in the `root` directory.
+        num_samples: A maximum number of paths to return. If given and its value is
+            smaller than the total number of paths, only the `num_samples` paths of the
+            total are randomly selected and returned. Hence, even using the same value
+            of `num_samples`, may return a different result. Defaults to `None`.
+        ignores: A sequence of paths to ignore. If any path in `ignores` does not start
+            with `root`, it is treated as a relative path. For example, `any/path` is
+            treated as `root/any/path`. Defaults to `None`.
+        condition: A predicate that takes a `Path` object and decides whether to include
+            the path in the results. Defaults to `None`.
+        recursive: Whether to search for paths recursively in subdirectories of the
+            `root` directory. Defaults to `True`.
+        stringify: Whether to return a sequence of strings. Defaults to `False`.
+
+    Returns:
+        The directory paths that match the specified criteria as a sequence of `Path`
+            objects or a sequence of strings, depending on the value of `stringify`.
+
+    Raises:
+        DirectoryNotFoundError: If `root` does not exist.
+        NotADirectoryError: If `root` exists but is not a directory.
+        ValueError: If `num_samples` is not a positive int.
+    """  # noqa: E501
+
+    if not callable(condition):
+        dir_condition = lambda p: p.is_dir()  # noqa: E731
+    else:
+        dir_condition = lambda p: p.is_dir() and condition(p)  # type: ignore[misc] # noqa: E501, E731
+
+    dir_paths = get_paths(
+        root,
+        pattern=pattern,
+        num_samples=num_samples,
+        ignores=ignores,
+        condition=dir_condition,
+        recursive=recursive,
+        stringify=stringify,
+    )
+
+    return dir_paths
+
+
+# ========================== #
+#   Empty Directory Check    #
+# ========================== #
+
+
+def is_empty_dir_unsafe(path: StrPath) -> bool:
+    """Check if a directory is empty.
+
+    Unlike the function `is_empty_dir()`, this function does not check the existence of
+    the input argument `path`. Use this function only if you are sure it exists.
+
+    Args:
+        path: The path to the directory.
+
+    Returns:
+        A boolean indicating whether the directory is empty.
+    """
+    return not os.listdir(path)
+
+
+def is_empty_dir(path: StrPath) -> bool:
+    """Check if a directory is empty.
+
+    Args:
+        path: The path to the directory.
+
+    Returns:
+        A boolean indicating whether the directory is empty.
+
+    Raises:
+        DirectoryNotFoundError: If the directory does not exist.
+        NotADirectoryError: If `path` exists but is not a directory.
+    """
+    path = check_if_dir_exists(path)
+    return is_empty_dir_unsafe(path)
+
+
+def are_empty_dirs_unsafe(paths: StrPaths, *, root: StrPath | None = None) -> bool:
+    """Check if multiple directories are empty.
+
+    Unlike the function `are_empty_dirs()`, this function does not check the existence
+    of the input arguments `paths` and `root`. Use this function only if you are sure
+    they exist.
+
+    Args:
+        paths: A sequence of directory paths to check.
+        root: The root directory to resolve relative paths. Defaults to `None`.
+
+    Returns:
+        A boolean indicating whether all directories are empty.
+    """
+    if root is not None:
+        paths = [os.path.join(root, p) for p in paths]
+    return all(is_empty_dir_unsafe(p) for p in paths)
+
+
+def are_empty_dirs(paths: StrPaths, *, root: StrPath | None = None) -> bool:
+    """Check if multiple directories are empty.
+
+    Args:
+        paths: A sequence of directory paths to check.
+        root: The root directory to resolve relative paths. Defaults to `None`.
+
+    Returns:
+        A boolean indicating whether all directories are empty.
+
+    Raises:
+        DirectoryNotFoundError: If the `root` directory does not exist.
+        DirectoryNotFoundError: If any of the directory paths does not exist.
+        NotADirectoryError: If `root` exists but is not a directory.
+        NotADirectoryError: If any of the paths exists but is not a directory.
+    """
+    paths = check_if_dirs_exist(paths, root=root)
+    return all(is_empty_dir_unsafe(p) for p in paths)

kaparoo/filesystem/types.py

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+
+__all__ = ("StrPath", "StrPaths")
+
+from collections.abc import Sequence
+from os import PathLike
+from typing import TypeAlias
+
+StrPath: TypeAlias = str | PathLike[str]
+StrPaths: TypeAlias = Sequence[StrPath]

kaparoo/utils/optional.py

@@ -0,0 +1,112 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+__all__ = (
+    "replace_if_none",
+    "factory_if_none",
+    "unwrap_or_default",
+    "unwrap_or_factory",
+)
+
+from typing import TYPE_CHECKING, overload
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from kaparoo.utils.types import T, U
+
+
+@overload
+def replace_if_none(optional: None, surrogate: U) -> U:
+    ...
+
+
+@overload
+def replace_if_none(optional: T, surrogate: U) -> T:
+    ...
+
+
+def replace_if_none(optional: T | None, surrogate: U) -> T | U:
+    """Replace the value with a surrogate if it is None.
+
+    Args:
+        optional: The optional value to be checked.
+        surrogate: The surrogate value to use if `optional` is None.
+
+    Returns:
+        The `optional` value if it is not None, otherwise the `surrogate` value.
+    """
+    return surrogate if optional is None else optional
+
+
+@overload
+def factory_if_none(
+    optional: None,
+    factory: Callable[[], U],
+) -> U:
+    ...
+
+
+@overload
+def factory_if_none(
+    optional: T,
+    factory: Callable[[], U],
+) -> T:
+    ...
+
+
+def factory_if_none(
+    optional: T | None,
+    factory: Callable[[], U],
+) -> T | U:
+    """Create a value using a factory if the optional value is None.
+
+    Args:
+        optional: The optional value to be checked.
+        factory: A callable that returns the value to be used if `optional` is None.
+
+    Returns:
+        The `optional` value if it is not None, otherwise the value returned by `factory`.
+    """  # noqa: E501
+    return factory() if optional is None else optional
+
+
+def unwrap_or_default(
+    optional: T | None,
+    default: T,
+    callback: Callable[[T], T] | None = None,
+) -> T:
+    """Unwrap the value or return a default value if it is None.
+
+    Args:
+        optional: The optional value to be checked.
+        default: The default value to be returned if `optional` is None.
+        callback: An optional callable to be applied to the result. Defaults to None.
+
+    Returns:
+        The `optional` value if it is not None, otherwise the `default` value.
+        If a `callback` is provided, it is applied to the result before returning.
+    """
+    result = replace_if_none(optional, default)
+    return callback(result) if callable(callback) else result
+
+
+def unwrap_or_factory(
+    optional: T | None,
+    factory: Callable[[], T],
+    callback: Callable[[T], T] | None = None,
+) -> T:
+    """Unwrap the value or create a value using a factory if it is None.
+
+    Args:
+        optional: The optional value to be checked.
+        factory: A callable that returns the value to be used if `optional` is None.
+        callback: An optional callable to be applied to the result. Defaults to None.
+
+    Returns:
+        The `optional` value if it is not None, otherwise the value returned by `factory`.
+        If a `callback` is provided, it is applied to the result before returning.
+    """  # noqa: E501
+    result = factory_if_none(optional, factory)
+    return callback(result) if callable(callback) else result

kaparoo/utils/types.py

@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+
+from typing import TypeVar
+
+# type variables
+T = TypeVar("T")
+U = TypeVar("U")
+K = TypeVar("K")
+V = TypeVar("V")
+
+# covariant type variables
+T_co = TypeVar("T_co", covariant=True)
+U_co = TypeVar("U_co", covariant=True)
+K_co = TypeVar("K_co", covariant=True)
+V_co = TypeVar("V_co", covariant=True)

kaparoo_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.1
+Name: kaparoo-python
+Version: 0.1.0
+Summary: A Python package for (personally) common and useful features.
+Project-URL: GitHub, https://www.github.com/kaparoo/python-package
+Author-email: Jaewoo Park <kaparoo2001@gmail.com>
+License: 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.
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: beartype>=0.14.1
+Provides-Extra: dev
+Requires-Dist: black>=23.3.0; extra == 'dev'
+Requires-Dist: hatch>=1.7.0; extra == 'dev'
+Requires-Dist: mypy>=1.3.0; extra == 'dev'
+Requires-Dist: pytest-order>=1.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.3.2; extra == 'dev'
+Requires-Dist: ruff>=0.0.274; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ***kaparoo-python-package***
+
+
+
+<!-- [              MARKDOWN BADGES              ] -->
+
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Gitomoji](https://img.shields.io/badge/gitmoji-%20😜%20😍-FFDD67.svg?style=flat-square")](https://gitmoji.dev)
+
+<!-- [                    END                    ] -->
+
+
+
+<!-- [             TABLE OF CONTENTS             ] -->
+
+<details>
+<summary><strong>Table of Contents</strong></summary>
+
+- [***kaparoo-python-package***](#kaparoo-python-package)
+  - [:wave: **Overview**](#wave-overview)
+  - [:balance\_scale: **License**](#balance_scale-license)
+
+</details>
+
+<!-- [                    END                    ] -->
+
+
+
+## :wave: **Overview**
+
+A Python package for (personally) common and useful features.
+
+## :balance_scale: **License**
+
+This project is distributed under the terms of [MIT](./LICENSE) license.  

kaparoo_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+kaparoo/__about__.py,sha256=b2fCZ20Exwr_01zDxnOFRvxbDylQLSzlPJRJj2l7ZmI,50
+kaparoo/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kaparoo/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kaparoo/beartype/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kaparoo/beartype/numerics.py,sha256=rDTmnuOGhBW7wQ_9vesHqx7sHkELIxyaUwuq9TQIHa4,674
+kaparoo/filesystem/__init__.py,sha256=K9KUnRcFXZQQRTEcP5jALce0QGn2XSN0gtf7558I6iQ,1206
+kaparoo/filesystem/exceptions.py,sha256=E9IOyZdA37QefamPrG9QMV9afMcmMf3zNyKk8n4Aewk,191
+kaparoo/filesystem/path.py,sha256=FYN4alF1f3ubA72fdKhGxvDtAhyNrFyAKDZeDag8y3M,23982
+kaparoo/filesystem/types.py,sha256=qISJYLhd8rW7nOdH5GQJEPiwkxwQD5b75zZi8Fowzqg,242
+kaparoo/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kaparoo/utils/optional.py,sha256=oX05_K04xSx1mKqiDra5V4pIm8F7h_1dKtJV03ojCis,3134
+kaparoo/utils/types.py,sha256=5LNQkhtVO9QLRGHcSc6hplwPxiEeA9U_J4SSYIKQfGY,337
+kaparoo_python-0.1.0.dist-info/METADATA,sha256=QSerqz89GVxr52Y7cdr3gK8NHuPndolW1aYPZQteMa4,3876
+kaparoo_python-0.1.0.dist-info/WHEEL,sha256=9QBuHhg6FNW7lppboF2vKVbCGTVzsFykgRQjjlajrhA,87
+kaparoo_python-0.1.0.dist-info/licenses/LICENSE,sha256=_6aA_CoB_YWkSfqkGFxghm2GIsBRE2rp_g7vhz11DM8,1087
+kaparoo_python-0.1.0.dist-info/RECORD,,

kaparoo_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.18.0
+Root-Is-Purelib: true
+Tag: py3-none-any

kaparoo_python-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +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
+SOFTWARE.