simplibs-path 0.1.0__py3-none-any.whl

simplibs/path/rules/filesystem/IsPathReadable.py

@@ -0,0 +1,77 @@
+from typing import Any
+from simplibs.rules import Rule
+# Outers
+from ...logic.checks._helpers import to_path
+from ...logic.checks import is_path_readable
+from .._helpers import build_path_rule_exception
+
+
+class IsPathReadable(Rule):
+    """Path must be a file that can be read or a directory that can be listed.
+
+    Rule:
+        is_path_readable(value)
+
+    Example:
+        validate(source, IsPathReadable())
+    """
+
+    __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_path_readable(path, _validate_call=False)
+
+    # ----------------------------------------------------------------------
+    # Description definition
+    # ----------------------------------------------------------------------
+    def describe(self) -> str:
+
+        # 1. Fixed noun phrase
+        return "readable path"
+
+    # ----------------------------------------------------------------------
+    # 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_PATH_READABLE_ERROR",
+            expected="a readable file or directory",
+            value=value,
+            value_name=value_name,
+            context=context,
+            problem=f"Path {value!r} is not readable (it is missing, not a regular file or directory, or access is denied).",
+            how_to_fix="Provide a path to a file or directory you have permission to read.",
+        )
+
+
+_DESIGN_NOTES = """
+# IsPathReadable — Readable path
+
+## Purpose
+A precondition for any step that reads: the failure card says *readable*, so
+a permission problem is not mistaken for a missing file.
+
+## Delegates to `is_path_readable`
+It actually opens the file (or lists the directory) — the only check that
+agrees with the real read that follows.
+
+## Description
+`describe()` returns "readable path" — a short noun phrase containers compose into larger texts ("not readable path", "... & readable path"); the failure card keeps its own `expected` sentence.
+"""

simplibs/path/rules/filesystem/IsPathWritable.py

@@ -0,0 +1,82 @@
+from typing import Any
+from simplibs.rules import Rule
+# Outers
+from ...logic.checks._helpers import to_path
+from ...logic.checks import is_path_writable
+from .._helpers import build_path_rule_exception
+
+
+class IsPathWritable(Rule):
+    """Path must be writable now, without anything being created or changed.
+
+    Rule:
+        is_path_writable(value)
+
+    Example:
+        validate(target, IsPathWritable())
+    """
+
+    __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_path_writable(path, _validate_call=False)
+
+    # ----------------------------------------------------------------------
+    # Description definition
+    # ----------------------------------------------------------------------
+    def describe(self) -> str:
+
+        # 1. Fixed noun phrase
+        return "writable path"
+
+    # ----------------------------------------------------------------------
+    # 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_PATH_WRITABLE_ERROR",
+            expected="a writable file or directory, or a new file in a writable directory",
+            value=value,
+            value_name=value_name,
+            context=context,
+            problem=f"Path {value!r} is not writable (access is denied, its folder is missing, or the name is taken by something else).",
+            how_to_fix="Provide a path you have permission to write to, inside an existing directory.",
+        )
+
+
+_DESIGN_NOTES = """
+# IsPathWritable — Writable path
+
+## Moved and Corrected
+This rule existed in `rules/IsPathWritable.py` and delegated to a function
+that **created an empty file** for a path that did not exist. The function
+now probes without a trace (see `is_path_writable`), so the rule is safe to
+use as a pure check. The `error_name` follows the rules library's
+`<NAME>_ERROR` convention (`IS_PATH_WRITABLE_ERROR`, formerly
+`PATH_NOT_WRITABLE_ERROR`).
+
+## Accepted Values
+An existing file, an existing directory, or a path of a not-yet-existing file
+whose parent directory exists and accepts new files. A missing parent is
+`False`: creating it is `ensure_parent_dir`'s job.
+
+## Description
+`describe()` returns "writable path" — a short noun phrase containers compose into larger texts ("not writable path", "... & writable path"); the failure card keeps its own `expected` sentence.
+"""

simplibs/path/rules/filesystem/IsSymlink.py

@@ -0,0 +1,71 @@
+from pathlib import Path
+from typing import Any
+from simplibs.rules import Rule
+# Outers
+from .._helpers import build_path_rule_exception, check_path
+
+
+class IsSymlink(Rule):
+    """Path itself must be a symbolic link (working or broken).
+
+    Rule:
+        Path(value).is_symlink()
+
+    Example:
+        exclude_filter = IsSymlink()
+    """
+
+    __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_symlink)
+
+    # ----------------------------------------------------------------------
+    # Description definition
+    # ----------------------------------------------------------------------
+    def describe(self) -> str:
+
+        # 1. Fixed noun phrase
+        return "symbolic link"
+
+    # ----------------------------------------------------------------------
+    # 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_SYMLINK_ERROR",
+            expected="a symbolic link",
+            value=value,
+            value_name=value_name,
+            context=context,
+            problem=f"Path {value!r} is not a symbolic link.",
+            how_to_fix="Provide a path to a symbolic link.",
+        )
+
+
+_DESIGN_NOTES = """
+# IsSymlink — Symbolic link
+
+## Purpose
+The only rule that looks at the *link* instead of its target — which is why
+it also accepts a broken link that `PathExists` rejects.
+
+## Windows
+Creating symlinks needs privileges there, but *detecting* them does not.
+Directory junctions are reparse points, not symlinks, and answer `False`.
+
+## Description
+`describe()` returns "symbolic link" — a short noun phrase containers compose into larger texts ("not symbolic link", "... & symbolic link"); the failure card keeps its own `expected` sentence.
+"""

simplibs/path/rules/filesystem/PathExists.py

@@ -0,0 +1,75 @@
+from pathlib import Path
+from typing import Any
+from simplibs.rules import Rule
+# Outers
+from .._helpers import build_path_rule_exception, check_path
+
+
+class PathExists(Rule):
+    """Path must exist (a file, a directory, or a symlink that leads somewhere).
+
+    Rule:
+        Path(value).exists()
+
+    Example:
+        validate(path, PathExists())
+    """
+
+    __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.exists)
+
+    # ----------------------------------------------------------------------
+    # Description definition
+    # ----------------------------------------------------------------------
+    def describe(self) -> str:
+
+        # 1. Fixed noun phrase
+        return "existing path"
+
+    # ----------------------------------------------------------------------
+    # 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="PATH_EXISTS_ERROR",
+            expected="an existing path",
+            value=value,
+            value_name=value_name,
+            context=context,
+            problem=f"Path {value!r} does not exist.",
+            how_to_fix="Provide a path to an existing file or directory.",
+        )
+
+
+_DESIGN_NOTES = """
+# PathExists — Existing path
+
+## Purpose
+The most basic filesystem precondition: "is there anything at this path?".
+
+## Follows Symlinks
+`Path.exists()` follows links, so a *broken* symlink answers `False` — the
+thing it points at is missing. `IsSymlink` is the rule that sees the link
+itself.
+
+## A Check at One Moment
+The answer holds when evaluated; the file can appear or vanish right after.
+Use it as a fail-fast message, not as a guarantee (see `ensure_file`).
+
+## Description
+`describe()` returns "existing path" — a short noun phrase containers compose into larger texts ("not existing path", "... & existing path"); the failure card keeps its own `expected` sentence.
+"""

simplibs/path/rules/filesystem/__init__.py

@@ -0,0 +1,31 @@
+from .IsDir import IsDir
+from .IsEmptyDir import IsEmptyDir
+from .IsEmptyFile import IsEmptyFile
+from .IsFile import IsFile
+from .IsPathReadable import IsPathReadable
+from .IsPathWritable import IsPathWritable
+from .IsSymlink import IsSymlink
+from .PathExists import PathExists
+
+
+_DESIGN_NOTES = """
+# Path Filesystem Rules Sub-Package
+
+## Purpose
+Rules that ask the filesystem about a path. Each is a thin wrapper: pathlib
+(or a function from `checks/`) answers, `check_path` guarantees a strict
+`bool` without exceptions, and a shared helper builds the failure card.
+
+## Internal Components Registry
+
+| Component        | Type | Description                                                    |
+| :--------------- | :--- | :------------------------------------------------------------- |
+| `IsDir`          | Rule | An existing directory (or a symlink to one).                   |
+| `IsEmptyDir`     | Rule | An existing directory with no entries.                         |
+| `IsEmptyFile`    | Rule | An existing regular file of size zero.                         |
+| `IsFile`         | Rule | An existing regular file (or a symlink to one).                |
+| `IsPathReadable` | Rule | A file that can be read or a directory that can be listed.     |
+| `IsPathWritable` | Rule | A path that could be written to now, with no side effects.     |
+| `IsSymlink`      | Rule | The path itself is a symbolic link.                            |
+| `PathExists`     | Rule | Something exists at the path.                                  |
+"""

simplibs/path/rules/lexical/HasSuffix.py

@@ -0,0 +1,146 @@
+from typing import Any
+from simplibs.rules import Rule
+# Outers
+from ...logic.transformers._helpers import is_valid_suffix
+from ...logic.checks._helpers import to_path
+from .._helpers import build_path_rule_exception
+from .._validations import (
+    raise_has_suffix_invalid_suffix_error,
+    raise_has_suffix_no_suffixes_error,
+    raise_rule_param_not_bool_error,
+)
+
+
+class HasSuffix(Rule):
+    """Path must end with one of the given suffixes.
+
+    Rule:
+        the final name ends with one of `suffixes` (after a non-empty base name)
+
+    Example:
+        validate(path, HasSuffix(".py"))
+        include_filter = HasSuffix(".py", ".md")
+        HasSuffix("")        # names without any suffix
+    """
+
+    __slots__ = ("suffixes", "ignore_case", "_keys")
+
+    # ----------------------------------------------------------------------
+    # Constructor initialization
+    # ----------------------------------------------------------------------
+    def __init__(self, *suffixes: str, ignore_case: bool = True) -> None:
+
+        # 1. Parameter validation
+        if not suffixes:
+            raise_has_suffix_no_suffixes_error()
+        for suffix in suffixes:
+            if not isinstance(suffix, str) or not is_valid_suffix(suffix):
+                raise_has_suffix_invalid_suffix_error(suffix)
+        if not isinstance(ignore_case, bool):
+            raise_rule_param_not_bool_error("HasSuffix", "ignore_case", ignore_case)
+
+        # 2. Parameter assignment, with the comparison keys prepared once
+        self.suffixes = tuple(suffixes)
+        self.ignore_case = ignore_case
+        self._keys = tuple(suffix.casefold() for suffix in suffixes) if ignore_case else self.suffixes
+
+    # ----------------------------------------------------------------------
+    # 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. Compare the final name with each suffix
+        name = path.name.casefold() if self.ignore_case else path.name
+        for key in self._keys:
+
+            # 2.1 An empty suffix means "the name has no suffix at all"
+            if key == "":
+                if path.suffix == "":
+                    return True
+
+            # 2.2 Otherwise the name must end with it, after a non-empty base name
+            elif len(name) > len(key) and name.endswith(key):
+                return True
+
+        # 3. No suffix matched
+        return False
+
+    # ----------------------------------------------------------------------
+    # Description definition
+    # ----------------------------------------------------------------------
+    def describe(self) -> str:
+
+        # 1. One suffix reads "suffix '.py'", several "suffix one of '.py', '.md'"
+        if len(self.suffixes) == 1:
+            text = f"suffix {self.suffixes[0]!r}"
+        else:
+            text = "suffix one of " + ", ".join(repr(suffix) for suffix in self.suffixes)
+
+        # 2. Say so when the comparison is case-sensitive
+        return text if self.ignore_case else f"{text} (case-sensitive)"
+
+    # ----------------------------------------------------------------------
+    # 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="HAS_SUFFIX_ERROR",
+            expected=f"a path with {self.describe()}",
+            value=value,
+            value_name=value_name,
+            context=context,
+            problem=f"Path {value!r} does not have {self.describe()}.",
+            how_to_fix=f"Provide a path with {self.describe()}.",
+        )
+
+
+_DESIGN_NOTES = """
+# HasSuffix — Select by File Extension
+
+## Purpose
+The most common filter of an extraction pipeline: "only `.py` and `.md`".
+`include_filter=HasSuffix(".py", ".md")`.
+
+---
+
+## 1. Matches the End of the Name, Not `Path.suffix`
+`Path("a.tar.gz").suffix` is only `.gz`, so `HasSuffix(".tar.gz")` could never
+match by comparing it. Checking `name.endswith(suffix)` supports compound
+suffixes. A name that *is* the suffix (`.py` as a whole file name, which is a
+hidden file without an extension) does not match — a suffix needs a base name
+in front of it.
+
+## 2. `""` Means "No Suffix"
+`HasSuffix("")` selects names without an extension (`Makefile`, `.bashrc`).
+It is the one case compared through `Path.suffix`.
+
+## 3. Case-Insensitive by Default
+`README.MD` and `x.PY` are what Windows users produce; a filter that misses
+them is a surprise. `ignore_case=False` opts out. `casefold` is used instead
+of `lower` for correct Unicode comparison.
+
+## 4. Lexical — Works on Names, Not on Files
+`HasSuffix(".py")` is true for a *directory* named `pkg.py` too. Combine
+with `IsFile()` when the type matters: `IsFile() & HasSuffix(".py")`.
+
+## 5. Constructor Guards
+No suffixes, a suffix without a leading dot (`"py"` would match any name
+ending in "py"), and a non-bool `ignore_case` are all `ParamError`s. The
+shape check is `is_valid_suffix`, shared with `change_suffix`.
+
+## 6. Description
+`suffix '.py'` / `suffix one of '.py', '.md'` — no `|` in the text, so the
+description cannot be misread inside `a | b`/`a & b` compositions.
+"""

simplibs/path/rules/lexical/IsAbsolutePath.py

@@ -0,0 +1,74 @@
+from pathlib import Path
+from typing import Any
+from simplibs.rules import Rule
+# Outers
+from .._helpers import build_path_rule_exception, check_path
+
+
+class IsAbsolutePath(Rule):
+    """Path must be absolute.
+
+    Rule:
+        Path(value).is_absolute()
+
+    Example:
+        validate(path, IsAbsolutePath())
+    """
+
+    __slots__ = ()
+
+    # ----------------------------------------------------------------------
+    # Rule definition
+    # ----------------------------------------------------------------------
+    def is_valid(self, value: Any) -> bool:
+
+        # 1. Pure path arithmetic — no disk access
+        return check_path(value, Path.is_absolute)
+
+    # ----------------------------------------------------------------------
+    # Description definition
+    # ----------------------------------------------------------------------
+    def describe(self) -> str:
+
+        # 1. Fixed noun phrase
+        return "absolute path"
+
+    # ----------------------------------------------------------------------
+    # 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_ABSOLUTE_PATH_ERROR",
+            expected="an absolute path",
+            value=value,
+            value_name=value_name,
+            context=context,
+            problem=f"Path {value!r} is not absolute.",
+            how_to_fix="Provide an absolute path, or make it absolute with normalize_path().",
+        )
+
+
+_DESIGN_NOTES = """
+# IsAbsolutePath — Anchored, Not Relative
+
+## Purpose
+A precondition for steps that must not depend on the working directory.
+
+## Platform Rule
+`Path.is_absolute()` follows the platform: `/etc` is absolute on POSIX, but on
+Windows it lacks a drive and is *not* (`C:\\\\etc` is). The rule reports what
+the platform means by "absolute".
+
+## `~` Is Expanded First
+`to_path` expands a leading `~`, so `~/work` is absolute (it is the home
+directory). A path that merely *starts with* a tilde character is otherwise
+indistinguishable from a home reference, and the rest of the library treats
+them identically.
+"""

simplibs/path/rules/lexical/IsHidden.py

@@ -0,0 +1,92 @@
+from typing import Any
+from simplibs.rules import Rule
+# Outers
+from ...logic.checks._helpers import to_path
+from ...logic.checks import is_hidden_path
+from .._helpers import build_path_rule_exception
+from .._validations import raise_rule_param_not_bool_error
+
+
+class IsHidden(Rule):
+    """Path must be hidden — its final name starts with a dot.
+
+    Rule:
+        is_hidden_path(value)
+
+    Example:
+        exclude_filter = IsHidden()
+        IsHidden(check_attributes=True)    # also the Windows "hidden" attribute
+    """
+
+    __slots__ = ("check_attributes",)
+
+    # ----------------------------------------------------------------------
+    # Constructor initialization
+    # ----------------------------------------------------------------------
+    def __init__(self, *, check_attributes: bool = False) -> None:
+
+        # 1. Parameter validation
+        if not isinstance(check_attributes, bool):
+            raise_rule_param_not_bool_error("IsHidden", "check_attributes", check_attributes)
+
+        # 2. Parameter assignment
+        self.check_attributes = check_attributes
+
+    # ----------------------------------------------------------------------
+    # 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_hidden_path(path, check_attributes=self.check_attributes, _validate_call=False)
+
+    # ----------------------------------------------------------------------
+    # Description definition
+    # ----------------------------------------------------------------------
+    def describe(self) -> str:
+
+        # 1. Fixed noun phrase
+        return "hidden path"
+
+    # ----------------------------------------------------------------------
+    # 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_HIDDEN_ERROR",
+            expected="a hidden path (its name starts with a dot)",
+            value=value,
+            value_name=value_name,
+            context=context,
+            problem=f"Path {value!r} is not hidden.",
+            how_to_fix="Provide a path whose final name starts with a dot, such as '.git'.",
+        )
+
+
+_DESIGN_NOTES = """
+# IsHidden — Hidden by Name, Optionally by Windows Attribute
+
+## Purpose
+Mostly used negated: `exclude_filter=IsHidden()` or `include_filter=~IsHidden()`.
+
+## Final Name Only
+`/home/me/.config/tool/a.json` is not hidden by this rule — its name is not.
+Skipping whole hidden *folders* is what a scanner's `ignore_names` does.
+
+## Keyword-Only Option
+`IsHidden(True)` would read as a mystery; `IsHidden(check_attributes=True)`
+says what it does. The option costs a `stat` call per path and exists only on
+Windows (a no-op elsewhere), so it is off by default.
+"""