simplibs-path 0.1.0__py3-none-any.whl

simplibs/path/logic/scanners/ignore_names/IGNORE_SYSTEM.py

@@ -0,0 +1,30 @@
+from typing import Final
+
+
+IGNORE_SYSTEM: Final[frozenset[str]] = frozenset({
+    "$RECYCLE.BIN",                 # Windows recycle bin
+    ".DS_Store",                    # macOS folder metadata
+    ".fseventsd",                   # macOS file system events log
+    ".Spotlight-V100",              # macOS Spotlight index
+    ".TemporaryItems",              # macOS temporary items
+    ".Trashes",                     # macOS trash directory
+    "System Volume Information",    # Windows volume metadata
+    "Thumbs.db",                    # Windows thumbnail cache
+    "desktop.ini",                  # Windows folder customization
+    "ehthumbs.db",                  # Windows Media Center thumbnails
+})
+"""Operating-system housekeeping files and folders (both files and directories)."""
+
+
+_DESIGN_NOTES = """
+# IGNORE_SYSTEM — OS Housekeeping
+
+## Purpose
+Entries the operating system creates on its own. Most are *files*
+(`.DS_Store`, `Thumbs.db`) — the reason the ignore mechanism now applies to
+files as well as directories; previously this whole group was dead.
+
+## Windows Coverage
+`$RECYCLE.BIN` and `System Volume Information` matter when scanning from the
+root of a drive; they are unreadable for normal users anyway.
+"""

simplibs/path/logic/scanners/ignore_names/IGNORE_VCS.py

@@ -0,0 +1,24 @@
+from typing import Final
+
+
+IGNORE_VCS: Final[frozenset[str]] = frozenset({
+    ".bzr",
+    ".git",
+    ".hg",
+    ".svn",
+})
+"""Metadata directories of version control systems."""
+
+
+_DESIGN_NOTES = """
+# IGNORE_VCS — Version Control Metadata
+
+## Purpose
+Names of the directories where Git, Mercurial, Subversion and Bazaar keep
+their internals. They hold no project content, often thousands of objects,
+and are never what a scan is looking for.
+
+## Unchanged
+Same content as the former `ignore_dirs/IGNORE_VCS`; only the package was
+renamed (`ignore_dirs` → `ignore_names`).
+"""

simplibs/path/logic/scanners/ignore_names/__init__.py

@@ -0,0 +1,30 @@
+from .DEFAULT_IGNORE_NAMES import DEFAULT_IGNORE_NAMES
+from .IGNORE_BUILD import IGNORE_BUILD
+from .IGNORE_ENV import IGNORE_ENV
+from .IGNORE_GENERIC import IGNORE_GENERIC
+from .IGNORE_IDE import IGNORE_IDE
+from .IGNORE_SYSTEM import IGNORE_SYSTEM
+from .IGNORE_VCS import IGNORE_VCS
+
+
+_DESIGN_NOTES = """
+# Scanner Ignore Names Sub-Package
+
+## Purpose
+Named sets of entry names (files and directories) that scanners skip. Names
+containing `*`, `?` or `[` are glob patterns; all others match exactly
+(case-insensitively on Windows). Renamed from `ignore_dirs`, because the
+sets contain files too.
+
+## Internal Components Registry
+
+| Component              | Type     | Description                                                       |
+| :--------------------- | :------- | :---------------------------------------------------------------- |
+| `DEFAULT_IGNORE_NAMES` | Constant | Union of VCS, ENV, BUILD, IDE and SYSTEM — the scanners' default. |
+| `IGNORE_BUILD`         | Constant | Caches, coverage data and tool output with unmistakable names.    |
+| `IGNORE_ENV`           | Constant | Virtual environments, installed dependencies, `.env`.             |
+| `IGNORE_GENERIC`       | Constant | Ambiguous output-folder names (`build`, `dist`, ...) — opt-in.    |
+| `IGNORE_IDE`           | Constant | Editor and IDE settings.                                          |
+| `IGNORE_SYSTEM`        | Constant | OS housekeeping (`.DS_Store`, `Thumbs.db`, ...).                  |
+| `IGNORE_VCS`           | Constant | Version control metadata (`.git`, `.svn`, ...).                   |
+"""

simplibs/path/logic/scanners/iter_paths.py

@@ -0,0 +1,91 @@
+from collections.abc import Collection, Iterator
+from pathlib import Path
+from simplibs.validate import validate_call
+# Outers
+from ...annotations import PathLike, PathPredicate, RecursionDepth
+# Inners
+from ._helpers import scan_paths
+from .ignore_names import DEFAULT_IGNORE_NAMES
+
+
+@validate_call
+def iter_paths(
+    root_dir: PathLike,
+    *,
+    recursive: RecursionDepth = True,
+    include_filter: PathPredicate | None = None,
+    exclude_filter: PathPredicate | None = None,
+    ignore_names: Collection[str] | None = DEFAULT_IGNORE_NAMES,
+    collect_files: bool = True,
+    collect_dirs: bool = False,
+) -> Iterator[Path]:
+    """Lazily yield the paths of a directory tree, one at a time.
+
+    The memory-friendly sibling of `collect_paths`: nothing is held back, so
+    a huge tree can be processed as it is discovered, and the walk can be
+    stopped early. The results are NOT sorted and come in no promised order.
+
+    Args:
+        root_dir: The root directory to scan.
+        recursive: `True` for unlimited depth, `False` for the root's own
+            entries only, or an `int` for a maximum depth (0 = root's own
+            entries, 1 = one level deeper, ...).
+        include_filter: A `Rule` or `(Path) -> bool` callable. A path must
+            satisfy it to be yielded.
+        exclude_filter: A `Rule` or `(Path) -> bool` callable. A path that
+            satisfies it is skipped (checked before `include_filter`).
+            Excluding a directory does not hide what is inside it.
+        ignore_names: Entry names (files and directories) or glob patterns
+            (`*.egg-info`) to skip entirely — an ignored directory is not
+            entered. Pass a collection, never a bare string; `None` ignores
+            nothing.
+        collect_files: Whether files are yielded.
+        collect_dirs: Whether directories are yielded.
+
+    Returns:
+        A lazy iterator of absolute `Path`s. The root and the options are
+        checked when `iter_paths` is called, not at the first `next()`.
+
+    Raises:
+        ParamError: If both collect flags are False, or `ignore_names` is a string.
+        NotFoundError: If `root_dir` does not exist.
+        StateError: If `root_dir` is not a directory.
+        AccessError: If `root_dir` cannot be listed.
+    """
+
+    # 1. Prepare everything now; only the walk itself is lazy
+    return scan_paths(
+        root_dir,
+        recursive=recursive,
+        include_filter=include_filter,
+        exclude_filter=exclude_filter,
+        ignore_names=ignore_names,
+        collect_files=collect_files,
+        collect_dirs=collect_dirs,
+    )
+
+
+_DESIGN_NOTES = """
+# iter_paths — the Lazy Scanner
+
+## Purpose
+`collect_paths` must finish the whole walk before returning anything.
+For a large tree, or a pipeline that only needs the first match, that is
+wasteful. `iter_paths` hands out paths as they are found.
+
+## No Action Counterpart
+An `Action` takes one value and returns one value; a generator is consumed
+once and cannot be safely logged, validated or re-run by the action
+machinery. Pipelines use `CollectPaths`/`CollectFiles`/`CollectDirs`, which
+return a list.
+
+## Eager Errors, Lazy Results
+`iter_paths` is an ordinary function that returns a generator, not a
+generator function itself. A generator function would run none of its body —
+including the root checks — until the first `next()`, so a typo in the path
+would surface in unrelated code, later.
+
+## Order
+Not sorted, not promised. Anything that needs a stable order uses
+`collect_paths`.
+"""

simplibs/path/logic/transformers/__init__.py

@@ -0,0 +1,27 @@
+from .change_suffix import change_suffix
+from .make_unique_path import make_unique_path
+from .normalize_entry_path import normalize_entry_path
+from .normalize_path import normalize_path
+from .rebase_path import rebase_path
+from .relativize_path import relativize_path
+
+
+_DESIGN_NOTES = """
+# Path Transformers Sub-Package
+
+## Purpose
+Functions that turn one path into another: normalize it, change its suffix,
+move it between two root directories, express it relative to a root, or find
+a free name for it. None of them changes the disk.
+
+## Internal Components Registry
+
+| Component               | Type     | Description                                                           |
+| :---------------------- | :------- | :-------------------------------------------------------------------- |
+| `change_suffix`         | Function | Replaces, adds or removes the last suffix of a path.                  |
+| `make_unique_path`      | Function | Returns a path, or a numbered variant of it, that does not exist yet. |
+| `normalize_entry_path`  | Function | Resolves the directory part while preserving the entry's final name.  |
+| `normalize_path`        | Function | Absolute, `~`-expanded, collapsed (and by default resolved) path.     |
+| `rebase_path`           | Function | Maps a path from a source root to a target root.                      |
+| `relativize_path`       | Function | Expresses a path relative to a root.                                  |
+"""

simplibs/path/logic/transformers/_helpers/__init__.py

@@ -0,0 +1,17 @@
+from .is_valid_suffix import is_valid_suffix
+from .split_name import split_name
+
+
+_DESIGN_NOTES = """
+# Path Transformers Internal Helpers Sub-Package
+
+## Purpose
+Small helpers private to `transformers/`.
+
+## Internal Components Registry
+
+| Component         | Type     | Description                                                                |
+| :---------------- | :------- | :------------------------------------------------------------------------- |
+| `is_valid_suffix` | Function | Whether a string has the shape of a file suffix (`""`, `.txt`, `.tar.gz`). |
+| `split_name`      | Function | Splits a final name into base name and suffix (`.tar.gz` aware).           |
+"""

simplibs/path/logic/transformers/_helpers/is_valid_suffix.py

@@ -0,0 +1,37 @@
+def is_valid_suffix(suffix: str) -> bool:
+    """Check whether a string has the shape of a file suffix.
+
+    Args:
+        suffix: The candidate suffix.
+
+    Returns:
+        True for an empty string (meaning "no suffix") or a string such as
+        `.txt` / `.tar.gz` — a dot followed by at least one character and no
+        path separator or null byte. False otherwise.
+    """
+
+    # 1. An empty suffix means "no suffix" — valid
+    if suffix == "":
+        return True
+
+    # 2. Otherwise: a dot plus at least one character, without separators or null bytes
+    return (
+        len(suffix) > 1
+        and suffix.startswith(".")
+        and not any(char in suffix for char in ("/", "\\", "\0"))
+    )
+
+
+_DESIGN_NOTES = """
+# is_valid_suffix — One Definition of "a Suffix"
+
+## Purpose
+`change_suffix` (a suffix to put on a path) and the `HasSuffix` rule (a
+suffix to look for) must agree on what a suffix is. The shape check used to
+live inline in `change_suffix`; it moved here so both share one definition
+and cannot drift apart.
+
+## Not an Extension Registry
+Any dot-prefixed text is accepted (`.tar.gz`, `.v2`). Whether it is a
+*real* extension is not this function's business.
+"""

simplibs/path/logic/transformers/_helpers/split_name.py

@@ -0,0 +1,46 @@
+from pathlib import Path
+
+
+def split_name(path: Path) -> tuple[str, str]:
+    """Split a path's final name into a base name and its (extension) suffix.
+
+    Args:
+        path: The path whose final name is split.
+
+    Returns:
+        `(stem, suffix)`. The suffix is the last extension (`".txt"`), except
+        for compound tar archives, where it is the whole `".tar.gz"`.
+        `("report", ".txt")`, `("archive", ".tar.gz")`, `(".bashrc", "")`.
+    """
+
+    # 1. Plain split — the last extension only
+    stem = path.stem
+    suffix = path.suffix
+
+    # 2. Compound tar archives keep ".tar" together with the compression suffix
+    if suffix and len(stem) > 4 and stem.lower().endswith(".tar"):
+        return stem[:-4], stem[-4:] + suffix
+
+    # 3. Everything else
+    return stem, suffix
+
+
+_DESIGN_NOTES = """
+# split_name — Name/Suffix Split for Numbered Variants
+
+## Purpose
+`make_unique_path` inserts " (1)" between the base name and the extension.
+With pathlib's plain `stem`/`suffix`, `archive.tar.gz` would become
+`archive.tar (1).gz` — a name whose "real" extension is lost. Treating
+`.tar.<compression>` as one suffix yields `archive (1).tar.gz`.
+
+## Why Only `.tar` Is Special
+Other multi-dot names (`report.v2.final.txt`) cannot be told apart from a
+base name that simply contains dots, so they keep the last extension only:
+`report.v2.final (1).txt`. The result is still correct and still opens with
+the right program — only `.tar.*` is common enough to deserve a rule.
+
+## Hidden Files
+`.bashrc` has no suffix in pathlib's view (its whole name is the stem), so
+the number goes at the end: `.bashrc (1)`.
+"""

simplibs/path/logic/transformers/_validations/__init__.py

@@ -0,0 +1,24 @@
+from .raise_invalid_suffix_error import raise_invalid_suffix_error
+from .raise_normalize_path_error import raise_normalize_path_error
+from .raise_path_has_no_name_error import raise_path_has_no_name_error
+from .raise_path_not_within_root_error import raise_path_not_within_root_error
+from .raise_unique_path_exhausted_error import raise_unique_path_exhausted_error
+
+
+_DESIGN_NOTES = """
+# Path Transformers Diagnostic Helpers Sub-Package
+
+## Purpose
+Internal diagnostic helpers raising structured exceptions for the functions
+in `transformers/`.
+
+## Internal Components Registry
+
+| Component                           | Type     | Description                                                              |
+| :---------------------------------- | :------- | :----------------------------------------------------------------------- |
+| `raise_invalid_suffix_error`        | Function | Raises `ParamError` for a malformed new suffix (`change_suffix`).        |
+| `raise_normalize_path_error`        | Function | Raises `AccessError` when a path cannot be resolved (`normalize_path`).  |
+| `raise_path_has_no_name_error`      | Function | Raises `ParamError` for a root, `.` or `..` (`change_suffix`, `make_unique_path`). |
+| `raise_path_not_within_root_error`  | Function | Raises `ParamError` when a path is outside its root (`rebase_path`, `relativize_path`). |
+| `raise_unique_path_exhausted_error` | Function | Raises `OperationError` when no free numbered name exists (`make_unique_path`). |
+"""

simplibs/path/logic/transformers/_validations/raise_invalid_suffix_error.py

@@ -0,0 +1,36 @@
+from typing import NoReturn
+from simplibs.exception import ParamError
+
+
+def raise_invalid_suffix_error(suffix: str) -> NoReturn:
+    """Raise ParamError when a new file suffix has an invalid shape."""
+
+    # 1. Raise structured ParamError wrapping a ValueError
+    raise ParamError(
+        error_name="INVALID_PATH_SUFFIX",
+        label="new_suffix",
+        value=suffix,
+        problem=(
+            f"Suffix {suffix!r} is not a valid file suffix.",
+            "A suffix must be empty, or start with a dot followed by at least one character, "
+            "without any path separator.",
+        ),
+        expected="An empty string (removes the suffix) or a string such as '.txt'.",
+        how_to_fix=(
+            "Start the suffix with a dot, e.g. '.txt' instead of 'txt'.",
+            "Remove path separators ('/' or '\\\\') from the suffix.",
+            "Use an empty string if the suffix should be removed.",
+        ),
+        exception=ValueError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_invalid_suffix_error — change_suffix Argument Diagnostic
+
+## Purpose
+`Path.with_suffix` has its own errors, but they are terse and differ between
+Python versions. Validating the suffix up front gives one consistent,
+actionable card — and prevents a suffix such as '/etc' from silently
+changing the directory part of the path.
+"""

simplibs/path/logic/transformers/_validations/raise_normalize_path_error.py

@@ -0,0 +1,44 @@
+from typing import Any, NoReturn
+from simplibs.exception import AccessError
+
+
+def raise_normalize_path_error(
+    path: Any,
+    caught_exc: Exception,
+) -> NoReturn:
+    """Raise AccessError when path normalization or resolution fails."""
+
+    # 1. Raise structured AccessError wrapping the caught resolution exception instance
+    raise AccessError(
+        error_name="PATH_NORMALIZATION_FAILED",
+        label=f"path '{path}'",
+        value=str(path),
+        problem=(
+            f"Could not resolve or normalize path '{path}'.",
+            # "The underlying operating system or resolver reported an error.",
+            f"OS reported: {caught_exc}",
+        ),
+        expected="A valid path string or Path instance that can be resolved on this system.",
+        how_to_fix=(
+            "Check for recursive or circular symlinks on the path.",
+            "Ensure the path contains no null bytes or characters invalid for the operating system.",
+            "Ensure the path format is valid for the operating system.",
+        ),
+        exception=caught_exc,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_normalize_path_error — normalize_path Failure Diagnostic
+
+## Purpose
+Single point of failure for "the path could not be resolved". Raised from
+`normalize_path` for OS-level errors, symlink loops (`RuntimeError` before
+Python 3.13, `OSError` after) and invalid path text such as an embedded null
+byte (`ValueError`).
+
+## Renamed From `raise_ensure_normalize_path_error`
+`normalize_path` ensures nothing — the old `ensure` prefix was a leftover of
+the former `validators/` folder. Only the name and one added how-to-fix
+line (null bytes) changed.
+"""

simplibs/path/logic/transformers/_validations/raise_path_has_no_name_error.py

@@ -0,0 +1,36 @@
+from pathlib import Path
+from typing import NoReturn
+from simplibs.exception import ParamError
+
+
+def raise_path_has_no_name_error(path: Path) -> NoReturn:
+    """Raise ParamError when a path has no final name component to work with."""
+
+    # 1. Raise structured ParamError wrapping a ValueError (what pathlib raises too)
+    raise ParamError(
+        error_name="PATH_HAS_NO_NAME",
+        label=f"path '{path}'",
+        value=str(path),
+        problem=(
+            f"Path '{path}' has no final name component.",
+            "It is empty, the current directory ('.'), '..', or a filesystem root.",
+        ),
+        expected="A path ending with a file or directory name, e.g. 'dir/report.txt'.",
+        how_to_fix=(
+            "Provide a path that ends with a file or directory name.",
+            "Normalize the path with `normalize_path` first if it is '.' or '..'.",
+        ),
+        exception=ValueError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_path_has_no_name_error — Nameless Path Diagnostic
+
+## Purpose
+`change_suffix` and `make_unique_path` both work on a path's final name. A
+filesystem root (`/`, `C:\\`), `.` and `..` have no usable name:
+`Path("/").with_suffix(".x")` raises a terse pathlib error, and
+`Path("..").with_suffix(".x")` does not raise at all but produces the
+nonsense name `...x`. One consistent card covers both cases.
+"""

simplibs/path/logic/transformers/_validations/raise_path_not_within_root_error.py

@@ -0,0 +1,43 @@
+from pathlib import Path
+from typing import NoReturn
+from simplibs.exception import ParamError
+
+
+def raise_path_not_within_root_error(
+    path: Path,
+    root: Path,
+) -> NoReturn:
+    """Raise ParamError when a path cannot be expressed relative to a root directory."""
+
+    # 1. Raise structured ParamError wrapping a ValueError (what Path.relative_to raises)
+    raise ParamError(
+        error_name="PATH_NOT_WITHIN_ROOT",
+        label=f"path '{path}'",
+        value=str(path),
+        problem=(
+            f"Path '{path}' is not located inside the root directory '{root}'.",
+            "The path cannot be expressed relative to this root.",
+        ),
+        expected=f"A path located inside '{root}'.",
+        how_to_fix=(
+            f"Provide a path that starts with '{root}'.",
+            "Check that both paths are absolute, or both are relative to the same base.",
+            "Normalize both paths with `normalize_path` before comparing them.",
+        ),
+        exception=ValueError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_path_not_within_root_error — Containment Failure Diagnostic
+
+## Purpose
+Shared by `rebase_path` (path vs. `source_root`) and `relativize_path`
+(path vs. `root`): both need "this path lives under that root" and fail the
+same way when it does not.
+
+## Why ParamError With a ValueError
+The caller supplied a combination of arguments that cannot work together —
+a parameter problem. `ValueError` is what `Path.relative_to` itself raises,
+so code that already catches it keeps working.
+"""

simplibs/path/logic/transformers/_validations/raise_unique_path_exhausted_error.py

@@ -0,0 +1,39 @@
+from pathlib import Path
+from typing import NoReturn
+from simplibs.exception import OperationError
+
+
+def raise_unique_path_exhausted_error(
+    path: Path,
+    attempts: int,
+) -> NoReturn:
+    """Raise OperationError when no free numbered variant of a path was found."""
+
+    # 1. Raise structured OperationError wrapping a FileExistsError
+    raise OperationError(
+        error_name="UNIQUE_PATH_EXHAUSTED",
+        label=f"path '{path}'",
+        value=str(path),
+        problem=(
+            f"Could not find a free name for '{path}' after {attempts} attempts.",
+            "Every numbered candidate already exists.",
+        ),
+        expected="A path with at least one free numbered variant within the attempt limit.",
+        how_to_fix=(
+            "Clean up the existing numbered variants of this path.",
+            "Use a different base name or target directory.",
+            "Raise `max_attempts` if that many variants are really needed.",
+        ),
+        exception=FileExistsError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_unique_path_exhausted_error — make_unique_path Diagnostic
+
+## Purpose
+`make_unique_path` tries "name (1).ext", "name (2).ext", ... up to
+`max_attempts`. A hard limit is a safety net against an endless loop on a
+pathological directory; reaching it is an operation failure, not a bad
+argument, hence OperationError.
+"""

simplibs/path/logic/transformers/change_suffix.py

@@ -0,0 +1,77 @@
+from pathlib import Path
+from simplibs.validate import validate_call
+# Outers
+from ...annotations import PathLike
+# Inners
+from ._helpers import is_valid_suffix
+
+from ._validations import raise_invalid_suffix_error, raise_path_has_no_name_error
+
+
+@validate_call
+def change_suffix(
+    path: PathLike,
+    new_suffix: str,
+) -> Path:
+    """Replace the last suffix of a path (or add / remove one).
+
+    Pure path arithmetic: nothing is read from or written to the disk and
+    `~` is not expanded — combine with `normalize_path` if you need that.
+
+    Args:
+        path: The path whose suffix changes.
+        new_suffix: The new suffix, including the dot (`".md"`), or an
+            empty string to remove the current suffix.
+
+    Returns:
+        A new `Path`; only the last suffix is replaced, so
+        `a.tar.gz` + `".zip"` becomes `a.tar.zip`.
+
+    Raises:
+        ParamError: If `new_suffix` is malformed, or `path` has no final
+            name (a root, `.` or `..`).
+    """
+
+    # 1. Validate the shape of the new suffix
+    if not is_valid_suffix(new_suffix):
+        raise_invalid_suffix_error(new_suffix)
+
+    # 2. The path needs a final name to carry a suffix
+    result = Path(path)
+    if result.name in ("", ".."):
+        raise_path_has_no_name_error(result)
+
+    # 3. Replace, add or remove the suffix
+    return result.with_suffix(new_suffix)
+
+
+_DESIGN_NOTES = """
+# change_suffix — Suffix Replacement With Up-Front Validation
+
+## Purpose
+A thin, safe wrapper over `Path.with_suffix`, existing as its own function
+(and `ChangeSuffix` action) so that "write the result next to the source,
+but as .md" is one named step in a pipeline.
+
+---
+
+## 1. Why Validate Before Calling `with_suffix`
+`with_suffix` has its own checks, but they are terse, differ slightly
+between Python versions, and let `..` through (producing `...md`). Validating
+first gives one consistent card and rules out a suffix such as `"/etc"`,
+which could otherwise reach the directory part of a path.
+
+## 2. The Shape Check Is Shared
+`is_valid_suffix` (package `_helpers/`) defines what a suffix looks like;
+the `HasSuffix` rule uses the very same function.
+
+## 3. Backslash Is Rejected on Every Platform
+It is a legal filename character on POSIX, but a path separator on Windows;
+a suffix containing it cannot be portable, and portability is the point of
+this library's filename handling.
+
+## 4. Lexical on Purpose
+No `expanduser`, no `resolve`, no disk access: a transformer that only
+changes a name has no business touching the filesystem. In a pipeline,
+`NormalizePath() >> ChangeSuffix(new_suffix=".md")` does both explicitly.
+"""