simplibs-path 0.1.0__py3-none-any.whl

simplibs/path/__init__.py

@@ -0,0 +1,118 @@
+from .logic.checks import (
+    is_empty_dir,
+    is_hidden_path,
+    is_path_readable,
+    is_path_writable,
+    is_valid_filename,
+    is_within,
+)
+from .logic.ensure import (
+    ensure_dir,
+    ensure_file,
+    ensure_parent_dir,
+)
+from .logic.scanners import (
+    DEFAULT_IGNORE_NAMES,
+    IGNORE_BUILD,
+    IGNORE_ENV,
+    IGNORE_GENERIC,
+    IGNORE_IDE,
+    IGNORE_SYSTEM,
+    IGNORE_VCS,
+    collect_dirs,
+    collect_files,
+    collect_paths,
+    filter_paths,
+    iter_paths,
+)
+from .logic.transformers import (
+    change_suffix,
+    make_unique_path,
+    normalize_path,
+    normalize_entry_path,
+    rebase_path,
+    relativize_path,
+)
+from .annotations import (
+    PathLike,
+    PathPredicate,
+    RecursionDepth,
+)
+
+__all__ = [
+    # transformers — path in, path out
+    "normalize_entry_path",
+    "normalize_path",
+    "rebase_path",
+    "relativize_path",
+    "change_suffix",
+    "make_unique_path",
+    # checks — a bool, never an exception for disk problems
+    "is_empty_dir",
+    "is_hidden_path",
+    "is_path_readable",
+    "is_path_writable",
+    "is_valid_filename",
+    "is_within",
+    # ensure — make a filesystem state true
+    "ensure_dir",
+    "ensure_file",
+    "ensure_parent_dir",
+    # scanners — look at a directory tree
+    "collect_paths",
+    "collect_files",
+    "collect_dirs",
+    "iter_paths",
+    "filter_paths",
+    "DEFAULT_IGNORE_NAMES",
+    "IGNORE_BUILD",
+    "IGNORE_ENV",
+    "IGNORE_GENERIC",
+    "IGNORE_IDE",
+    "IGNORE_SYSTEM",
+    "IGNORE_VCS",
+    # annotations — types for your own signatures
+    "PathLike",
+    "PathPredicate",
+    "RecursionDepth",
+]
+
+
+_DESIGN_NOTES = """
+# simplibs-path — Package Root
+
+## Purpose
+Safe, composable work with paths and directory trees: normalize, check,
+ensure and scan — as plain functions, as `Rule`s, and as pipeline `Action`s.
+
+## What the Root Exports
+Everything from the four logic sub-packages of `logic/`
+(`transformers`, `checks`, `ensure`, `scanners`) and the three public
+types of `annotations/`:
+
+    from simplibs.path import collect_files, normalize_path, PathLike
+
+## What the Root Deliberately Does NOT Export
+* **`rules/` and `actions/`** — domain folders with their own `__all__`,
+  imported through their domain:
+
+      from simplibs.path.rules import HasSuffix, IsFile
+      from simplibs.path.actions import CollectFiles
+
+  Twenty-nine class names would drown the thirty-odd functions, and a
+  `Rule` and an `Action` are different kinds of thing that should stay
+  visibly different at the import line.
+* **`ScanEntry`** — the walker's internal result type; it never appears in
+  a public signature.
+
+## Why the Three Types ARE Exported
+`PathLike`, `PathPredicate` and `RecursionDepth` are annotations meant for
+the caller's own signatures (`def load(path: PathLike) -> ...`), always used
+together with the functions. They are few, tiny and unambiguous — unlike
+the rules and actions — so the root is the natural place for them. They stay
+importable from `simplibs.path.types` as well.
+
+## `__all__`
+Defined here and in the domain folders (`rules`, `actions`) only; the
+sub-packages below export by plain imports.
+"""

simplibs/path/actions/ChangeSuffix.py

@@ -0,0 +1,23 @@
+from simplibs.actions import create_action
+# Outers
+from ..logic.transformers import change_suffix
+
+
+ChangeSuffix = create_action(
+    change_suffix,
+    main_param="path",
+    class_name="ChangeSuffix",
+)
+"""Action wrapping `change_suffix` — replaces, adds or removes the last suffix of a path."""
+
+
+_DESIGN_NOTES = """
+# ChangeSuffix — Action Over `change_suffix`
+
+## Purpose
+`ChangeSuffix(new_suffix=".md")` as one named step of a pipeline.
+
+## Call-Time Shape Check
+`new_suffix` is a plain `str` at construction; its shape (leading dot, no separators) is checked by the
+function when the action runs.
+"""

simplibs/path/actions/CollectDirs.py

@@ -0,0 +1,24 @@
+from simplibs.actions import create_action
+# Outers
+from ..logic.scanners import collect_dirs
+
+
+CollectDirs = create_action(
+    collect_dirs,
+    main_param="root_dir",
+    class_name="CollectDirs",
+    use_logging=False,
+)
+"""Action wrapping `collect_dirs` — collects only the directories of a tree into a sorted list."""
+
+
+_DESIGN_NOTES = """
+# CollectDirs — Action Over `collect_dirs`
+
+## Purpose
+"Which folders exist under here" as a pipeline step. The root itself is not included.
+
+## Logging Is Off
+The result is a list that can hold tens of thousands of paths, and the `log_this` layer would record all of it.
+Remove `use_logging=False` once `log_this` is known to truncate large results.
+"""

simplibs/path/actions/CollectFiles.py

@@ -0,0 +1,25 @@
+from simplibs.actions import create_action
+# Outers
+from ..logic.scanners import collect_files
+
+
+CollectFiles = create_action(
+    collect_files,
+    main_param="root_dir",
+    class_name="CollectFiles",
+    use_logging=False,
+)
+"""Action wrapping `collect_files` — collects only the files of a tree into a sorted list."""
+
+
+_DESIGN_NOTES = """
+# CollectFiles — Action Over `collect_files`
+
+## Purpose
+Real locking: the type flags are not part of `collect_files`' signature, so `CollectFiles` cannot be made to
+collect directories. (The former `functools.partial` preset only changed defaults.)
+
+## Logging Is Off
+The result is a list that can hold tens of thousands of paths, and the `log_this` layer would record all of it.
+Remove `use_logging=False` once `log_this` is known to truncate large results.
+"""

simplibs/path/actions/CollectPaths.py

@@ -0,0 +1,24 @@
+from simplibs.actions import create_action
+# Outers
+from ..logic.scanners import collect_paths
+
+
+CollectPaths = create_action(
+    collect_paths,
+    main_param="root_dir",
+    class_name="CollectPaths",
+    use_logging=False,
+)
+"""Action wrapping `collect_paths` — collects files and/or directories of a tree into a sorted list."""
+
+
+_DESIGN_NOTES = """
+# CollectPaths — Action Over `collect_paths`
+
+## Purpose
+The head of an extraction pipeline: the root goes in, a sorted list of paths comes out.
+
+## Logging Is Off
+The result is a list that can hold tens of thousands of paths, and the `log_this` layer would record all of it.
+Remove `use_logging=False` once `log_this` is known to truncate large results.
+"""

simplibs/path/actions/EnsureDir.py

@@ -0,0 +1,22 @@
+from simplibs.actions import create_action
+# Outers
+from ..logic.ensure import ensure_dir
+
+
+EnsureDir = create_action(
+    ensure_dir,
+    main_param="path",
+    class_name="EnsureDir",
+)
+"""Action wrapping `ensure_dir` — guarantees a directory (and its parents) exists."""
+
+
+_DESIGN_NOTES = """
+# EnsureDir — Action Over `ensure_dir`
+
+## Purpose
+Turns "I need this folder" into a pipeline step that passes the normalized directory on.
+
+## Changes the Disk
+Together with `EnsureFile` and `EnsureParentDir`, the only actions that do.
+"""

simplibs/path/actions/EnsureFile.py

@@ -0,0 +1,19 @@
+from simplibs.actions import create_action
+# Outers
+from ..logic.ensure import ensure_file
+
+
+EnsureFile = create_action(
+    ensure_file,
+    main_param="path",
+    class_name="EnsureFile",
+)
+"""Action wrapping `ensure_file` — guarantees a file (and its parent directory) exists."""
+
+
+_DESIGN_NOTES = """
+# EnsureFile — Action Over `ensure_file`
+
+## Purpose
+`EnsureFile(create=False)` is also a pure precondition: it passes an existing file on, or raises `NotFoundError`.
+"""

simplibs/path/actions/EnsureParentDir.py

@@ -0,0 +1,20 @@
+from simplibs.actions import create_action
+# Outers
+from ..logic.ensure import ensure_parent_dir
+
+
+EnsureParentDir = create_action(
+    ensure_parent_dir,
+    main_param="path",
+    class_name="EnsureParentDir",
+)
+"""Action wrapping `ensure_parent_dir` — guarantees the directory a path lives in exists, and passes the path on."""
+
+
+_DESIGN_NOTES = """
+# EnsureParentDir — Action Over `ensure_parent_dir`
+
+## Purpose
+The step right before a write: `RebasePath(...) >> EnsureParentDir() >> write_step`. The value flowing on is the
+file path itself, not its folder.
+"""

simplibs/path/actions/FilterPaths.py

@@ -0,0 +1,27 @@
+from simplibs.actions import create_action
+# Outers
+from ..logic.scanners import filter_paths
+
+
+FilterPaths = create_action(
+    filter_paths,
+    main_param="paths",
+    class_name="FilterPaths",
+    use_logging=False,
+)
+"""Action wrapping `filter_paths` — keeps the paths of a list that satisfy a Rule or callable."""
+
+
+_DESIGN_NOTES = """
+# FilterPaths — Action Over `filter_paths`
+
+## Purpose
+`CollectFiles() >> FilterPaths(rule=HasSuffix(".py") & ~IsHidden())`.
+
+## `rule` Is Required
+A filter without a rule would only copy the list. The main input is a collection of paths (not a generator).
+
+## Logging Is Off
+The result is a list that can hold tens of thousands of paths, and the `log_this` layer would record all of it.
+Remove `use_logging=False` once `log_this` is known to truncate large results.
+"""

simplibs/path/actions/MakeUniquePath.py

@@ -0,0 +1,22 @@
+from simplibs.actions import create_action
+# Outers
+from ..logic.transformers import make_unique_path
+
+
+MakeUniquePath = create_action(
+    make_unique_path,
+    main_param="path",
+    class_name="MakeUniquePath",
+)
+"""Action wrapping `make_unique_path` — returns the path, or a numbered variant of it that does not exist yet."""
+
+
+_DESIGN_NOTES = """
+# MakeUniquePath — Action Over `make_unique_path`
+
+## Purpose
+Choosing an output name that overwrites nothing: `RebasePath(...) >> MakeUniquePath()`.
+
+## Not a Reservation
+The name is free at the moment of the call; claim it by opening the result with mode `"x"`.
+"""

simplibs/path/actions/NormalizeEntryPath.py

@@ -0,0 +1,20 @@
+from simplibs.actions import create_action
+# Outers
+from ..logic.transformers import normalize_entry_path
+
+
+NormalizeEntryPath = create_action(
+    normalize_entry_path,
+    main_param="path",
+    class_name="NormalizeEntryPath",
+)
+"""Action wrapping `normalize_entry_path` — resolves an entry's folder and keeps its own name as written."""
+
+
+_DESIGN_NOTES = """
+# NormalizeEntryPath — Action Over `normalize_entry_path`
+
+## Purpose
+The first step of pipelines that act on the entry itself (delete, move, rename)
+rather than on its content — `NormalizeEntryPath() >> DeleteFile()`.
+"""

simplibs/path/actions/NormalizePath.py

@@ -0,0 +1,23 @@
+from simplibs.actions import create_action
+# Outers
+from ..logic.transformers import normalize_path
+
+
+NormalizePath = create_action(
+    normalize_path,
+    main_param="path",
+    class_name="NormalizePath",
+)
+"""Action wrapping `normalize_path` — makes a path absolute, `~`-expanded and (by default) symlink-resolved."""
+
+
+_DESIGN_NOTES = """
+# NormalizePath — Action Over `normalize_path`
+
+## Purpose
+The first step of most path pipelines (`NormalizePath() >> EnsureDir() >> CollectFiles()`), so every later
+step sees one canonical form of the path.
+
+## Configuration
+`NormalizePath(resolve_symlinks=False)` keeps symlinks as written. The main input is the path; the result is a `Path`.
+"""

simplibs/path/actions/RebasePath.py

@@ -0,0 +1,24 @@
+from simplibs.actions import create_action
+# Outers
+from ..logic.transformers import rebase_path
+
+
+RebasePath = create_action(
+    rebase_path,
+    main_param="path",
+    class_name="RebasePath",
+)
+"""Action wrapping `rebase_path` — maps a path from `source_root` to the same place under `target_root`."""
+
+
+_DESIGN_NOTES = """
+# RebasePath — Action Over `rebase_path`
+
+## Purpose
+The "where does the output of this input go" step:
+`RebasePath(source_root="src", target_root="out", new_suffix=".md")`.
+
+## Configuration
+`source_root` and `target_root` are required; `new_suffix` is optional (`None` keeps the name, `""` removes the
+suffix). Pure path arithmetic — pair it with `EnsureParentDir` before writing.
+"""

simplibs/path/actions/RelativizePath.py

@@ -0,0 +1,22 @@
+from simplibs.actions import create_action
+# Outers
+from ..logic.transformers import relativize_path
+
+
+RelativizePath = create_action(
+    relativize_path,
+    main_param="path",
+    class_name="RelativizePath",
+)
+"""Action wrapping `relativize_path` — expresses a path relative to `root`."""
+
+
+_DESIGN_NOTES = """
+# RelativizePath — Action Over `relativize_path`
+
+## Purpose
+Shows a collected path as it appears inside the scanned tree (`src/a/b.py` instead of the absolute path).
+
+## Configuration
+`RelativizePath(root=...)` — `root` is required. A path outside it raises a `ParamError` when the action runs.
+"""

simplibs/path/actions/__init__.py

@@ -0,0 +1,68 @@
+from .ChangeSuffix import ChangeSuffix
+from .CollectDirs import CollectDirs
+from .CollectFiles import CollectFiles
+from .CollectPaths import CollectPaths
+from .EnsureDir import EnsureDir
+from .EnsureFile import EnsureFile
+from .EnsureParentDir import EnsureParentDir
+from .FilterPaths import FilterPaths
+from .MakeUniquePath import MakeUniquePath
+from .NormalizeEntryPath import NormalizeEntryPath
+from .NormalizePath import NormalizePath
+from .RebasePath import RebasePath
+from .RelativizePath import RelativizePath
+
+
+__all__ = [
+    # transformers — path in, path out
+    "NormalizeEntryPath",
+    "NormalizePath",
+    "RebasePath",
+    "RelativizePath",
+    "ChangeSuffix",
+    "MakeUniquePath",
+    # ensure — make a filesystem state true
+    "EnsureDir",
+    "EnsureFile",
+    "EnsureParentDir",
+    # scanners — look at a tree
+    "CollectPaths",
+    "CollectFiles",
+    "CollectDirs",
+    "FilterPaths",
+]
+
+
+_DESIGN_NOTES = """
+# Path Actions Sub-Package
+
+## Purpose
+Every function of the library that takes one main value and returns one
+result, as an `Action`: constructed once with its options, then called with
+the main input and chainable with `>>`, `&` and `|`.
+
+```python
+pipeline = (
+    IsDir()                                   # a Rule — becomes a guard step
+    >> CollectFiles(include_filter=HasSuffix(".py"))
+    >> FilterPaths(rule=~IsHidden())
+)
+paths = pipeline("~/project")
+````
+
+## What Is Not Here
+
+- **Predicates (`checks/`, rules):** a bool is not a pipeline value. A Rule\
+  already works as a step — `Action` turns it into a pass-through `guard`.
+- **`iter_paths`:** a generator is consumed once and cannot be logged or\
+  re-run by the action machinery; pipelines use the list-returning collectors.
+
+## Async
+
+All thirteen are synchronous actions, so `await action.acall(data)` runs them\
+in a worker thread — the right model for blocking file-system calls.
+
+## Domain Folder: `__all__`
+
+Like `rules/`, this package defines `__all__` (the public actions).\
+"""

simplibs/path/annotations/PathLike.py

@@ -0,0 +1,43 @@
+from pathlib import Path
+from simplibs.types import str_not_blank
+
+
+PathLike = str_not_blank | Path
+"""A filesystem path given as a non-blank string or as a `Path` instance.
+
+The annotation of every path parameter in this library. A blank string is
+rejected on purpose: `Path("")` silently means "the current directory",
+which is almost never what the caller intended.
+"""
+
+
+_DESIGN_NOTES = """
+# PathLike — the accepted shape of a path argument
+
+## Purpose
+One shared annotation for every path parameter in `simplibs-path`, so the
+accepted input is defined (and described in error cards) in exactly one place.
+
+---
+
+## 1. Why a Blank String Is Rejected
+
+`Path("")` and `Path("   ")` do not fail — they quietly become `.` (the
+current working directory). `ensure_dir("")` would "succeed" and
+`collect_paths("")` would scan whatever directory the process happens to run
+in. Rejecting blank strings at the boundary turns that silent surprise into
+an immediate, readable error.
+
+## 2. Why `str | Path`, Not `os.PathLike`
+
+Every function normalizes its input through `Path` first. Keeping the
+accepted input to the two types people actually pass keeps validation
+messages short ("non-blank string | Path") and avoids bytes-based
+`os.PathLike` objects, which `Path` cannot represent.
+
+## 3. Not a Rule Input Type
+
+Rules never raise on a wrong input type — they use `to_path` (see
+`_helpers/to_path.py`) and answer `False`. This annotation is for the
+`@validate_call` boundary of functions only.
+"""

simplibs/path/annotations/PathPredicate.py

@@ -0,0 +1,39 @@
+from pathlib import Path
+from typing import Callable
+
+
+PathPredicate = Callable[[Path], bool]
+"""A `(Path) -> bool` predicate: a plain function, a lambda, or any `Rule`.
+
+A `Rule` instance is callable (`Rule.__call__` delegates to `is_valid`), so
+rules such as `HasSuffix(".py") & ~IsHidden()` fit this type directly —
+no special protocol is needed.
+"""
+
+
+_DESIGN_NOTES = """
+# PathPredicate — what a path filter may be
+
+## Purpose
+The annotation of `include_filter`, `exclude_filter` and `filter_paths`'s
+`rule`: anything callable with one `Path` that returns a truthy/falsy answer.
+
+---
+
+## 1. Why the Former `HasIsValid` Protocol Is Gone
+
+An earlier version also accepted any object with an `is_valid` method via a
+structural `Protocol`. But every `Rule` is already callable, and
+`build_typing_rule` turns `Callable[[...], R]` into a plain `IsCallable()`
+check (argument and return types are never inspected). The protocol added a
+second code path (`getattr(rule, "is_valid", rule)`) for objects that are
+not callable but carry `is_valid` — a shape nobody produces. Removing it
+leaves one rule: "it is callable".
+
+## 2. Resolved Once, Outside the Loop
+
+Consumers (`collect_paths`, `filter_paths`) resolve the predicate a single
+time via `as_path_predicate` (see `scanners/_helpers/`), which unwraps a
+`Rule` to its bound `is_valid` — skipping the one extra Python call of
+`Rule.__call__` per entry.
+"""

simplibs/path/annotations/RecursionDepth.py

@@ -0,0 +1,33 @@
+from typing import Annotated
+from simplibs.rules import is_bool, is_int, ge
+
+RecursionDepth = Annotated[bool | int, is_bool | (is_int & ge(0))]
+"""How deep a recursive scan may go.
+
+- `True`: infinite recursion.
+- `False`: no recursion (only the starting entries).
+- A non-negative `int` (`0`, `1`, `2`, ...): maximum depth of traversal.
+"""
+
+
+_DESIGN_NOTES = """
+# RecursionDepth — controlling traversal depth
+
+## Purpose
+A single shared annotation for recursive functions (`collect_paths`, `walk_tree`)
+to validate depth constraints uniformly across the library.
+
+---
+
+## 1. Why `bool` Combined With `int`
+
+In Python APIs, passing `True` or `False` is a clean and readable way to enable
+or disable recursion entirely without remembering numeric constants like `-1`
+or `sys.maxsize`. Combining `bool` with non-negative integers (`ge(0)`) gives
+the exact semantics needed: infinite, disabled, or an exact maximum depth limit.
+
+## 2. Boundary Enforcement
+
+Negative integers (e.g., `-1`) are strictly rejected by `ge(0)`, preventing invalid
+configurations at the `@validate_call` boundary.
+"""

simplibs/path/annotations/__init__.py

@@ -0,0 +1,21 @@
+from .PathLike import PathLike
+from .PathPredicate import PathPredicate
+from .RecursionDepth import RecursionDepth
+
+
+_DESIGN_NOTES = """
+# Path Shared Types Sub-Package
+
+## Purpose
+Annotations shared by several sub-packages (`transformers`, `ensure`,
+`scanners`, `rules`, `actions`). Kept at package level instead of inside
+`scanners/` because rules and functions outside the scanners need them too.
+
+## Internal Components Registry
+
+| Component        | Type       | Description                                                          |
+| :--------------- | :--------- | :------------------------------------------------------------------- |
+| `PathLike`       | Annotation | A non-blank string or a `Path` — the accepted shape of a path input. |
+| `PathPredicate`  | Annotation | A `(Path) -> bool` callable; every `Rule` fits.                      |
+| `RecursionDepth` | Annotation | `True`/`False` or a non-negative `int` — how deep a scan may go.     |
+"""

simplibs/path/logic/__init__.py

@@ -0,0 +1,41 @@
+_DESIGN_NOTES = """
+# Path Core Logic Package
+
+## Purpose
+The functional core of `simplibs-path`: plain, reusable functions that work on
+their own, with no knowledge of the `Rule` or `Action` layers. `rules/` and
+`actions/` are thin layers built *on top of* these functions — a rule wraps a
+check, an action wraps a function — never the other way round.
+
+This package groups; it does not export. It has no imports of its own, so
+importing it costs nothing and creates no import cycles. The main package
+`__init__` (`simplibs.path`) reaches into the four sub-packages below and
+propagates their public names.
+
+## Internal Components Registry
+
+| Sub-package    | Kind                     | What it holds                                                                                   |
+| :------------- | :----------------------- | :---------------------------------------------------------------------------------------------- |
+| `transformers` | Pure path arithmetic     | `normalize_path`, `rebase_path`, `relativize_path`, `change_suffix`, `make_unique_path` — path in, path out. |
+| `checks`       | Predicates with real logic | `is_empty_dir`, `is_hidden_path`, `is_path_readable`, `is_path_writable`, `is_valid_filename`, `is_within` — a `bool`, never an exception for disk problems. |
+| `ensure`       | Changes the disk         | `ensure_dir`, `ensure_file`, `ensure_parent_dir` — make a filesystem state true, return the normalized path. |
+| `scanners`     | Looks at a directory tree | `collect_paths`, `collect_files`, `collect_dirs`, `iter_paths`, `filter_paths`, plus the `ignore_names` constants. |
+
+## Layering
+The packages depend on each other in one direction only:
+
+* `transformers` and `checks` are leaves — neither imports the other.
+* `ensure` and `scanners` build on `transformers` (every path is normalized first).
+
+Two small helpers are deliberately shared with the `rules/` package, which
+imports them directly: `to_path` (in `checks/_helpers`) and `is_valid_suffix`
+(in `transformers/_helpers`). That keeps one definition of "a usable path"
+and "a suffix shape" for functions and rules alike.
+
+## Why `logic` Is Its Own Folder
+Without it, the package root would mix four logic packages with `rules/`,
+`actions/` and `annotations/` — seven siblings of very different kinds. Grouping
+the logic leaves the root readable as a map: *logic* (`logic`),
+*vocabulary of predicates* (`rules`), *vocabulary of pipeline steps*
+(`actions`) and *shared types* (`annotations`).
+"""