simplibs-path 0.1.0__py3-none-any.whl

simplibs/path/logic/transformers/make_unique_path.py

@@ -0,0 +1,88 @@
+import os
+from pathlib import Path
+from simplibs.types import int_positive
+from simplibs.validate import validate_call
+# Outers
+from ...annotations import PathLike
+# Inners
+from ._helpers import split_name
+from ._validations import raise_unique_path_exhausted_error
+from .normalize_entry_path import normalize_entry_path
+
+
+@validate_call
+def make_unique_path(
+    path: PathLike,
+    *,
+    max_attempts: int_positive = 1000,
+) -> Path:
+    """Return `path` itself if it is free, otherwise a numbered variant that is.
+
+    `report.txt` becomes `report (1).txt`, `report (2).txt`, ... — the first
+    name that does not exist yet. Nothing is created.
+
+    Args:
+        path: The wanted path.
+        max_attempts: How many numbered variants to try before giving up.
+
+    Returns:
+        An absolute `Path` that did not exist at the moment of the call. Its
+        directory is resolved (symlinks followed); the final name is kept as
+        written, so a symlink there is never followed.
+
+    Raises:
+        ParamError: If `path` has no final name (a filesystem root).
+        OperationError: If every variant up to `max_attempts` is taken.
+        AccessError: If the path cannot be normalized.
+    """
+
+    # 1. Normalize the wanted path as an entry (directory resolved, name kept)
+    normalized = normalize_entry_path(path)
+
+    # 2. The wanted path is free — keep it as it is
+    if not os.path.lexists(normalized):
+        return normalized
+
+    # 3. Try "name (1).ext", "name (2).ext", ... until one is free
+    stem, suffix = split_name(normalized)
+    for number in range(1, max_attempts + 1):
+        candidate = normalized.with_name(f"{stem} ({number}){suffix}")
+        if not os.path.lexists(candidate):
+            return candidate
+
+    # 4. Every candidate within the limit is taken
+    raise_unique_path_exhausted_error(normalized, max_attempts)
+
+
+_DESIGN_NOTES = """
+# make_unique_path — Collision-Free Output Names
+
+## Purpose
+Lets a pipeline write a result next to others without overwriting them,
+choosing the name the way file managers do ("report (1).txt").
+
+---
+
+## 1. `os.path.lexists`, Not `Path.exists`
+`exists()` follows symlinks, so a *broken* symlink reports "does not
+exist" — and writing to that name would write through the link to its
+missing target. `lexists` treats the link itself as occupying the name.
+
+## 2. Only the Directory Is Resolved
+Delegated to `normalize_entry_path`: the final name is judged as written, so a
+dangling link `out.txt -> nowhere` occupies the name `out.txt`.
+
+## 3. Not Atomic — By Nature
+The name is free at the moment of the call, not reserved. To claim a name for
+certain, open the returned path with mode `"x"`; this function only chooses a
+good candidate.
+
+## 4. A Hard Attempt Limit
+`max_attempts` stops the search on a directory where thousands of variants
+exist. Reaching it is an operation failure (`OperationError`), not silent
+success with a wrong name.
+
+## 5. Compound Suffixes
+`split_name` keeps `.tar.gz` together, so `archive.tar.gz` becomes
+`archive (1).tar.gz` instead of `archive.tar (1).gz`.
+"""

simplibs/path/logic/transformers/normalize_entry_path.py

@@ -0,0 +1,67 @@
+from pathlib import Path
+from simplibs.validate import validate_call
+# Outers
+from ...annotations import PathLike
+# Inners
+from .normalize_path import normalize_path
+from ._validations import raise_path_has_no_name_error
+
+
+@validate_call
+def normalize_entry_path(
+    path: PathLike,
+) -> Path:
+    """Normalize the path of a directory ENTRY — resolve its folder, keep its own name as written.
+
+    `normalize_path` follows symlinks all the way, which is right when you mean
+    "the content behind this path". This function is for operations on the
+    *entry itself* — deleting, renaming, moving, checking whether a name is
+    taken — where a symlink in the final position must stay a symlink:
+    `delete_file("link")` must remove the link, not the file it points to.
+
+    Args:
+        path: The path of the entry.
+
+    Returns:
+        An absolute `Path`: `~` expanded, relative parts collapsed, symlinks
+        in the *directory part* resolved, the final name untouched. The entry
+        does not have to exist.
+
+    Raises:
+        ParamError: If `path` has no final name (a filesystem root).
+        AccessError: If the directory part cannot be resolved.
+    """
+
+    # 1. Make the path absolute without following a symlink in its final name
+    lexical = normalize_path(path, resolve_symlinks=False)
+
+    # 2. A nameless path (a root) is not an entry that can be addressed by name
+    if not lexical.name:
+        raise_path_has_no_name_error(lexical)
+
+    # 3. Resolve only the directory part — the final name stays as written
+    return normalize_path(lexical.parent) / lexical.name
+
+
+_DESIGN_NOTES = """
+# normalize_entry_path — Normalizing a Name, Not Its Target
+
+## Purpose
+Two different questions hide behind "normalize this path":
+* *Where is the content?* — `normalize_path` (symlinks resolved all the way).
+* *Which directory entry is this?* — this function (the folder resolved, the
+  final name kept).
+
+Operations on entries (`delete_file`, `move_file`, `make_unique_path`) need the
+second one; reading and writing content needs the first.
+
+## Extracted From `make_unique_path`
+`make_unique_path` already contained exactly this logic inline (a dangling link
+`out.txt -> nowhere` must be judged as the name `out.txt`, not as `.../nowhere`).
+It now calls this function, and `simplibs-file` shares it.
+
+## Why Not `normalize_path(resolve_symlinks=False)`
+That is purely lexical: a symlinked *directory* above the entry stays
+unresolved, so two spellings of the same folder compare as different. Resolving
+the directory part (and only that) gives one canonical address per entry.
+"""

simplibs/path/logic/transformers/normalize_path.py

@@ -0,0 +1,85 @@
+import os
+from pathlib import Path
+from simplibs.validate import validate_call
+# Outers
+from ...annotations import PathLike
+# Inners
+from ._validations import raise_normalize_path_error
+
+
+@validate_call
+def normalize_path(
+    path: PathLike,
+    *,
+    resolve_symlinks: bool = True,
+) -> Path:
+    """Normalize a path into an absolute, user-expanded `Path`.
+
+    Args:
+        path: The path to normalize.
+        resolve_symlinks: If True (default), symlinks are followed and the
+            real location is returned. If False, the result is only made
+            absolute and `..`/`.` are collapsed lexically — symlinks stay
+            as they are.
+
+    Returns:
+        An absolute `Path` — `~` expanded, relative components collapsed
+        and (by default) symlinks resolved. The path does not have to exist.
+
+    Raises:
+        AccessError: If the path cannot be resolved (an OS-level error, a
+            symlink loop, or invalid text such as an embedded null byte).
+    """
+
+    # 1. A null byte is invalid in every path — report it the same way in both modes
+    if "\0" in str(path):
+        raise_normalize_path_error(path, ValueError("embedded null byte"))
+
+    # 2. Expand user (~) and make the path absolute
+    try:
+        expanded = Path(path).expanduser()
+
+        # 2.1 Follow symlinks and collapse ".." through the real filesystem
+        if resolve_symlinks:
+            return expanded.resolve()
+
+        # 2.2 Purely lexical — absolute and collapsed, symlinks untouched
+        return Path(os.path.abspath(expanded))
+
+    # 3. Catch OS-level failures, symlink loops and invalid path text
+    except (OSError, RuntimeError, ValueError) as caught_exc:
+        raise_normalize_path_error(path, caught_exc)
+
+
+_DESIGN_NOTES = """
+# normalize_path — the Library's Single Path Normalizer
+
+## Purpose
+Every function that touches the disk starts here, so all of them agree on
+what "the same path" means. It does not require the path to exist.
+
+---
+
+## 1. Moved From `validators/`, Gained `resolve_symlinks`
+The function itself is unchanged. The new keyword `resolve_symlinks=False`
+covers the case where a symlinked location must be kept as written
+(`data -> /mnt/storage` stays `data`, not `/mnt/storage`). The default keeps
+the old behavior, which the scanners rely on: `collect_paths` resolves its
+root, so entries and any root passed to `rebase_path`/`relativize_path`
+agree only if both are resolved the same way.
+
+## 2. Why the Null Byte Is Checked Explicitly
+`Path.resolve()` raises `ValueError` for it, but `os.path.abspath` (the
+non-resolving branch) does not. Checking first makes both modes fail
+identically, with the same card.
+
+## 3. Why `RuntimeError` Is Caught
+Before Python 3.13 a symlink loop surfaces from `resolve()` as
+`RuntimeError`, afterwards as `OSError`; an unknown `~user` is also a
+`RuntimeError`. Catching all three keeps the card stable across versions.
+
+## 4. Errors Are `AccessError`, Not `ValidationError`
+A bad *type* or a blank string never gets here — the `PathLike` annotation
+rejects it with a `ValidationError` before the body runs. What remains is
+the environment refusing to resolve a well-formed path.
+"""

simplibs/path/logic/transformers/rebase_path.py

@@ -0,0 +1,78 @@
+from pathlib import Path
+from simplibs.validate import validate_call
+# Outers
+from ...annotations import PathLike
+# Inners
+from .change_suffix import change_suffix
+from .normalize_path import normalize_path
+from ._validations import raise_path_not_within_root_error
+
+
+@validate_call
+def rebase_path(
+    path: PathLike,
+    *,
+    source_root: PathLike,
+    target_root: PathLike,
+    new_suffix: str | None = None,
+) -> Path:
+    """Map a path inside one root directory to the same place inside another.
+
+    `src/pkg/a.py` with `source_root="src"`, `target_root="out"` becomes
+    `out/pkg/a.py` — the "where does the output of this input go" step of
+    an extraction pipeline. Nothing is created on the disk.
+
+    Args:
+        path: The path inside `source_root`.
+        source_root: The directory `path` currently lives in.
+        target_root: The directory the result should live in.
+        new_suffix: If given, the suffix of the result is replaced (see
+            `change_suffix`); `None` keeps the original name.
+
+    Returns:
+        The rebased, normalized `Path`.
+
+    Raises:
+        ParamError: If `path` is not located inside `source_root`, or
+            `new_suffix` is malformed.
+        AccessError: If any of the paths cannot be normalized.
+    """
+
+    # 1. Normalize all three paths the same way, so they are comparable
+    normalized_path = normalize_path(path)
+    normalized_source = normalize_path(source_root)
+    normalized_target = normalize_path(target_root)
+
+    # 2. Express the path relative to the source root
+    try:
+        relative = normalized_path.relative_to(normalized_source)
+    except ValueError:
+        raise_path_not_within_root_error(normalized_path, normalized_source)
+
+    # 3. Re-attach the relative part to the target root
+    rebased = normalized_target / relative
+
+    # 4. Optionally replace the suffix
+    if new_suffix is not None:
+        return change_suffix(rebased, new_suffix)
+    return rebased
+
+
+_DESIGN_NOTES = """
+# rebase_path — Source Tree to Target Tree
+
+## Purpose
+The path arithmetic behind "mirror this tree somewhere else": each
+collected input path is mapped to its output path, keeping the structure
+below the root and optionally swapping the extension (`.py` → `.md`).
+
+## Pure Path Arithmetic
+No directory is created and nothing is checked for existence. Creating the
+parent directory is a separate, explicit step (`ensure_parent_dir`), so a
+pipeline can compute all targets first, check them, and only then write.
+
+## `new_suffix=None` vs `""`
+`None` means "keep the name as is"; an empty string means "remove the
+suffix" — two different, both meaningful requests, which is why the
+default is not an empty string.
+"""

simplibs/path/logic/transformers/relativize_path.py

@@ -0,0 +1,56 @@
+from pathlib import Path
+from simplibs.validate import validate_call
+# Outers
+from ...annotations import PathLike
+# Inners
+from .normalize_path import normalize_path
+from ._validations import raise_path_not_within_root_error
+
+
+@validate_call
+def relativize_path(
+    path: PathLike,
+    *,
+    root: PathLike,
+) -> Path:
+    """Express a path relative to a root directory.
+
+    Args:
+        path: The path to relativize.
+        root: The directory the result is relative to.
+
+    Returns:
+        The path relative to `root` (`Path(".")` when both are the same).
+
+    Raises:
+        ParamError: If `path` is not located inside `root`.
+        AccessError: If either path cannot be normalized.
+    """
+
+    # 1. Normalize both paths the same way, so they are comparable
+    normalized_path = normalize_path(path)
+    normalized_root = normalize_path(root)
+
+    # 2. Express the path relative to the root
+    try:
+        return normalized_path.relative_to(normalized_root)
+
+    # 3. Not inside the root — report it instead of a bare pathlib error
+    except ValueError:
+        raise_path_not_within_root_error(normalized_path, normalized_root)
+
+
+_DESIGN_NOTES = """
+# relativize_path — Path Relative to a Root
+
+## Purpose
+Shows a collected path as it appears inside the scanned tree
+(`src/a/b.py`, not `/home/me/project/src/a/b.py`) — for reports, logs and
+as the first half of `rebase_path`.
+
+## Why Both Sides Are Normalized
+`Path.relative_to` compares path parts textually. `./src` vs `/abs/src`, or
+a symlinked vs. a resolved root, would wrongly fail. Normalizing both with
+the same function removes that class of surprise (and makes Windows'
+case-insensitive comparison apply to real, absolute parts).
+"""

simplibs/path/rules/__init__.py

@@ -0,0 +1,66 @@
+from .filesystem import (
+    IsDir,
+    IsEmptyDir,
+    IsEmptyFile,
+    IsFile,
+    IsPathReadable,
+    IsPathWritable,
+    IsSymlink,
+    PathExists,
+)
+from .lexical import (
+    HasSuffix,
+    IsAbsolutePath,
+    IsHidden,
+    IsRelativePath,
+    IsValidFilename,
+    IsWithin,
+    NameIs,
+    ParentNameIs,
+    StemIs,
+)
+
+__all__ = [
+    # lexical — judge a path by its text
+    "HasSuffix",
+    "IsAbsolutePath",
+    "IsHidden",
+    "IsRelativePath",
+    "IsValidFilename",
+    "IsWithin",
+    "NameIs",
+    "ParentNameIs",
+    "StemIs",
+    # filesystem — ask the disk
+    "IsDir",
+    "IsEmptyDir",
+    "IsEmptyFile",
+    "IsFile",
+    "IsPathReadable",
+    "IsPathWritable",
+    "IsSymlink",
+    "PathExists",
+]
+
+
+_DESIGN_NOTES = """
+# Path Rules Sub-Package
+
+## Purpose
+`Rule` classes for paths: filters for scanners (`include_filter`,
+`exclude_filter`, `filter_paths`), annotations for `@validate_call`
+(`validated_type(Path, IsDir())`) and pipeline gates (`IsDir() >> CollectFiles()`).
+Each is a thin wrapper over a function in `checks/` or a pathlib call.
+
+## Two Groups
+* `lexical/` — judge the path's *text*. Cheap; safe to run per entry.
+* `filesystem/` — ask the disk. One or two syscalls per call.
+
+## Composition
+Combine them with the usual operators: `IsFile() & HasSuffix(".py") & ~IsHidden()`.
+The description of that rule reads `existing file & suffix '.py' & not hidden path`.
+
+## Domain Folder: `__all__`
+As the other domain folders, this package defines `__all__` (the public
+rules); the sub-packages and helpers are importable but not part of it.
+"""

simplibs/path/rules/_helpers/PathPartIs.py

@@ -0,0 +1,152 @@
+from pathlib import Path
+from typing import Any, Callable
+from simplibs.exception import ValidationError
+from simplibs.rules import AllOf, AnyOf, Compose, Rule, UserRule
+# Outers
+from ...logic.checks._helpers import to_path
+from .._validations import raise_rule_param_not_callable_error
+# Inners
+from .build_not_a_path_exception import build_not_a_path_exception
+
+
+class PathPartIs(Rule):
+    """Base of the rules that check one text part of a path with another rule.
+
+    A subclass names the part (`_part_name`) and extracts it (`_get_part`);
+    everything else — validation, evaluation, description, failure card —
+    is shared. Not meant to be used directly.
+    """
+
+    __slots__ = ("rule",)
+
+    _part_name: str = "part"
+
+    # ----------------------------------------------------------------------
+    # Part extraction (the one thing a subclass defines)
+    # ----------------------------------------------------------------------
+    @staticmethod
+    def _get_part(path: Path) -> str:
+        raise NotImplementedError
+
+    # ----------------------------------------------------------------------
+    # Constructor initialization
+    # ----------------------------------------------------------------------
+    def __init__(self, rule: Rule | Callable[[Any], bool]) -> None:
+
+        # 1. Parameter validation
+        if not callable(rule):
+            raise_rule_param_not_callable_error(type(self).__name__, "rule", rule)
+
+        # 2. A plain callable gets the missing Rule contract (describe, build_exception)
+        self.rule = rule if isinstance(rule, Rule) else UserRule(rule)
+
+    # ----------------------------------------------------------------------
+    # 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. Let the wrapped rule judge the extracted text
+        return bool(self.rule.is_valid(self._get_part(path)))
+
+    # ----------------------------------------------------------------------
+    # Description definition
+    # ----------------------------------------------------------------------
+    def describe(self) -> str:
+
+        # 1. The wrapped rule describes itself — a faulty describe() must never break this one
+        # noinspection PyBroadException
+        try:
+            text = self.rule.describe()
+        except Exception:
+            text = None
+        if not isinstance(text, str) or not text:
+            text = type(self.rule).__name__
+
+        # 2. A compound operand needs parentheses so the prefix reads as covering all of it
+        if isinstance(self.rule, (AllOf, AnyOf, Compose)):
+            text = f"({text})"
+
+        # 3. "name: <rule>"
+        return f"{self._part_name}: {text}"
+
+    # ----------------------------------------------------------------------
+    # Exception definition
+    # ----------------------------------------------------------------------
+    def build_exception(
+        self,
+        value: Any,
+        value_name: str | None = None,
+        context: str | None = None,
+    ) -> Exception:
+
+        # 1. Prepare data
+        prefix = f"{self._part_name.upper().replace(' ', '_')}_IS"
+
+        # 2. Not a usable path at all
+        path = to_path(value)
+        if path is None:
+            return build_not_a_path_exception(
+                error_name=f"{prefix}_ERROR",
+                expected=f"a path whose {self.describe()}",
+                value=value,
+                value_name=value_name,
+                context=context,
+            )
+
+        # 3. The part fails the wrapped rule — vend the wrapped rule's own card
+        part = self._get_part(path)
+        if not self.rule.is_valid(part):
+            label = f"{value_name}.{self._part_name}" if value_name else self._part_name
+            return self.rule.build_exception(part, value_name=label, context=context)
+
+        # 4. Fallback (build exception if the part unexpectedly passed)
+        return ValidationError(
+            error_name=f"{prefix}_UNREACHABLE_ERROR",
+            label=value_name,
+            expected=f"a path whose {self.describe()}",
+            value=value,
+            problem="The path part unexpectedly passed during error construction.",
+            context=context,
+            how_to_fix=("Check validation logic state.",),
+            exception=RuntimeError,
+        )
+
+
+_DESIGN_NOTES = """
+# PathPartIs — a Lens From a Path to One of Its Text Parts
+
+## Purpose
+Matching file names ("starts with `test_`", "matches this regex") needs no
+new string logic: `StartsWith`, `Regex`, `Contains` and every other string
+rule already exists. `NameIs(StartsWith("test_"))` simply points them at the
+right piece of the path. The three lenses (`NameIs`, `StemIs`,
+`ParentNameIs`) differ only in which piece; this base holds the rest.
+
+---
+
+## 1. Plain Callables Are Wrapped in `UserRule`
+Same reasoning as `validate_call`'s `overrides`: a bare function has no
+`describe()` and no `build_exception()`, so a failure could not be
+explained. `UserRule` supplies both.
+
+## 2. The Failure Card Is the Wrapped Rule's Own
+`NameIs(StartsWith("test_"))` on `src/a.py` reports *that `a.py` does not
+start with `test_`*, labelled `source.name` — the same "delegate to
+whoever actually failed" principle `AllOf` and `ForEach` use. Consequently
+`exc.value` is the part, not the whole path (contract tests run with
+`check_value=False`).
+
+## 3. Description
+`name: string starting with 'test_'`. A compound operand is wrapped in
+parentheses (`name: (a | b)`), exactly as `ForEach` does for `each (a | b)`.
+
+## 4. Why a Base Class and Not Three Copies
+The three rules are 90% identical; a bug fixed in one (say, how the label
+is built) must be fixed in all. `__slots__` is declared on the base and
+as `()` on each subclass, so no instance carries a `__dict__`.
+"""

simplibs/path/rules/_helpers/__init__.py

@@ -0,0 +1,21 @@
+from .PathPartIs import PathPartIs
+from .build_not_a_path_exception import build_not_a_path_exception
+from .build_path_rule_exception import build_path_rule_exception
+from .check_path import check_path
+
+
+_DESIGN_NOTES = """
+# Path Rules Internal Helpers Sub-Package
+
+## Purpose
+Building blocks shared by the rules in `lexical/` and `filesystem/`.
+
+## Internal Components Registry
+
+| Component                    | Type  | Description                                                              |
+| :--------------------------- | :---- | :----------------------------------------------------------------------- |
+| `PathPartIs`                 | Class | Base of the lens rules (`NameIs`, `StemIs`, `ParentNameIs`).             |
+| `build_not_a_path_exception` | Function | Failure card for a value that is not a usable path.                   |
+| `build_path_rule_exception`  | Function | A path rule's whole `build_exception`, from its three sentences.      |
+| `check_path`                 | Function | Runs a filesystem check and answers `False` instead of raising.       |
+"""

simplibs/path/rules/_helpers/build_not_a_path_exception.py

@@ -0,0 +1,66 @@
+from pathlib import Path
+from typing import Any
+from simplibs.exception import ValidationError
+
+
+def build_not_a_path_exception(
+    *,
+    error_name: str,
+    expected: str,
+    value: Any,
+    value_name: str | None,
+    context: str | None,
+) -> Exception:
+    """Build the failure card for a value that cannot even be treated as a path.
+
+    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`.
+
+    Returns:
+        A `ValidationError` — wrapping `TypeError` for a non-string, non-Path
+        value, and `ValueError` for a blank string or one with a null byte.
+    """
+
+    # 1. A str/Path that is still unusable — blank or containing a null byte
+    if isinstance(value, (str, Path)):
+        problem = f"Value {value!r} cannot be used as a path (it is blank or contains a null byte)."
+        how_to_fix = "Provide a non-blank path without null bytes."
+        exception_type = ValueError
+
+    # 2. Not a string or Path at all
+    else:
+        problem = f"Value {value!r} of type '{type(value).__name__}' is not a string or Path."
+        how_to_fix = "Provide a path as a str or a Path object."
+        exception_type = TypeError
+
+    # 3. Build the exception
+    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_type,
+    )
+
+
+_DESIGN_NOTES = """
+# build_not_a_path_exception — Wrong Kind of Value, Said Once
+
+## Purpose
+Every path rule has the same first failure branch: the value is not a path
+at all. This builds that card for all of them, mirroring the `if not
+isinstance(value, str)` branch of `Contains`/`IsString` — with the one extra
+distinction a path needs: a *blank* string is a `str` and still not a path.
+
+## Same `error_name` in Both Branches
+A rule's card keeps one `error_name` whatever went wrong (as `Contains` uses
+`CONTAINS_ERROR` for both its type and its value failure); only the
+wrapped `exception` type (`TypeError` / `ValueError`) differs.
+"""