simplibs-path 0.1.0__py3-none-any.whl

simplibs/path/logic/checks/is_path_writable.py

@@ -0,0 +1,90 @@
+import os
+from simplibs.validate import validate_call
+# Outers
+from ...annotations import PathLike
+# Inners
+from ._helpers import can_create_inside, to_path
+
+
+@validate_call
+def is_path_writable(
+    path: PathLike,
+    *,
+    _validate_call: bool = True,
+) -> bool:
+    """Check whether a path could be written to right now, without changing anything.
+
+    Args:
+        path: The path to check — an existing file, an existing directory,
+            or a file that does not exist yet.
+        _validate_call: Internal bypass switch for `@validate_call` — rules
+            pass `False` because they have already checked the input type.
+
+    Returns:
+        True if an existing file can be opened for appending, if a file can
+        be created inside an existing directory, or if a missing file's
+        parent directory exists and accepts new files. False otherwise —
+        including a missing parent directory (nothing is created here).
+    """
+
+    # 1. Anything that cannot be turned into a path is not writable
+    candidate = to_path(path)
+    if candidate is None:
+        return False
+
+    # 2. Probe the real target — the only check that matches a later write
+    try:
+
+        # 2.1 An existing directory — can a file be created inside?
+        if candidate.is_dir():
+            return can_create_inside(candidate)
+
+        # 2.2 An existing file — append mode never changes its content
+        if candidate.is_file():
+            with candidate.open("ab"):
+                return True
+
+        # 2.3 Something else already occupies the name (broken symlink, device)
+        if os.path.lexists(candidate):
+            return False
+
+        # 2.4 A file that does not exist yet — its parent must accept new files
+        parent = candidate.parent
+        return parent.is_dir() and can_create_inside(parent)
+
+    # 3. Permission and OS-level failures mean "not writable"
+    except (OSError, ValueError):
+        return False
+
+
+_DESIGN_NOTES = """
+# is_path_writable — Writable Without Side Effects
+
+## Purpose
+The predicate behind `IsPathWritable`: "if I write here next, will the OS
+let me?".
+
+---
+
+## 1. Fixes Two Problems of the Old Version
+The former version opened *any* path in append mode. For a path that did not
+exist that **created an empty file** — a "check" with a lasting side effect,
+contradicting its own docstring. It also reported `False` for every
+directory. Now a missing file is judged by probing its parent directory
+(`can_create_inside`, which leaves no trace), and a directory is writable
+when files can be created inside it.
+
+## 2. Existing Files: Append Mode
+`open("ab")` fails on a read-only file, locked file or denied ACL, yet
+neither truncates nor modifies anything.
+
+## 3. Missing Parent Means False
+Creating parent directories is `ensure_parent_dir`'s job. "Is it writable
+*now*?" is honestly answered `False` when the folder is not there; a
+pipeline that wants to create it first simply orders the steps that way.
+
+## 4. Not a Reservation
+The answer holds at the moment of the call. Another process can change
+permissions or fill the disk before the actual write, so a real write must
+still handle its own errors.
+"""

simplibs/path/logic/checks/is_valid_filename.py

@@ -0,0 +1,47 @@
+from simplibs.validate import validate_call
+# Inners
+from ._helpers import find_filename_problem
+
+
+@validate_call
+def is_valid_filename(
+    name: str,
+    *,
+    portable: bool = True,
+    _validate_call: bool = True,
+) -> bool:
+    """Check whether a string is a usable single file or directory name.
+
+    Args:
+        name: The candidate name — a name only, not a path.
+        portable: If True (default), the name must be valid on both Windows
+            and POSIX systems. If False, only the current OS's rules apply.
+        _validate_call: Internal bypass switch for `@validate_call` — rules
+            pass `False` because they have already checked the input type.
+
+    Returns:
+        True if the name has no problem (see `find_filename_problem` for the
+        exact rules); False otherwise.
+    """
+
+    # 1. A name is valid exactly when no problem is found
+    return find_filename_problem(name, portable=portable) is None
+
+
+_DESIGN_NOTES = """
+# is_valid_filename — Is This String Safe as a File Name?
+
+## Purpose
+For code that builds file names from content (titles, identifiers, user
+input) and must not produce a name the filesystem refuses or silently alters.
+
+## Thin on Purpose
+All rules live in `find_filename_problem`, which also explains *why* a name
+fails — the `IsValidFilename` rule shows that text in its failure card. This
+function only turns "no problem" into `True`.
+
+## A Name, Not a Path
+`"dir/file.txt"` is not a valid *name* (it contains a separator). Check
+a path's last part with `Path(...).name` first, or use the rule, which does
+that for `Path` values.
+"""

simplibs/path/logic/checks/is_within.py

@@ -0,0 +1,88 @@
+import os
+from pathlib import Path
+from simplibs.validate import validate_call
+# Outers
+from ...annotations import PathLike
+# Inners
+from ._helpers import to_path
+
+@validate_call
+def is_within(
+    path: PathLike,
+    root: PathLike,
+    *,
+    resolve_symlinks: bool = True,
+    allow_equal: bool = True,
+    _validate_call: bool = True,
+) -> bool:
+    """Check whether a path lies inside a root directory, without touching its content.
+
+    Args:
+        path: The path to test.
+        root: The directory it is supposed to be inside.
+        resolve_symlinks: If True (default), symlinks and `..` are resolved
+            before comparing, so a link pointing out of `root` does not
+            count as inside. If False, the comparison is purely lexical.
+        allow_equal: Whether a path equal to `root` itself counts as inside.
+        _validate_call: Internal bypass switch for `@validate_call` — rules
+            pass `False` because they have already checked the input type.
+
+    Returns:
+        True if `path` is inside `root` (or equal to it, when allowed).
+        Never raises for unresolvable input — that is simply False.
+    """
+
+    # 1. Anything that cannot be turned into a path is not inside anything
+    candidate = to_path(path)
+    base = to_path(root)
+    if candidate is None or base is None:
+        return False
+
+    # 2. Make both absolute the same way
+    try:
+
+        # 2.1 Follow symlinks and collapse ".." through the real filesystem
+        if resolve_symlinks:
+            candidate = candidate.resolve()
+            base = base.resolve()
+
+        # 2.2 Purely lexical — absolute and collapsed, symlinks untouched
+        else:
+            candidate = Path(os.path.abspath(candidate))
+            base = Path(os.path.abspath(base))
+
+    # 3. Paths that cannot be resolved cannot be proven inside
+    except (OSError, RuntimeError, ValueError):
+        return False
+
+    # 4. Equal paths are decided by the flag, everything else by containment
+    if candidate == base:
+        return allow_equal
+    return candidate.is_relative_to(base)
+
+
+_DESIGN_NOTES = """
+# is_within — Containment Without String Tricks
+
+## Purpose
+The guard against path traversal ("`../../etc/passwd` must not leave the
+output folder") and the predicate behind `IsWithin`.
+
+---
+
+## 1. Why Not `str(path).startswith(str(root))`
+`/data/src2` starts with `/data/src` but is not inside it, `..` segments
+hide an escape, and Windows compares case-insensitively. `Path.is_relative_to`
+on normalized absolute paths compares whole path *parts*, with the right
+case rules for the platform.
+
+## 2. Safe by Default: Symlinks Are Resolved
+A symlink inside `root` that points outside it must not pass. Resolving both
+sides handles that. The cost is a few syscalls per call, so
+`resolve_symlinks=False` exists for filters over paths that `collect_paths`
+already produced in normalized form.
+
+## 3. Unresolvable Means False
+A security check that raises can be skipped by a broad `except`; one that
+answers `False` fails closed.
+"""

simplibs/path/logic/ensure/__init__.py

@@ -0,0 +1,22 @@
+from .ensure_dir import ensure_dir
+from .ensure_file import ensure_file
+from .ensure_parent_dir import ensure_parent_dir
+
+
+_DESIGN_NOTES = """
+# Path Ensure Sub-Package
+
+## Purpose
+Functions that make a filesystem state true — a directory exists, a file
+exists, a path's parent exists — and return the normalized path. These are
+the library's only functions that change the disk (besides what the caller
+writes itself), which is why they live apart from the pure `transformers/`.
+
+## Internal Components Registry
+
+| Component           | Type     | Description                                                              |
+| :------------------ | :------- | :----------------------------------------------------------------------- |
+| `ensure_dir`        | Function | Guarantees a directory exists, creating it and its parents.              |
+| `ensure_file`       | Function | Guarantees a file exists, optionally creating it and its parent directory. |
+| `ensure_parent_dir` | Function | Guarantees the directory a path lives in exists; returns the path itself. |
+"""

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

@@ -0,0 +1,25 @@
+from .raise_ensure_dir_error import raise_ensure_dir_error
+from .raise_ensure_dir_not_a_dir_error import raise_ensure_dir_not_a_dir_error
+from .raise_ensure_file_create_error import raise_ensure_file_create_error
+from .raise_ensure_file_not_a_file_error import raise_ensure_file_not_a_file_error
+from .raise_ensure_file_not_found_error import raise_ensure_file_not_found_error
+
+
+_DESIGN_NOTES = """
+# Path Ensure Diagnostic Helpers Sub-Package
+
+## Purpose
+Internal diagnostic helpers raising structured exceptions for the
+functions in `ensure/` (`ensure_dir`, `ensure_file`, `ensure_parent_dir`).
+These five files moved here unchanged from `validators/_validations/`.
+
+## Internal Components Registry
+
+| Component                              | Type     | Description                                                      |
+| :------------------------------------- | :------- | :--------------------------------------------------------------- |
+| `raise_ensure_dir_error`               | Function | Raises `AccessError` when a directory cannot be created.         |
+| `raise_ensure_dir_not_a_dir_error`     | Function | Raises `StateError` when a file blocks a wanted directory.       |
+| `raise_ensure_file_create_error`       | Function | Raises `AccessError` when a file cannot be created.              |
+| `raise_ensure_file_not_a_file_error`   | Function | Raises `StateError` when a directory blocks a wanted file.       |
+| `raise_ensure_file_not_found_error`    | Function | Raises `NotFoundError` for a missing file when `create=False`.   |
+"""

simplibs/path/logic/ensure/_validations/raise_ensure_dir_error.py

@@ -0,0 +1,40 @@
+from pathlib import Path
+from typing import NoReturn
+from simplibs.exception import AccessError
+
+
+def raise_ensure_dir_error(
+    path: Path,
+    caught_exc: Exception,
+) -> NoReturn:
+    """Raise AccessError when directory creation fails due to OS or permission errors."""
+
+    # 1. Raise structured AccessError wrapping the caught OS exception
+    raise AccessError(
+        error_name="DIRECTORY_CREATION_FAILED",
+        label=f"directory '{path}'",
+        value=str(path),
+        problem=(
+            f"Failed to guarantee directory at '{path}'.",
+            f"OS reported: {caught_exc}",
+        ),
+        expected="A writable parent filesystem location where directory can be created.",
+        how_to_fix=(
+            f"Check write permissions for parent directory '{path.parent}'.",
+            "Verify that the storage device is mounted and has sufficient free space.",
+        ),
+        exception=type(caught_exc),
+    )
+
+
+_DESIGN_NOTES = """
+# raise_ensure_dir_error — Directory Creation Validation Helper
+
+## Purpose
+Provides a structured exception when `ensure_dir` encounters an OS-level or
+permission error while attempting to create a directory tree using `mkdir`.
+
+## Integration
+- **Caller**: `ensure_dir` in `simplibs/path/base/ensure_dir.py`.
+- Emits a structured `AccessError` wrapping the caught exception instance.
+"""

simplibs/path/logic/ensure/_validations/raise_ensure_dir_not_a_dir_error.py

@@ -0,0 +1,36 @@
+from pathlib import Path
+from typing import NoReturn
+from simplibs.exception import StateError
+
+
+def raise_ensure_dir_not_a_dir_error(path: Path) -> NoReturn:
+    """Raise StateError when a path exists but is a file instead of a directory."""
+
+    # 1. Raise structured StateError wrapping a NotADirectoryError exception
+    raise StateError(
+        error_name="PATH_IS_NOT_A_DIRECTORY",
+        label=f"path '{path}'",
+        value=str(path),
+        problem=(
+            f"Expected directory at '{path}', but an existing file was found at this location.",
+        ),
+        expected="A directory path or a non-existent path where a directory can be created.",
+        how_to_fix=(
+            "Provide a path to a directory or a location that does not yet exist.",
+            f"Remove or rename the existing file at '{path}' if it should be replaced by a directory.",
+        ),
+        exception=NotADirectoryError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_ensure_dir_not_a_dir_error — Directory Type Validation Helper
+
+## Purpose
+Provides a structured exception when `ensure_dir` encounters an existing filesystem item
+at the given target path that is a file rather than a directory.
+
+## Integration
+- **Caller**: `ensure_dir` in `simplibs/path/base/ensure_dir.py`.
+- Emits a structured `StateError` wrapping a `NotADirectoryError`.
+"""

simplibs/path/logic/ensure/_validations/raise_ensure_file_create_error.py

@@ -0,0 +1,39 @@
+from pathlib import Path
+from typing import NoReturn
+from simplibs.exception import AccessError
+
+
+def raise_ensure_file_create_error(
+    path: Path,
+    caught_exc: Exception,
+) -> NoReturn:
+    """Raise AccessError when file creation fails due to OS or permission errors."""
+
+    # 1. Raise structured AccessError wrapping the caught OS exception
+    raise AccessError(
+        error_name="FILE_CREATION_FAILED",
+        label=f"file '{path}'",
+        value=str(path),
+        problem=(
+            f"Failed to create file at '{path}'.",
+            f"OS reported: {caught_exc}",
+        ),
+        expected="A writable directory location where a new file can be created.",
+        how_to_fix=(
+            f"Check write permissions for directory '{path.parent}'.",
+            "Verify that the storage device is accessible and not read-only.",
+        ),
+        exception=type(caught_exc),
+    )
+
+
+_DESIGN_NOTES = """
+# raise_ensure_file_create_error — File Creation Validation Helper
+
+## Purpose
+Provides a structured exception when `ensure_file` fails to touch or create a file on disk.
+
+## Integration
+- **Caller**: `ensure_file` in `simplibs/path/base/ensure_file.py`.
+- Emits a structured `AccessError` wrapping the caught exception instance.
+"""

simplibs/path/logic/ensure/_validations/raise_ensure_file_not_a_file_error.py

@@ -0,0 +1,36 @@
+from pathlib import Path
+from typing import NoReturn
+from simplibs.exception import StateError
+
+
+def raise_ensure_file_not_a_file_error(path: Path) -> NoReturn:
+    """Raise StateError when a path exists but is a directory instead of a file."""
+
+    # 1. Raise structured StateError wrapping an IsADirectoryError exception
+    raise StateError(
+        error_name="PATH_IS_NOT_A_FILE",
+        label=f"path '{path}'",
+        value=str(path),
+        problem=(
+            f"Expected file at '{path}', but an existing directory was found at this location.",
+        ),
+        expected="A regular file path or a non-existent path where a file can be created.",
+        how_to_fix=(
+            "Provide a path pointing to a file rather than a directory.",
+            f"Remove or rename the existing directory at '{path}' if a file is intended.",
+        ),
+        exception=IsADirectoryError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_ensure_file_not_a_file_error — File Type Validation Helper
+
+## Purpose
+Provides a structured exception when `ensure_file` encounters an existing directory
+where a regular file was expected.
+
+## Integration
+- **Caller**: `ensure_file` in `simplibs/path/base/ensure_file.py`.
+- Emits a structured `StateError` wrapping an `IsADirectoryError`.
+"""

simplibs/path/logic/ensure/_validations/raise_ensure_file_not_found_error.py

@@ -0,0 +1,36 @@
+from pathlib import Path
+from typing import NoReturn
+from simplibs.exception import NotFoundError
+
+
+def raise_ensure_file_not_found_error(path: Path) -> NoReturn:
+    """Raise NotFoundError when a required file is missing and create=False."""
+
+    # 1. Raise structured NotFoundError wrapping a FileNotFoundError exception
+    raise NotFoundError(
+        error_name="FILE_NOT_FOUND",
+        label=f"file '{path}'",
+        value=str(path),
+        problem=(
+            f"Required file '{path}' does not exist on disk.",
+            "Automatic creation was disabled because `create=False` was passed.",
+        ),
+        expected="An existing file path, or call ensure_file with create=True.",
+        how_to_fix=(
+            f"Ensure the file exists at '{path}' before invoking ensure_file.",
+            "Set `create=True` if you want ensure_file to create missing files automatically.",
+        ),
+        exception=FileNotFoundError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_ensure_file_not_found_error — File Absence Validation Helper
+
+## Purpose
+Provides a structured exception when `ensure_file` is called with `create=False` and the target file does not exist.
+
+## Integration
+- **Caller**: `ensure_file` in `simplibs/path/base/ensure_file.py`.
+- Emits a structured `NotFoundError` wrapping a `FileNotFoundError`.
+"""

simplibs/path/logic/ensure/ensure_dir.py

@@ -0,0 +1,83 @@
+import os
+from pathlib import Path
+from simplibs.validate import validate_call
+# Outers
+from ...annotations import PathLike
+from ..transformers import normalize_path
+# Inners
+from ._validations import raise_ensure_dir_error, raise_ensure_dir_not_a_dir_error
+
+
+@validate_call
+def ensure_dir(
+    path: PathLike,
+) -> Path:
+    """Guarantee that a directory exists, creating it (and any missing
+    parents) if necessary.
+
+    Args:
+        path: The directory path to guarantee.
+
+    Returns:
+        The normalized, guaranteed-to-exist directory `Path`.
+
+    Raises:
+        StateError: If something that is not a directory (a file) already
+            occupies the path.
+        AccessError: If the directory cannot be created due to
+            insufficient permissions or another OS-level failure.
+    """
+
+    # 1. Normalize the target path
+    normalized_path = normalize_path(path)
+
+    # 2. Already exists — must be a directory, not a file
+    if normalized_path.exists():
+        if not normalized_path.is_dir():
+            raise_ensure_dir_not_a_dir_error(normalized_path)
+        return normalized_path
+
+    # 3. Create the directory (and parents) if missing
+    try:
+        normalized_path.mkdir(parents=True, exist_ok=True)
+
+    # 4. Creation failed
+    except OSError as caught_exc:
+
+        # 4.1 Something else took the name meanwhile (a file created in the
+        #     gap since step 2) — a state problem, not a permission problem
+        if os.path.lexists(normalized_path) and not normalized_path.is_dir():
+            raise_ensure_dir_not_a_dir_error(normalized_path)
+
+        # 4.2 Permissions, a read-only disk, a file in the parent chain, ...
+        raise_ensure_dir_error(normalized_path, caught_exc)
+
+    # 5. Return the guaranteed directory
+    return normalized_path
+
+
+_DESIGN_NOTES = """
+# ensure_dir — "This Directory Exists Now"
+
+## Purpose
+Turns "I need this folder" into one step that either succeeds or explains
+why not. Returns the normalized path, so it chains
+(`NormalizePath >> EnsureDir >> CollectFiles`).
+
+---
+
+## 1. Moved From `validators/`, Two Small Corrections
+* `except (PermissionError, OSError)` is now `except OSError` —
+  `PermissionError` is a subclass, the tuple said nothing extra.
+* The race "a file appeared between the check and `mkdir`" used to surface
+  as `AccessError` with a how-to-fix about permissions. It is now reported
+  as the `StateError` it really is (step 4.1).
+
+## 2. A Symlink Is Followed
+`normalize_path` resolves symlinks first, so `ensure_dir("link")` for a
+dangling link creates the directory the link *points to*. That is the
+consistent meaning of "this path" everywhere in the library.
+
+## 3. Idempotent
+Calling it on an existing directory touches nothing and costs one `stat`.
+"""

simplibs/path/logic/ensure/ensure_file.py

@@ -0,0 +1,103 @@
+import os
+from pathlib import Path
+from simplibs.validate import validate_call
+# Outers
+from ...annotations import PathLike
+from ..transformers import normalize_path
+# Inners
+from .ensure_dir import ensure_dir
+from ._validations import (
+    raise_ensure_file_create_error,
+    raise_ensure_file_not_a_file_error,
+    raise_ensure_file_not_found_error,
+)
+
+
+@validate_call
+def ensure_file(
+    path: PathLike,
+    *,
+    create: bool = True,
+) -> Path:
+    """Guarantee that a path points to a file, optionally creating it
+    (and its parent directory) if missing.
+
+    Args:
+        path: The file path to guarantee.
+        create: If True (default), create the file and its parent
+            directory when missing. If False, a missing file raises
+            instead.
+
+    Returns:
+        The normalized, guaranteed-to-exist file `Path`.
+
+    Raises:
+        StateError: If the path exists but is a directory instead of a
+            file, or a parent in the chain is a file.
+        NotFoundError: If the file is missing and `create=False`.
+        AccessError: If the file cannot be created due to missing permissions
+            or an OS-level failure.
+    """
+
+    # 1. Normalize the target path
+    normalized_path = normalize_path(path)
+
+    # 2. Already exists — must be a file, not a directory
+    if normalized_path.exists():
+        if not normalized_path.is_file():
+            raise_ensure_file_not_a_file_error(normalized_path)
+        return normalized_path
+
+    # 3. Missing, and creation was not requested
+    if not create:
+        raise_ensure_file_not_found_error(normalized_path)
+
+    # 4. Missing, creation requested — guarantee the parent directory first
+    ensure_dir(normalized_path.parent)
+
+    # 5. Create the empty file
+    try:
+        normalized_path.touch(exist_ok=True)
+
+    # 6. Creation failed
+    except OSError as caught_exc:
+
+        # 6.1 A directory took the name meanwhile (created in the gap since step 2)
+        if os.path.lexists(normalized_path) and not normalized_path.is_file():
+            raise_ensure_file_not_a_file_error(normalized_path)
+
+        # 6.2 Permissions, a read-only disk, ...
+        raise_ensure_file_create_error(normalized_path, caught_exc)
+
+    # 7. Return the normalized, guaranteed-to-exist file
+    return normalized_path
+
+
+_DESIGN_NOTES = """
+# ensure_file — "This File Exists Now"
+
+## Purpose
+The file counterpart of `ensure_dir`: returns a path that is certainly a
+file, creating an empty one (and the folders above it) when allowed.
+
+---
+
+## 1. Moved From `validators/`, Same Two Corrections as `ensure_dir`
+`except OSError` instead of the redundant tuple, and the "a directory took
+the name between the check and `touch`" race is reported as a `StateError`
+(step 6.1).
+
+## 2. Existing Content Is Never Touched
+`touch(exist_ok=True)` only runs for a path that did not exist. An existing
+file is returned as it is — no truncation, no timestamp change.
+
+## 3. `create=False` — A Pure Assertion
+With creation off the function becomes "this file must already be there":
+it returns the path, or raises `NotFoundError`. That makes it usable as a
+precondition step in front of a read.
+
+## 4. A File in the Parent Chain
+`ensure_file("a_file/new.txt")` fails inside `ensure_dir` with a
+`StateError` naming the blocking file — the real cause, not a vague
+creation failure.
+"""