simplibs-path 0.1.0__py3-none-any.whl

simplibs/path/rules/_helpers/build_path_rule_exception.py

@@ -0,0 +1,71 @@
+from typing import Any
+from simplibs.exception import ValidationError
+# Outers
+from ...logic.checks._helpers import to_path
+# Inners
+from .build_not_a_path_exception import build_not_a_path_exception
+
+
+def build_path_rule_exception(
+    *,
+    error_name: str,
+    expected: str,
+    value: Any,
+    value_name: str | None,
+    context: str | None,
+    problem: str,
+    how_to_fix: str,
+    exception: type[Exception] = ValueError,
+) -> Exception:
+    """Build the failure card of a path rule, covering both failure branches.
+
+    Args:
+        error_name: The calling rule's `error_name`.
+        expected: The calling rule's `expected` sentence.
+        value: The rejected value.
+        value_name: The label passed to `build_exception`.
+        context: The context passed to `build_exception`.
+        problem: What is wrong with a value that IS a usable path.
+        how_to_fix: How to fix that.
+        exception: The exception type wrapped for that case.
+
+    Returns:
+        A `ValidationError`. If `value` is not a usable path at all, the
+        generic "not a path" card is returned instead of `problem`/`how_to_fix`.
+    """
+
+    # 1. Not a usable path — the shared card
+    if to_path(value) is None:
+        return build_not_a_path_exception(
+            error_name=error_name,
+            expected=expected,
+            value=value,
+            value_name=value_name,
+            context=context,
+        )
+
+    # 2. A usable path that fails the rule's own condition
+    return ValidationError(
+        error_name=error_name,
+        label=value_name,
+        expected=expected,
+        value=value,
+        problem=problem,
+        context=context,
+        how_to_fix=how_to_fix,
+        exception=exception,
+    )
+
+
+_DESIGN_NOTES = """
+# build_path_rule_exception — the Whole `build_exception` of a Path Rule
+
+## Purpose
+Reduces a path rule's `build_exception` to its own three sentences
+(`expected`, `problem`, `how_to_fix`): the type-or-blank branch is decided
+here, identically for all of them.
+
+## Keyword-Only
+Seven values of the same kind (`str`) travel together; naming each at the
+call site is what keeps `problem` and `how_to_fix` from being swapped.
+"""

simplibs/path/rules/_helpers/check_path.py

@@ -0,0 +1,48 @@
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+# Outers
+from ...logic.checks._helpers import to_path
+
+
+def check_path(
+    value: Any,
+    check: Callable[[Path], bool],
+) -> bool:
+    """Run a filesystem check on a value, answering False instead of raising.
+
+    Args:
+        value: Any value; only a usable `str`/`Path` is checked.
+        check: A callable taking the `Path` — e.g. `Path.is_file`.
+
+    Returns:
+        The strict `bool` answer of `check`, or `False` if `value` is not a
+        usable path or the operating system refuses to answer.
+    """
+
+    # 1. Anything that cannot be turned into a path fails the rule
+    path = to_path(value)
+    if path is None:
+        return False
+
+    # 2. Ask the filesystem; a refusal (permissions, bad name) is a "no"
+    try:
+        return bool(check(path))
+    except (OSError, ValueError):
+        return False
+
+
+_DESIGN_NOTES = """
+# check_path — The Never-Raising Wrapper Every Filesystem Rule Needs
+
+## Purpose
+`Rule.is_valid` must return a strict `bool` and never raise. The pathlib
+predicates mostly honor that for "no such file", but not for everything:
+`Path.is_file()` re-raises `PermissionError` for a path behind a folder you
+may not enter. One wrapper turns every such case into `False`, so no rule
+has to remember the `try`.
+
+## Strict `bool`
+`bool(check(path))` — the contract tests compare with `is True`/`is False`,
+so a truthy non-bool (an `int` from a custom check) is normalized here.
+"""

simplibs/path/rules/_validations/__init__.py

@@ -0,0 +1,24 @@
+from .raise_has_suffix_invalid_suffix_error import raise_has_suffix_invalid_suffix_error
+from .raise_has_suffix_no_suffixes_error import raise_has_suffix_no_suffixes_error
+from .raise_rule_param_not_bool_error import raise_rule_param_not_bool_error
+from .raise_rule_param_not_callable_error import raise_rule_param_not_callable_error
+from .raise_rule_param_not_path_error import raise_rule_param_not_path_error
+
+
+_DESIGN_NOTES = """
+# Path Rules Diagnostic Helpers Sub-Package
+
+## Purpose
+Internal diagnostic helpers raising `ParamError` when a rule is constructed
+with invalid arguments.
+
+## Internal Components Registry
+
+| Component                                | Type     | Description                                                       |
+| :--------------------------------------- | :------- | :---------------------------------------------------------------- |
+| `raise_has_suffix_invalid_suffix_error`  | Function | A `HasSuffix` suffix has the wrong shape.                         |
+| `raise_has_suffix_no_suffixes_error`     | Function | `HasSuffix()` was created without any suffix.                     |
+| `raise_rule_param_not_bool_error`        | Function | An on/off option is not a `bool`.                                 |
+| `raise_rule_param_not_callable_error`    | Function | A wrapped rule/predicate is not callable.                         |
+| `raise_rule_param_not_path_error`        | Function | A root/path option is not a usable path.                          |
+"""

simplibs/path/rules/_validations/raise_has_suffix_invalid_suffix_error.py

@@ -0,0 +1,35 @@
+from typing import Any, NoReturn
+from simplibs.exception import ParamError
+
+
+def raise_has_suffix_invalid_suffix_error(suffix: Any) -> NoReturn:
+    """Raise ParamError when a HasSuffix suffix has an invalid shape."""
+
+    # 1. Raise structured ParamError wrapping a ValueError
+    raise ParamError(
+        error_name="HAS_SUFFIX_INVALID_SUFFIX_ERROR",
+        label="HasSuffix.suffixes",
+        value=suffix,
+        problem=(
+            f"{suffix!r} is not a valid file suffix.",
+            "A suffix must be an empty string (no suffix) or a string such as '.txt', "
+            "without any path separator.",
+        ),
+        expected="Strings such as '.py', '.tar.gz', or '' for a name without a suffix.",
+        how_to_fix=(
+            "Start each suffix with a dot, e.g. '.py' instead of 'py'.",
+            "Remove path separators from the suffix.",
+        ),
+        exception=ValueError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_has_suffix_invalid_suffix_error — Suffix Shape Guard
+
+## Purpose
+The most common mistake is `HasSuffix("py")` — no dot, so it would match
+names merely *ending* in "py". Rejecting the shape up front prevents a rule
+that silently selects the wrong files. The shape rule is the library-wide
+`is_valid_suffix`, shared with `change_suffix`.
+"""

simplibs/path/rules/_validations/raise_has_suffix_no_suffixes_error.py

@@ -0,0 +1,31 @@
+from typing import NoReturn
+from simplibs.exception import ParamError
+
+
+def raise_has_suffix_no_suffixes_error() -> NoReturn:
+    """Raise ParamError when HasSuffix is constructed without any suffix."""
+
+    # 1. Raise structured ParamError wrapping a ValueError
+    raise ParamError(
+        error_name="HAS_SUFFIX_NO_SUFFIXES_ERROR",
+        label="HasSuffix.suffixes",
+        value=(),
+        problem=(
+            "HasSuffix() was created without any suffix.",
+            "A rule without a suffix to look for could never accept or reject anything.",
+        ),
+        expected="At least one suffix, e.g. HasSuffix('.py') or HasSuffix('.md', '.rst').",
+        how_to_fix=(
+            "Pass one or more suffixes: HasSuffix('.py').",
+        ),
+        exception=ValueError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_has_suffix_no_suffixes_error — Empty Rule Guard
+
+## Purpose
+Mirrors the "at least one rule" guard of `AllOf`/`AnyOf`: `HasSuffix()` with
+nothing to look for is almost certainly a forgotten argument.
+"""

simplibs/path/rules/_validations/raise_rule_param_not_bool_error.py

@@ -0,0 +1,37 @@
+from typing import Any, NoReturn
+from simplibs.exception import ParamError
+
+
+def raise_rule_param_not_bool_error(
+    rule_name: str,
+    param_name: str,
+    value: Any,
+) -> NoReturn:
+    """Raise ParamError when a rule's boolean constructor parameter is not a bool."""
+
+    # 1. Raise structured ParamError wrapping a TypeError
+    raise ParamError(
+        error_name="RULE_PARAM_NOT_BOOL_ERROR",
+        label=f"{rule_name}.{param_name}",
+        value=value,
+        problem=(
+            f"Parameter '{param_name}' of {rule_name}() must be a bool, "
+            f"got {value!r} of type '{type(value).__name__}'.",
+        ),
+        expected="True or False.",
+        how_to_fix=(
+            f"Pass True or False as '{param_name}'.",
+        ),
+        exception=TypeError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_rule_param_not_bool_error — Boolean Option Guard
+
+## Purpose
+`ignore_case`, `resolve_symlinks`, `allow_equal`, `portable` and
+`check_attributes` are on/off switches. A truthy string such as `"yes"` would
+be accepted by Python but almost certainly signals a mistake, so the rules
+require a real `bool` and report anything else at construction time.
+"""

simplibs/path/rules/_validations/raise_rule_param_not_callable_error.py

@@ -0,0 +1,36 @@
+from typing import Any, NoReturn
+from simplibs.exception import ParamError
+
+
+def raise_rule_param_not_callable_error(
+    rule_name: str,
+    param_name: str,
+    value: Any,
+) -> NoReturn:
+    """Raise ParamError when a rule's rule-or-callable parameter is not callable."""
+
+    # 1. Raise structured ParamError wrapping a TypeError
+    raise ParamError(
+        error_name="RULE_PARAM_NOT_CALLABLE_ERROR",
+        label=f"{rule_name}.{param_name}",
+        value=value,
+        problem=(
+            f"Parameter '{param_name}' of {rule_name}() must be a Rule or a callable, "
+            f"got {value!r} of type '{type(value).__name__}'.",
+        ),
+        expected="A Rule instance or a callable taking one value and returning a bool.",
+        how_to_fix=(
+            f"Pass a Rule (e.g. StartsWith('test_')) or a function as '{param_name}'.",
+        ),
+        exception=TypeError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_rule_param_not_callable_error — Operand Guard
+
+## Purpose
+`NameIs`, `StemIs` and `ParentNameIs` wrap another rule. A value that is not
+callable (a string, `None`) could never be evaluated, so it is reported when
+the rule is built, not on first use.
+"""

simplibs/path/rules/_validations/raise_rule_param_not_path_error.py

@@ -0,0 +1,37 @@
+from typing import Any, NoReturn
+from simplibs.exception import ParamError
+
+
+def raise_rule_param_not_path_error(
+    rule_name: str,
+    param_name: str,
+    value: Any,
+) -> NoReturn:
+    """Raise ParamError when a rule's path constructor parameter is not a usable path."""
+
+    # 1. Raise structured ParamError wrapping a TypeError
+    raise ParamError(
+        error_name="RULE_PARAM_NOT_PATH_ERROR",
+        label=f"{rule_name}.{param_name}",
+        value=value,
+        problem=(
+            f"Parameter '{param_name}' of {rule_name}() must be a non-blank str or a Path "
+            f"without a null byte, got {value!r} of type '{type(value).__name__}'.",
+        ),
+        expected="A non-blank string or a Path instance.",
+        how_to_fix=(
+            f"Pass a directory path as '{param_name}', e.g. Path('src') or 'src'.",
+        ),
+        exception=TypeError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_rule_param_not_path_error — Path Option Guard
+
+## Purpose
+`IsWithin(root)` is meaningless with a blank or non-path root (it would
+quietly mean "the current directory" or never match). The same `to_path`
+conversion the rule uses at evaluation time decides here, so "accepted at
+construction" and "usable at evaluation" cannot disagree.
+"""

simplibs/path/rules/filesystem/IsDir.py

@@ -0,0 +1,70 @@
+from pathlib import Path
+from typing import Any
+from simplibs.rules import Rule
+# Outers
+from .._helpers import build_path_rule_exception, check_path
+
+
+class IsDir(Rule):
+    """Path must be an existing directory (or a symlink to one).
+
+    Rule:
+        Path(value).is_dir()
+
+    Example:
+        validate(root, IsDir())  # or: IsDir() >> CollectFiles()
+    """
+
+    __slots__ = ()
+
+    # ----------------------------------------------------------------------
+    # Rule definition
+    # ----------------------------------------------------------------------
+    def is_valid(self, value: Any) -> bool:
+
+        # 1. Ask the filesystem — a refusal or a non-path is simply a failed check
+        return check_path(value, Path.is_dir)
+
+    # ----------------------------------------------------------------------
+    # Description definition
+    # ----------------------------------------------------------------------
+    def describe(self) -> str:
+
+        # 1. Fixed noun phrase
+        return "existing directory"
+
+    # ----------------------------------------------------------------------
+    # Exception definition
+    # ----------------------------------------------------------------------
+    def build_exception(
+        self,
+        value: Any,
+        value_name: str | None = None,
+        context: str | None = None,
+    ) -> Exception:
+
+        # 1. Build the exception (the not-a-path branch is handled by the helper)
+        return build_path_rule_exception(
+            error_name="IS_DIR_ERROR",
+            expected="an existing directory",
+            value=value,
+            value_name=value_name,
+            context=context,
+            problem=f"Path {value!r} is not an existing directory.",
+            how_to_fix="Provide a path to an existing directory.",
+        )
+
+
+_DESIGN_NOTES = """
+# IsDir — Existing directory
+
+## Purpose
+The natural head of a pipeline: `IsDir() >> CollectFiles()` — check the
+input, then pass it on unchanged (`Action` turns the rule into a `guard`).
+
+## Follows Symlinks
+A symlink to a directory is a directory here, as for every pathlib call.
+
+## Description
+`describe()` returns "existing directory" — a short noun phrase containers compose into larger texts ("not existing directory", "... & existing directory"); the failure card keeps its own `expected` sentence.
+"""

simplibs/path/rules/filesystem/IsEmptyDir.py

@@ -0,0 +1,76 @@
+from typing import Any
+from simplibs.rules import Rule
+# Outers
+from ...logic.checks._helpers import to_path
+from ...logic.checks import is_empty_dir
+from .._helpers import build_path_rule_exception
+
+
+class IsEmptyDir(Rule):
+    """Path must be an existing directory with no entries.
+
+    Rule:
+        is_empty_dir(value)
+
+    Example:
+        validate(output_dir, IsEmptyDir())
+    """
+
+    __slots__ = ()
+
+    # ----------------------------------------------------------------------
+    # Rule definition
+    # ----------------------------------------------------------------------
+    def is_valid(self, value: Any) -> bool:
+
+        # 1. Anything that cannot be turned into a path fails
+        path = to_path(value)
+        if path is None:
+            return False
+
+        # 2. Delegate to the plain predicate (its own validation is skipped — the input is checked)
+        return is_empty_dir(path, _validate_call=False)
+
+    # ----------------------------------------------------------------------
+    # Description definition
+    # ----------------------------------------------------------------------
+    def describe(self) -> str:
+
+        # 1. Fixed noun phrase
+        return "empty directory"
+
+    # ----------------------------------------------------------------------
+    # Exception definition
+    # ----------------------------------------------------------------------
+    def build_exception(
+        self,
+        value: Any,
+        value_name: str | None = None,
+        context: str | None = None,
+    ) -> Exception:
+
+        # 1. Build the exception (the not-a-path branch is handled by the helper)
+        return build_path_rule_exception(
+            error_name="IS_EMPTY_DIR_ERROR",
+            expected="an existing empty directory",
+            value=value,
+            value_name=value_name,
+            context=context,
+            problem=f"Path {value!r} is not an existing, empty directory.",
+            how_to_fix="Provide a path to an existing directory that contains nothing.",
+        )
+
+
+_DESIGN_NOTES = """
+# IsEmptyDir — Empty directory
+
+## Purpose
+"Only write into an empty folder", "this scan found nothing to clean up".
+
+## Delegates to `is_empty_dir`
+Reads the first entry only and treats an unlistable directory as *not* empty
+(emptiness unknown) — see the function's notes.
+
+## Description
+`describe()` returns "empty directory" — a short noun phrase containers compose into larger texts ("not empty directory", "... & empty directory"); the failure card keeps its own `expected` sentence.
+"""

simplibs/path/rules/filesystem/IsEmptyFile.py

@@ -0,0 +1,76 @@
+from pathlib import Path
+from typing import Any
+from simplibs.rules import Rule
+# Outers
+from .._helpers import build_path_rule_exception, check_path
+
+
+def _is_empty_file(path: Path) -> bool:
+    """True for a regular file of size zero."""
+    return path.is_file() and path.stat().st_size == 0
+
+
+class IsEmptyFile(Rule):
+    """Path must be an existing regular file of size zero.
+
+    Rule:
+        Path(value).is_file() and Path(value).stat().st_size == 0
+
+    Example:
+        exclude_filter = IsEmptyFile()
+    """
+
+    __slots__ = ()
+
+    # ----------------------------------------------------------------------
+    # Rule definition
+    # ----------------------------------------------------------------------
+    def is_valid(self, value: Any) -> bool:
+
+        # 1. Ask the filesystem — a refusal or a non-path is simply a failed check
+        return check_path(value, _is_empty_file)
+
+    # ----------------------------------------------------------------------
+    # Description definition
+    # ----------------------------------------------------------------------
+    def describe(self) -> str:
+
+        # 1. Fixed noun phrase
+        return "empty file"
+
+    # ----------------------------------------------------------------------
+    # Exception definition
+    # ----------------------------------------------------------------------
+    def build_exception(
+        self,
+        value: Any,
+        value_name: str | None = None,
+        context: str | None = None,
+    ) -> Exception:
+
+        # 1. Build the exception (the not-a-path branch is handled by the helper)
+        return build_path_rule_exception(
+            error_name="IS_EMPTY_FILE_ERROR",
+            expected="an existing empty file",
+            value=value,
+            value_name=value_name,
+            context=context,
+            problem=f"Path {value!r} is not an existing, empty file.",
+            how_to_fix="Provide a path to an existing file whose size is zero bytes.",
+        )
+
+
+_DESIGN_NOTES = """
+# IsEmptyFile — Empty file
+
+## Purpose
+Skipping files that carry no content (`exclude_filter=IsEmptyFile()`), or
+asserting that a file was just created.
+
+## Size, Not Content
+A file with a single space is not empty. Whitespace-only content is a
+question for the file library, which reads content.
+
+## Description
+`describe()` returns "empty file" — a short noun phrase containers compose into larger texts ("not empty file", "... & empty file"); the failure card keeps its own `expected` sentence.
+"""

simplibs/path/rules/filesystem/IsFile.py

@@ -0,0 +1,76 @@
+from pathlib import Path
+from typing import Any
+from simplibs.rules import Rule
+# Outers
+from .._helpers import build_path_rule_exception, check_path
+
+
+class IsFile(Rule):
+    """Path must be an existing regular file (or a symlink to one).
+
+    Rule:
+        Path(value).is_file()
+
+    Example:
+        include_filter = IsFile() & HasSuffix(".py")
+    """
+
+    __slots__ = ()
+
+    # ----------------------------------------------------------------------
+    # Rule definition
+    # ----------------------------------------------------------------------
+    def is_valid(self, value: Any) -> bool:
+
+        # 1. Ask the filesystem — a refusal or a non-path is simply a failed check
+        return check_path(value, Path.is_file)
+
+    # ----------------------------------------------------------------------
+    # Description definition
+    # ----------------------------------------------------------------------
+    def describe(self) -> str:
+
+        # 1. Fixed noun phrase
+        return "existing file"
+
+    # ----------------------------------------------------------------------
+    # Exception definition
+    # ----------------------------------------------------------------------
+    def build_exception(
+        self,
+        value: Any,
+        value_name: str | None = None,
+        context: str | None = None,
+    ) -> Exception:
+
+        # 1. Build the exception (the not-a-path branch is handled by the helper)
+        return build_path_rule_exception(
+            error_name="IS_FILE_ERROR",
+            expected="an existing file",
+            value=value,
+            value_name=value_name,
+            context=context,
+            problem=f"Path {value!r} is not an existing file.",
+            how_to_fix="Provide a path to an existing regular file.",
+        )
+
+
+_DESIGN_NOTES = """
+# IsFile — Existing file
+
+## Purpose
+"Is this a file I can treat as one?" — typically the first gate of a
+pipeline step that reads content.
+
+## Follows Symlinks
+A symlink to a file is a file; a broken symlink, a directory, a FIFO or a
+device is not.
+
+## Never Raises
+`Path.is_file()` itself re-raises `PermissionError` for a path behind a folder
+you may not enter; `check_path` turns that into `False`, as `Rule.is_valid`
+requires.
+
+## Description
+`describe()` returns "existing file" — a short noun phrase containers compose into larger texts ("not existing file", "... & existing file"); the failure card keeps its own `expected` sentence.
+"""