simplibs-path 0.1.0__py3-none-any.whl

simplibs/path/logic/checks/__init__.py

@@ -0,0 +1,29 @@
+from .is_empty_dir import is_empty_dir
+from .is_hidden_path import is_hidden_path
+from .is_path_readable import is_path_readable
+from .is_path_writable import is_path_writable
+from .is_valid_filename import is_valid_filename
+from .is_within import is_within
+
+
+_DESIGN_NOTES = """
+# Path Checks Sub-Package
+
+## Purpose
+Plain predicate functions with real logic behind them. Each returns a `bool`
+and never raises for disk problems; the matching `Rule` classes in `rules/`
+are thin wrappers over them. Checks that are a single pathlib call
+(`exists`, `is_file`, `is_dir`, ...) have no function here — the rule calls
+pathlib directly.
+
+## Internal Components Registry
+
+| Component          | Type     | Description                                                           |
+| :----------------- | :------- | :-------------------------------------------------------------------- |
+| `is_empty_dir`     | Function | An existing, listable directory with no entries.                      |
+| `is_hidden_path`   | Function | The final name starts with a dot (optionally: Windows hidden attribute). |
+| `is_path_readable` | Function | A file that can be opened, or a directory that can be listed.         |
+| `is_path_writable` | Function | A path that could be written to now — with no side effects.           |
+| `is_valid_filename`| Function | A string usable as a file name (portable by default).                 |
+| `is_within`        | Function | A path lies inside a root directory (symlink-safe by default).        |
+"""

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

@@ -0,0 +1,21 @@
+from .can_create_inside import can_create_inside
+from .find_filename_problem import find_filename_problem
+from .to_path import to_path
+
+
+_DESIGN_NOTES = """
+# Path Checks Internal Helpers Sub-Package
+
+## Purpose
+Building blocks private to `checks/`.
+
+## Internal Components Registry
+
+| Component                    | Type     | Description                                                            |
+| :--------------------------- | :------- | :--------------------------------------------------------------------- |
+| `can_create_inside`          | Function | Probes whether a file can be created in a directory, leaving no trace. |
+| `find_filename_problem`      | Function | Why a string is not a usable file name (`None` if it is).              |
+| `_find_length_problem`       | Function | Why a name is too long for POSIX and/or Windows.                       |
+| `_find_windows_name_problem` | Function | Windows-specific name problems (forbidden characters, device names).   |
+| `to_path`                    | Function | Safely converts a candidate (`str` or `Path`) into a `Path` or `None`. |
+"""

simplibs/path/logic/checks/_helpers/_find_length_problem.py

@@ -0,0 +1,48 @@
+# Inners
+from .constants import MAX_NAME_LENGTH
+
+
+def _find_length_problem(
+    name: str,
+    *,
+    windows: bool,
+    posix: bool,
+) -> str | None:
+    """Return why a name is too long, or None if its length is acceptable.
+
+    Args:
+        name: A single file or directory name (no path).
+        windows: Apply the NTFS limit (255 UTF-16 code units).
+        posix: Apply the limit of most POSIX filesystems (255 bytes in UTF-8).
+
+    Returns:
+        A short description of the problem, or `None`.
+    """
+
+    # 1. POSIX filesystems count bytes — multi-byte characters use more of the limit
+    if posix and len(name.encode("utf-8", "surrogatepass")) > MAX_NAME_LENGTH:
+        return f"is longer than {MAX_NAME_LENGTH} bytes in UTF-8"
+
+    # 2. NTFS counts UTF-16 code units — two bytes each
+    if windows and len(name.encode("utf-16-le", "surrogatepass")) // 2 > MAX_NAME_LENGTH:
+        return f"is longer than {MAX_NAME_LENGTH} UTF-16 characters"
+
+    # 3. Within the limit
+    return None
+
+
+_DESIGN_NOTES = """
+# find_length_problem — Name Length on Both Platform Families
+
+## Purpose
+The two limits are different units of the same number: bytes on POSIX,
+UTF-16 units on Windows. A name of 128 `é` characters is 256 bytes (too long
+on ext4) but only 128 units (fine on NTFS), so each platform family gets its
+own count and a *portable* check applies both.
+
+## `surrogatepass`
+POSIX names may contain undecodable bytes that Python represents as lone
+surrogates. Encoding them strictly would raise; `surrogatepass` encodes
+them anyway, so a weird-but-existing name is measured, not rejected by
+accident.
+"""

simplibs/path/logic/checks/_helpers/_find_windows_name_problem.py

@@ -0,0 +1,55 @@
+# Inners
+from .constants import WINDOWS_FORBIDDEN_CHARS, WINDOWS_RESERVED_NAMES
+
+
+def _find_windows_name_problem(name: str) -> str | None:
+    """Return why a name is invalid on Windows, or None if it is fine there.
+
+    Args:
+        name: A single file or directory name (no path).
+
+    Returns:
+        A short description of the first problem found, or `None`.
+    """
+
+    # 1. A backslash is a path separator on Windows
+    if "\\" in name:
+        return "contains a path separator '\\'"
+
+    # 2. Control characters and characters Windows forbids in names
+    for char in name:
+        if ord(char) < 32:
+            return f"contains a control character (code {ord(char)})"
+        if char in WINDOWS_FORBIDDEN_CHARS:
+            return f"contains the character {char!r}, which Windows forbids in names"
+
+    # 3. Windows silently strips a trailing dot or space
+    if name.endswith((".", " ")):
+        return "ends with a dot or a space, which Windows removes"
+
+    # 4. Reserved device names — the part before the first dot decides
+    base = name.split(".", 1)[0].rstrip(" ").upper()
+    if base in WINDOWS_RESERVED_NAMES:
+        return f"'{base}' is a reserved Windows device name"
+
+    # 5. Nothing wrong
+    return None
+
+
+_DESIGN_NOTES = """
+# find_windows_name_problem — Windows-Specific Name Rules
+
+## Purpose
+The Windows half of the filename check, separated from the platform-neutral
+rules so `find_filename_problem` can apply it on Windows, or everywhere when
+a *portable* name is wanted.
+
+## Returns Text, Not a Bool
+The same function feeds both `is_valid_filename` (needs a yes/no) and the
+`IsValidFilename` rule's failure card (needs the reason). Returning the
+reason once serves both and keeps a single source of truth.
+
+## Order of Checks
+Cheapest and most specific first; the reserved-name test comes last because
+it needs the string split and upper-cased.
+"""

simplibs/path/logic/checks/_helpers/can_create_inside.py

@@ -0,0 +1,39 @@
+import tempfile
+from pathlib import Path
+
+
+def can_create_inside(directory: Path) -> bool:
+    """Check whether a file can be created inside a directory — and leave no trace.
+
+    Args:
+        directory: An existing directory.
+
+    Returns:
+        True if an anonymous temporary file could be created (and was
+        removed again); False if the OS refused.
+    """
+
+    # 1. Create and immediately discard an anonymous temporary file
+    try:
+        with tempfile.TemporaryFile(dir=directory):
+            return True
+
+    # 2. Any permission or OS-level refusal means "not writable"
+    except OSError:
+        return False
+
+
+_DESIGN_NOTES = """
+# can_create_inside — the Honest Write Probe for a Directory
+
+## Purpose
+`os.access(path, W_OK)` is unreliable for directories on Windows (it mostly
+reports "yes") and ignores ACLs and read-only mounts everywhere. Actually
+creating a file is the only check that matches what a later write will
+experience.
+
+## Why It Leaves No Trace
+`TemporaryFile` is unlinked on creation on POSIX and opened with
+`O_TEMPORARY` on Windows: it never appears under a name that survives, even
+if the process is killed in the middle.
+"""

simplibs/path/logic/checks/_helpers/constants/MAX_NAME_LENGTH.py

@@ -0,0 +1,18 @@
+from typing import Final
+
+
+MAX_NAME_LENGTH: Final[int] = 255
+"""Longest single file or directory name that common filesystems accept.
+
+255 bytes on ext4/APFS-style filesystems, 255 UTF-16 code units on NTFS.
+"""
+
+
+_DESIGN_NOTES = """
+# MAX_NAME_LENGTH — the 255 Limit
+
+## Purpose
+One named number for `find_length_problem`, instead of a bare 255 in the
+code. It limits a single *name*, not a whole path (a full Windows path has a
+separate, much larger limit that is not checked here).
+"""

simplibs/path/logic/checks/_helpers/constants/WINDOWS_FORBIDDEN_CHARS.py

@@ -0,0 +1,25 @@
+from typing import Final
+
+
+WINDOWS_FORBIDDEN_CHARS: Final[frozenset[str]] = frozenset('<>:"|?*')
+"""Characters Windows does not allow inside a file name.
+
+The path separators `/` and `\\` are handled separately (they are never
+valid in a *name* on any platform / on Windows respectively), as are
+control characters.
+"""
+
+
+_DESIGN_NOTES = """
+# WINDOWS_FORBIDDEN_CHARS — Characters NTFS Rejects
+
+## Purpose
+The set `find_windows_name_problem` checks each character against. Kept
+as its own constant, like the other name lists in this library, so it can
+be read (and tested) at a glance.
+
+## Why `:` Is Included
+On Windows a colon in a name is not an error at the API level — it opens an
+NTFS alternate data stream (`file.txt:hidden`). For a portable filename
+check that is exactly the surprise to rule out.
+"""

simplibs/path/logic/checks/_helpers/constants/WINDOWS_RESERVED_NAMES.py

@@ -0,0 +1,27 @@
+from typing import Final
+
+
+WINDOWS_RESERVED_NAMES: Final[frozenset[str]] = frozenset(
+    {"CON", "PRN", "AUX", "NUL"}
+    | {f"COM{number}" for number in range(10)}
+    | {f"LPT{number}" for number in range(10)}
+)
+"""Device names Windows reserves, in upper case.
+
+A file name is reserved when its part before the first dot, ignoring case
+and trailing spaces, is one of these — `con`, `CON.txt` and `nul.log` all are.
+"""
+
+
+_DESIGN_NOTES = """
+# WINDOWS_RESERVED_NAMES — Legacy DOS Device Names
+
+## Purpose
+`CON`, `PRN`, `AUX`, `NUL`, `COM0`–`COM9`, `LPT0`–`LPT9` still refer to
+devices on Windows, whatever extension follows. Creating a file with such a
+name fails or silently writes to the device — a classic portability trap
+for tools that generate file names from content.
+
+## Upper Case, Matched Case-Insensitively
+The names are stored in upper case; the caller upper-cases the candidate.
+"""

simplibs/path/logic/checks/_helpers/constants/__init__.py

@@ -0,0 +1,20 @@
+from .MAX_NAME_LENGTH import MAX_NAME_LENGTH
+from .WINDOWS_FORBIDDEN_CHARS import WINDOWS_FORBIDDEN_CHARS
+from .WINDOWS_RESERVED_NAMES import WINDOWS_RESERVED_NAMES
+
+
+_DESIGN_NOTES = """
+# Path Checks Constants Sub-Package
+
+## Purpose
+Platform-specific and universal name constraints (lengths and forbidden elements)
+used during filename validation.
+
+## Internal Components Registry
+
+| Component                 | Type     | Description                                                          |
+| :------------------------ | :------- | :------------------------------------------------------------------- |
+| `MAX_NAME_LENGTH`         | Constant | The 255 limit on a single name.                                      |
+| `WINDOWS_FORBIDDEN_CHARS` | Constant | Characters Windows forbids in names.                                 |
+| `WINDOWS_RESERVED_NAMES`  | Constant | Reserved Windows device names (`CON`, `NUL`, `COM1`, ...).           |
+"""

simplibs/path/logic/checks/_helpers/find_filename_problem.py

@@ -0,0 +1,75 @@
+import os
+# Inners
+from ._find_length_problem import _find_length_problem
+from ._find_windows_name_problem import _find_windows_name_problem
+
+
+def find_filename_problem(
+    name: str,
+    *,
+    portable: bool = True,
+) -> str | None:
+    """Return why a string is not a usable file name, or None if it is.
+
+    Args:
+        name: A single file or directory name (no path).
+        portable: If True (default), the name must be valid on both Windows
+            and POSIX systems. If False, only the rules of the current
+            operating system apply.
+
+    Returns:
+        A short description of the first problem found
+        (`"contains the character '?', which Windows forbids in names"`),
+        or `None` when the name is acceptable.
+    """
+
+    # 1. Rules that hold on every platform
+    if not name.strip():
+        return "is empty or blank"
+    if name in (".", ".."):
+        return f"'{name}' is a reserved directory reference"
+    if "/" in name:
+        return "contains a path separator '/'"
+    if "\0" in name:
+        return "contains a null byte"
+
+    # 2. Decide which platform families apply
+    is_windows = os.name == "nt"
+    check_windows = portable or is_windows
+    check_posix = portable or not is_windows
+
+    # 3. Windows-specific rules
+    if check_windows:
+        problem = _find_windows_name_problem(name)
+        if problem is not None:
+            return problem
+
+    # 4. Length, counted the way each applicable platform counts it
+    return _find_length_problem(name, windows=check_windows, posix=check_posix)
+
+
+_DESIGN_NOTES = """
+# find_filename_problem — the One Source of Truth for Name Validity
+
+## Purpose
+Answers "is this string a usable file name?" with a reason, so both
+`is_valid_filename` (bool) and the `IsValidFilename` rule's failure card
+(text) are built on the same check.
+
+---
+
+## 1. Portable by Default
+This library generates names from content (extraction output), so the
+default is the strictest union of Windows and POSIX rules: a name that passes
+works everywhere the result may later be copied. `portable=False` relaxes it
+to the current OS only.
+
+## 2. Blank Is a Problem on Every Platform
+A name of spaces is legal on POSIX but unusable in practice and silently
+altered on Windows; treating it as invalid everywhere is the useful answer.
+
+## 3. What Is Not Checked
+The *existence* of the name, the total path length (Windows' 260-character
+`MAX_PATH`), and names that are valid but unwise (leading dashes, `~`). This
+is a check of the string itself, not of the disk.
+"""

simplibs/path/logic/checks/_helpers/to_path.py

@@ -0,0 +1,77 @@
+from pathlib import Path
+from typing import Any
+
+
+def to_path(value: Any) -> Path | None:
+    """Turn a path candidate into a `Path` without touching the disk, or return None.
+
+    Used by every rule, which must never raise on a bad input — a value
+    that cannot be a path simply fails the rule.
+
+    Args:
+        value: Any value; only a `str` or a `Path` is a path candidate.
+
+    Returns:
+        The `Path` with a leading `~` expanded, or `None` if `value` is not
+        a `str`/`Path`, is blank, contains a null byte, or cannot be
+        expanded.
+    """
+
+    # 1. Only str and Path instances are path candidates
+    if not isinstance(value, (str, Path)):
+        return None
+
+    # 2. A blank string would silently become the current directory
+    if isinstance(value, str) and not value.strip():
+        return None
+
+    # 3. A null byte makes every later filesystem call raise ValueError
+    if "\0" in str(value):
+        return None
+
+    # 4. Expand "~" — pure string work, no stat/resolve syscalls
+    try:
+        return Path(value).expanduser()
+
+    # 5. "~unknown_user" or another unusable value — not a path
+    except (RuntimeError, OSError, ValueError):
+        return None
+
+
+_DESIGN_NOTES = """
+# to_path — the one safe str/Path → Path conversion
+
+## Purpose
+`Rule.is_valid` must never raise, and every path rule starts the same way:
+"is this even a path, and which one?". `to_path` is that shared first step,
+so no rule repeats the `isinstance` / blank / null-byte / `expanduser`
+dance.
+
+---
+
+## 1. Returns None Instead of Raising
+
+The caller decides what a non-path means: a rule answers `False` (and its
+`build_exception` reports a type problem), a function would have been
+rejected earlier by the `PathLike` annotation.
+
+## 2. Why Only `expanduser`, Never `resolve`
+
+Rules run inside filters over thousands of entries. `resolve()` is a
+syscall per call and follows symlinks; `expanduser()` is string work. The
+entries produced by `collect_paths` are already absolute and normalized, so
+nothing more is needed — while a user-typed `~/project` still means what
+they expect.
+
+## 3. Why the Null-Byte Check Is Explicit
+
+`Path("a\\0b")` constructs fine; the `ValueError: embedded null byte` only
+appears later, at the first `stat`/`open`. Catching it here keeps that
+failure out of every rule's `is_valid`.
+
+## 4. `~unknown_user`
+
+On POSIX `Path("~unknown").expanduser()` raises `RuntimeError`; on Windows it
+is expanded to a sibling of the home directory. Both outcomes are handled:
+a `RuntimeError` becomes `None`, a successful expansion is returned.
+"""

simplibs/path/logic/checks/is_empty_dir.py

@@ -0,0 +1,59 @@
+import os
+from simplibs.validate import validate_call
+# Outers
+from ...annotations import PathLike
+# Inners
+from ._helpers import to_path
+
+
+@validate_call
+def is_empty_dir(
+    path: PathLike,
+    *,
+    _validate_call: bool = True,
+) -> bool:
+    """Check whether a path is an existing directory with no entries.
+
+    Args:
+        path: The path to check.
+        _validate_call: Internal bypass switch for `@validate_call` — rules
+            pass `False` because they have already checked the input type.
+
+    Returns:
+        True only for an existing, listable, empty directory. False for a
+        non-empty directory, a file, a missing path, or a directory that
+        cannot be listed (its emptiness is unknown).
+    """
+
+    # 1. Anything that cannot be turned into a path is not an empty directory
+    candidate = to_path(path)
+    if candidate is None:
+        return False
+
+    # 2. Ask for the first entry only — never list the whole directory
+    try:
+        with os.scandir(candidate) as entries:
+            return next(entries, None) is None
+
+    # 3. Not a directory, missing, or not listable — not (known to be) empty
+    except (OSError, ValueError):
+        return False
+
+
+_DESIGN_NOTES = """
+# is_empty_dir — Cheap Emptiness Test
+
+## Purpose
+Used by the `IsEmptyDir` rule, and useful before cleanup or output steps
+("only write into an empty folder").
+
+## First Entry Only
+`next(entries, None)` stops after one entry; a directory with a million
+files costs the same as an empty one. `os.scandir` also never raises for
+`.` and `..` — they are not yielded.
+
+## Unknown Is False
+A directory that cannot be listed (permissions) is neither known to be
+empty nor known to be non-empty. The predicate answers `False` — "not
+proven empty" — which is the safe side for a cleanup decision.
+"""

simplibs/path/logic/checks/is_hidden_path.py

@@ -0,0 +1,78 @@
+import os
+import stat
+from simplibs.validate import validate_call
+# Outers
+from ...annotations import PathLike
+# Inners
+from ._helpers import to_path
+
+@validate_call
+def is_hidden_path(
+    path: PathLike,
+    *,
+    check_attributes: bool = False,
+    _validate_call: bool = True,
+) -> bool:
+    """Check whether a path's final name marks it as hidden.
+
+    Args:
+        path: The path to check. Only its final name is considered, not the
+            directories above it.
+        check_attributes: If True, on Windows an existing path that carries
+            the "hidden" file attribute also counts. No effect elsewhere.
+        _validate_call: Internal bypass switch for `@validate_call` — rules
+            pass `False` because they have already checked the input type.
+
+    Returns:
+        True if the final name starts with a dot (`.git`, `.env`), or — with
+        `check_attributes` on Windows — the hidden attribute is set. `.` and
+        `..` are never hidden.
+    """
+
+    # 1. Anything that cannot be turned into a path is not hidden
+    candidate = to_path(path)
+    if candidate is None:
+        return False
+
+    # 2. The Unix convention — a leading dot in the final name
+    name = candidate.name
+    if name.startswith(".") and name not in (".", ".."):
+        return True
+
+    # 3. The Windows convention — an attribute on the file, only when asked for
+    if check_attributes and os.name == "nt":
+        try:
+            attributes = getattr(candidate.stat(), "st_file_attributes", 0)
+        except OSError:
+            return False
+        return bool(attributes & stat.FILE_ATTRIBUTE_HIDDEN)
+
+    # 4. Nothing marks it as hidden
+    return False
+
+
+_DESIGN_NOTES = """
+# is_hidden_path — Hidden by Name, Optionally by Attribute
+
+## Purpose
+The predicate behind `IsHidden`, meant for filters such as
+`exclude_filter=IsHidden()`.
+
+---
+
+## 1. Name-Based by Default
+The dot convention needs no disk access, which matters in a filter running
+over thousands of entries, and it behaves identically on every platform
+(`.git` is hidden to a scanner on Windows too).
+
+## 2. The Windows Attribute Is Opt-In
+Reading it costs a `stat` call per path, and it only exists on Windows.
+`check_attributes=True` asks for it; elsewhere the flag is simply ignored so
+the same code runs everywhere.
+
+## 3. Only the Final Name
+`/home/me/.config/tool/settings.json` is not "hidden" by this function —
+its *name* is not. Whether a file lives under a hidden directory is a
+question about the path's parents, which scanners answer by pruning
+(`ignore_names`) rather than by testing each entry.
+"""

simplibs/path/logic/checks/is_path_readable.py

@@ -0,0 +1,73 @@
+import os
+from simplibs.validate import validate_call
+# Outers
+from ...annotations import PathLike
+# Inners
+from ._helpers import to_path
+
+@validate_call
+def is_path_readable(
+    path: PathLike,
+    *,
+    _validate_call: bool = True,
+) -> bool:
+    """Check whether a file can be read, or a directory listed, without raising.
+
+    Args:
+        path: The file or directory to check.
+        _validate_call: Internal bypass switch for `@validate_call` — rules
+            pass `False` because they have already checked the input type.
+
+    Returns:
+        True for an existing regular file that can be opened for reading, or
+        an existing directory whose entries can be listed; False otherwise
+        (including a missing path, a broken symlink, or a special file).
+    """
+
+    # 1. Anything that cannot be turned into a path is not readable
+    candidate = to_path(path)
+    if candidate is None:
+        return False
+
+    # 2. Actually try — the only check that matches what a later read experiences
+    try:
+
+        # 2.1 A directory is readable when its entries can be listed
+        if candidate.is_dir():
+            with os.scandir(candidate):
+                return True
+
+        # 2.2 A file is readable when it can be opened for reading
+        if candidate.is_file():
+            with candidate.open("rb"):
+                return True
+
+    # 3. Permission and OS-level failures mean "not readable"
+    except (OSError, ValueError):
+        return False
+
+    # 4. Missing paths, broken symlinks and special files
+    return False
+
+
+_DESIGN_NOTES = """
+# is_path_readable — Can This Be Read Right Now?
+
+## Purpose
+The predicate behind the `IsPathReadable` rule and a natural precondition
+for any extraction step ("is the source even readable?").
+
+## Why Open It Instead of `os.access`
+On Windows `os.access(path, R_OK)` ignores ACLs, and on every platform it
+cannot see a file locked by another process. Opening the file (or listing
+the directory) is the only check that agrees with what the next real read
+will experience. Opening for reading changes nothing on disk.
+
+## Regular Files and Directories Only
+FIFOs, sockets and devices can block or have side effects when opened, so
+they answer `False` without being touched.
+
+## Never Raises for Disk Problems
+Anything the OS refuses is a legitimate `False`. A wrong *type* of argument
+is still rejected by the `PathLike` annotation before the body runs.
+"""