rootle 0.1.0__tar.gz → 1.2.0__tar.gz

{rootle-0.1.0 → rootle-1.2.0}/.config/rumdl.toml

@@ -16,6 +16,9 @@ strict = true  # Check code blocks too
 "docs/testing/*.md" = [
   "MD041",
 ]
+"docs/types/*.md" = [
+  "MD041",
+]
 "docs/winerror.md" = [
   "MD041",
 ]

{rootle-0.1.0 → rootle-1.2.0}/CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md
 
-rootle is a Python package with functions for interacting with the file systems. Each function lives in a module of its own with the same name (`src/rootle/<name>.py`) and is re-exported from `rootle`. Helpers for testing code that uses the file system live in `rootle.testing` the same way (`src/rootle/testing/<name>.py`). Windows error codes live in `rootle.winerror` (`src/rootle/winerror.py`), like Python's `errno`, documented on one page, `docs/winerror.md`.
+rootle is a Python package with functions for interacting with the file systems. Each function lives in a module of its own with the same name (`src/rootle/<name>.py`) and is re-exported from `rootle`. Helpers for testing code that uses the file system live in `rootle.testing` the same way (`src/rootle/testing/<name>.py`). Types that functions return live in `rootle.types`, each in a module named after it in lowercase (`src/rootle/types/identity.py` for `Identity`). Windows error codes live in `rootle.winerror` (`src/rootle/winerror.py`), like Python's `errno`, documented on one page, `docs/winerror.md`.
 
 ## Commands
 
@@ -22,7 +22,7 @@ mise exec -- uv run --locked ruff format       # Format Python
 - `.config/mise.toml`•`min_version` ↔ the mise-action `version` in every job that installs mise, in `.github/workflows/ci.yml` and `.github/workflows/release.yml`.
 - After changing `.config/mise.toml`•`tools`, run `mise lock`, because CI sets `MISE_LOCKED=1`.
 - Every `lint:*` task in `.config/mise.toml` ↔ a step of its own in `.github/workflows/ci.yml`'s `lint` job.
-- Every function exported from `rootle` ↔ its own page `docs/functions/<name>.md` and its entry under "Functions" in `zensical.toml`•`project`•`nav`. Likewise for `rootle.testing`, with `docs/testing/<name>.md` and "Testing". `tests/test_docs.py` checks both, for every module in its `SECTIONS`.
+- Every function exported from `rootle` ↔ its own page `docs/functions/<name>.md` and its entry under "Functions" in `zensical.toml`•`project`•`nav`. Likewise for `rootle.testing`, with `docs/testing/<name>.md` and "Testing", and for `rootle.types`, with `docs/types/<module>.md` and "Types". `tests/test_docs.py` checks both, for every module in its `SECTIONS`.
 - `.config/mise.toml`•`tools`•`uv` ↔ `pyproject.toml`•`tool.uv`•`required-version`, which it must satisfy. The range's floor must never be above the uv that Dependabot's uv updater bundles (0.12.19 on 2026-10-18), or every one of Dependabot's uv updates fails.
 - `pyproject.toml`•`project`•`requires-python` ↔ `pyproject.toml`•`tool.pyright`•`pythonVersion` ↔ `.python-version`.
 

{rootle-0.1.0 → rootle-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rootle
-Version: 0.1.0
+Version: 1.2.0
 Summary: Python functions to rootle around in your file system
 Project-URL: Issues, https://github.com/cariad/rootle/issues
 Project-URL: Source, https://github.com/cariad/rootle

rootle-1.2.0/docs/functions/ends_like_directory.md

@@ -0,0 +1,3 @@
+::: rootle.ends_like_directory.ends_like_directory
+    options:
+      heading_level: 1

rootle-1.2.0/docs/functions/identity.md

@@ -0,0 +1,3 @@
+::: rootle.identity.identity
+    options:
+      heading_level: 1

rootle-1.2.0/docs/functions/relative_within.md

@@ -0,0 +1,3 @@
+::: rootle.relative_within.relative_within
+    options:
+      heading_level: 1

rootle-1.2.0/docs/functions/status.md

@@ -0,0 +1,3 @@
+::: rootle.status.status
+    options:
+      heading_level: 1

rootle-1.2.0/docs/testing/can_chmod_deny_listing.md

@@ -0,0 +1,3 @@
+::: rootle.testing.can_chmod_deny_listing.can_chmod_deny_listing
+    options:
+      heading_level: 1

rootle-1.2.0/docs/testing/can_chmod_deny_writing.md

@@ -0,0 +1,3 @@
+::: rootle.testing.can_chmod_deny_writing.can_chmod_deny_writing
+    options:
+      heading_level: 1

rootle-1.2.0/docs/testing/is_treated_as_same_name.md

@@ -0,0 +1,3 @@
+::: rootle.testing.is_treated_as_same_name.is_treated_as_same_name
+    options:
+      heading_level: 1

rootle-1.2.0/docs/types/identity.md

@@ -0,0 +1,3 @@
+::: rootle.types.identity.Identity
+    options:
+      heading_level: 1

rootle-1.2.0/src/rootle/__init__.py

@@ -0,0 +1,13 @@
+from .ends_like_directory import ends_like_directory
+from .identity import identity
+from .relative_within import relative_within
+from .resolve import resolve
+from .status import status
+
+__all__ = [
+    "ends_like_directory",
+    "identity",
+    "relative_within",
+    "resolve",
+    "status",
+]

rootle-1.2.0/src/rootle/_identity_of_status.py

@@ -0,0 +1,22 @@
+from os import stat_result
+
+from .types import Identity
+
+
+def identity_of_status(st: stat_result) -> Identity | None:
+    """
+    Get the identity in `st`, a file's status, or `None` when it has none, like when
+    Windows can't open the file.
+    """
+    # A file's number identifies it only when it isn't zero.
+    #
+    # When Windows can't open a file, it reads the file's attributes from its directory
+    # instead, which has no file index, and some file systems never report one. Every
+    # such file would share that identity, so it mustn't pass as one.
+    if st.st_ino == 0:
+        return None
+
+    return Identity(
+        device=st.st_dev,
+        inode=st.st_ino,
+    )

rootle-1.2.0/src/rootle/_status_of_resolved.py

@@ -0,0 +1,53 @@
+from os import PathLike, stat, stat_result
+from pathlib import Path
+
+from rootle.exceptions import _os_error
+
+from . import winerror
+
+
+def status_of_resolved(
+    resolved: Path,
+    path: PathLike[str] | str,
+    *,
+    follow_symlinks: bool = True,
+) -> stat_result | None:
+    """
+    Get the status of the file at `resolved`, which `path` already resolved to, or
+    `None` when nothing exists there. Errors name `path` as it was given.
+
+    Unless `follow_symlinks` is set, a symlink at `resolved` isn't followed, like when
+    it appeared after `path` was resolved.
+    """
+    try:
+        return stat(
+            resolved,
+            follow_symlinks=follow_symlinks,
+        )
+
+    # Windows reports a path through a file as missing, so `NotADirectoryError` is
+    # raised here only on POSIX. Either way, nothing exists at the path.
+    except NotADirectoryError:  # pragma: posix-only
+        # `NotADirectoryError` means that one of the path's parents is a file, so
+        # nothing can exist at the path.
+        return None
+
+    except FileNotFoundError as ex:
+        # Windows maps more than a missing file to `ENOENT`, like a network path that
+        # can't be reached, and that mustn't pass as nothing existing there.
+        missing = (
+            None,
+            winerror.FILE_NOT_FOUND,
+            winerror.PATH_NOT_FOUND,
+        )
+
+        if getattr(ex, "winerror", None) in missing:
+            return None
+
+        raise _os_error.with_path(ex, path) from ex
+
+    except OSError as ex:
+        # The path can change after it's resolved, so `stat` can still fail. `ex`
+        # names the resolved path, so describe the path as it was given instead, like
+        # `resolve` does.
+        raise _os_error.with_path(ex, path) from ex

rootle-1.2.0/src/rootle/ends_like_directory.py

@@ -0,0 +1,55 @@
+from os import PathLike, altsep, fspath, sep
+from os.path import splitdrive
+
+
+def ends_like_directory(path: PathLike[str] | str) -> bool:
+    r"""
+    Check whether `path` ends like a directory, with a separator or a `.` or `..` name,
+    which only a directory can have, whether or not one exists there.
+
+    [`Path`][pathlib.Path] drops a trailing separator and `.`, so `Path("docs/")` and
+    `Path("docs/.")` can't say this, but the path as it was given still can. Only the
+    spelling is checked, never the file system.
+
+    **Linux & macOS:** The separator is `/`.
+
+    **Windows:** The separator is `\` or `/`, and a drive or share comes off first, so
+    `C:.` and `C:..` end like a directory but `C:` alone doesn't.
+
+    Args:
+        path: Path to check.
+
+    Returns:
+        `True` when `path` ends with a separator or a `.` or `..` name, otherwise
+        `False`.
+
+    Examples:
+        ```python
+        ends_like_directory("docs/")
+        # True
+
+        ends_like_directory("docs/.")
+        # True
+
+        ends_like_directory("docs/..")
+        # True
+
+        ends_like_directory("docs")
+        # False
+        ```
+    """
+    name = fspath(path)
+
+    # Only Windows has drives, and a drive on its own names no path component.
+    name = splitdrive(name)[1]
+
+    # An empty path names nothing, so it doesn't end like anything.
+    if not name:
+        return False
+
+    # Only Windows has an alternative separator.
+    for separator in (s for s in (sep, altsep) if s):
+        name = name.rpartition(separator)[2]
+
+    # A path that ends with a separator has an empty last name.
+    return name in ("", ".", "..")

rootle-1.2.0/src/rootle/exceptions/_not_a_directory_error.py

@@ -0,0 +1,11 @@
+from errno import ENOTDIR
+from os import PathLike, fspath, strerror
+
+
+def not_a_directory(path: PathLike[str] | str) -> NotADirectoryError:
+    """Make the error that says `path`, as the caller gave it, isn't a directory."""
+    return NotADirectoryError(
+        ENOTDIR,
+        strerror(ENOTDIR),
+        fspath(path),
+    )

rootle-1.2.0/src/rootle/exceptions/_os_error.py

@@ -0,0 +1,31 @@
+from errno import EINVAL
+from os import PathLike, fspath
+
+
+def null_character(path: PathLike[str] | str) -> OSError:
+    """Make an error that says `path` holds a null character."""
+    return OSError(
+        # `EINVAL` rather than the `ENOENT` of an empty path, so it can't be mistaken
+        # for a missing file.
+        EINVAL,
+        "The path holds a null character",
+        fspath(path),
+    )
+
+
+def with_path(ex: OSError, path: PathLike[str] | str) -> OSError:
+    """
+    Copy `ex` so that it describes `path` as the caller gave it, rather than whichever
+    part of that path, or wherever it leads, the error happened at.
+
+    Keep Windows' own error code, because Windows maps many of them to the same `errno`.
+    Other platforms ignore it.
+
+    An error made from a message alone has no `strerror`, so keep its message.
+    """
+    return OSError(
+        ex.errno,
+        ex.strerror or str(ex),
+        fspath(path),
+        getattr(ex, "winerror", None),
+    )

rootle-1.2.0/src/rootle/exceptions/_permission_error.py

@@ -0,0 +1,11 @@
+from errno import EACCES
+from os import PathLike, fspath
+
+
+def unreadable_identity_error(path: PathLike[str] | str) -> PermissionError:
+    """Make the error that says the identity of the file at `path` can't be read."""
+    return PermissionError(
+        EACCES,
+        "The file's identity can't be read",
+        fspath(path),
+    )

rootle-1.2.0/src/rootle/identity.py

@@ -0,0 +1,91 @@
+from os import PathLike
+
+from rootle.exceptions import _permission_error
+
+from ._identity_of_status import identity_of_status
+from .status import status
+from .types import Identity
+
+
+def identity(path: PathLike[str] | str) -> Identity | None:
+    """
+    Identify the file at `path`, following every symlink it contains.
+
+    Two paths have the same identity when they name the same file. That's true of a
+    symlink or a hard link to the file, and of a spelling that a case- or
+    normalisation-insensitive file system treats as the same name, like `README.md` and
+    `readme.md` on macOS's default APFS.
+
+    Comparing paths as strings can't see any of those, so compare identities instead.
+    Nothing exists at a missing path, so it has no identity, `None`, and two missing
+    paths compare as equal. Check for `None` before comparing.
+
+    The path is resolved with [`resolve`][rootle.resolve.resolve] before it's
+    identified, so a `..` after a directory that doesn't exist yet steps up the same
+    way it will once the directory is created. For example, `missing/../doc.md` is
+    identified as `doc.md`.
+
+    **Linux & macOS:** A `..` after a file raises an error.
+
+    **Windows:** A `..` after a file steps up. Windows can't read the identity of a
+    file that it can't open, like one that's locked or whose permissions deny it, so
+    that raises an error. So does a network path that can't be reached, which Windows
+    reports as missing.
+
+    Args:
+        path: Path to the file to identify.
+
+    Returns:
+        The file's [identity][rootle.types.identity.Identity], or `None` when nothing
+        exists at `path`.
+
+    Raises:
+        OSError:
+            - When a part of the path can't be read — for example, when permissions deny
+              it, symlinks loop, a `..` steps up from a file on Linux or macOS, or when
+              the path is relative and the working directory is gone. A safety check
+              that can't be made must fail rather than pass.
+            - When `path` ends with a separator or `.`, which says it's a directory, but
+              leads to a file.
+            - When `path` is empty, which names nothing.
+            - When `path` contains a null character.
+            - When the file exists but its identity can't be read, like when Windows
+              can't open it.
+
+            The error names `path` as it was given.
+
+    Examples:
+        Given this directory, where `latest` is a symlink to `v2`:
+
+        ```text
+        /docs
+        ├── latest -> v2
+        └── v2
+            └── guide.md
+        ```
+
+        Every name for a file has the same identity:
+
+        ```python
+        identity("/docs/latest/guide.md") == identity("/docs/v2/guide.md")
+        # True
+        ```
+
+        Nothing exists at a missing path, so it has no identity:
+
+        ```python
+        identity("/docs/v2/missing.md")
+        # None
+        ```
+    """
+    st = status(path)
+
+    if st is None:
+        return None
+
+    found = identity_of_status(st)
+
+    if found is None:
+        raise _permission_error.unreadable_identity_error(path)
+
+    return found

rootle-1.2.0/src/rootle/relative_within.py

@@ -0,0 +1,207 @@
+from os import PathLike, stat_result
+from os.path import ALLOW_MISSING, realpath
+from pathlib import Path, PurePath
+from stat import S_ISDIR
+
+from rootle.exceptions import _not_a_directory_error, _os_error, _permission_error
+
+from ._identity_of_status import identity_of_status
+from ._status_of_resolved import status_of_resolved
+from .resolve import resolve
+from .status import status
+
+
+def _resolves_to_itself(part: Path, path: PathLike[str] | str) -> bool:
+    """
+    Check whether `part`, a part of the path that `path` resolved to, still resolves to
+    itself, so that a path through it isn't redirected somewhere else, like by a symlink
+    or a Windows directory junction that's appeared since. Errors name `path` as it was
+    given.
+    """
+    try:
+        canon = realpath(
+            part,
+            strict=ALLOW_MISSING,
+        )
+
+    except OSError as ex:
+        raise _os_error.with_path(ex, path) from ex
+
+    return Path(canon) == part
+
+
+def relative_within(
+    path: PathLike[str] | str,
+    directory: PathLike[str] | str,
+) -> PurePath | None:
+    """
+    Get the path of `path` relative to `directory`, or `None` when `path` isn't
+    `directory` or within it.
+
+    The path is resolved with [`resolve`][rootle.resolve.resolve] first, so every
+    symlink it contains is followed, even a dangling one at its end, and a `..` after a
+    directory that doesn't exist yet steps up the same way it will once the directory
+    is created. A path that leads out of `directory` through a symlink isn't within it,
+    even when it's named within it.
+
+    Then the resolved path and each of its parents are compared with `directory` by
+    [`identity`][rootle.identity.identity], so a spelling that a case- or
+    normalisation-insensitive file system treats as the same name, like
+    `TEMPLATES/build` for `templates/build` on macOS's default APFS, is still within
+    `templates`. A path that doesn't exist yet is judged by its nearest parents that
+    do.
+
+    Each part of the resolved path is checked again as it's compared, so a symlink that
+    appears in the path after it's resolved isn't followed into `directory`. The answer
+    is only true at the moment it's made, though. A path that changes while it's
+    checked, or afterwards, can lead somewhere else by the time it's used.
+
+    Nothing can be within a directory that doesn't exist, so a missing `directory`
+    returns `None`. Nothing can be within a file either, so a `directory` that's a file
+    raises an error.
+
+    The relative path is a [`PurePath`][pathlib.PurePath], which can't touch the file
+    system, because it's relative to `directory` rather than to the working directory.
+    Join it to `directory` to make a [`Path`][pathlib.Path], or call
+    [`as_posix()`][pathlib.PurePath.as_posix] to spell it with forward slashes on every
+    operating system.
+
+    **Linux & macOS:** The relative path keeps the spelling that `path` gave each name,
+    or that a symlink gave the names it leads to, so `docs/GUIDE.md` is `GUIDE.md`
+    within `docs`, even when the file system stores `guide.md`. A `..` after a file
+    raises an error.
+
+    **Windows:** The relative path uses the spelling that the file system stores for
+    each name that exists, so `docs/GUIDE.md` is `guide.md` within `docs` when the file
+    system stores `guide.md`. A name that doesn't exist keeps the spelling that `path`
+    gave it. A `..` after a file steps up. Windows can't read the identity of a file
+    that it can't open, like one that's locked or whose permissions deny it. When
+    that's `directory`, it raises an error, but when it's a part of `path`, it can't be
+    `directory`, so `path` is judged by its parents.
+
+    A network path that can't be reached raises an error when `directory` exists, even
+    though Windows reports it as missing.
+
+    Args:
+        path: Path to find within `directory`.
+        directory: Path to the directory.
+
+    Returns:
+        The path of `path` relative to `directory`, `PurePath(".")` when `path` is
+        `directory` itself, or `None` when `path` is neither `directory` nor within it,
+        or when `directory` doesn't exist.
+
+    Raises:
+        OSError:
+            - When a part of `path` or `directory` can't be read — for example, when
+              permissions deny it, symlinks loop, a `..` steps up from a file on Linux
+              or macOS, or when the path is relative and the working directory is gone.
+              A safety check that can't be made must fail rather than pass.
+            - When `path` or `directory` ends with a separator or `.`, which says it's
+              a directory, but leads to a file.
+            - When `path` or `directory` is empty, which names nothing.
+            - When `path` or `directory` contains a null character.
+            - When `directory` is a file.
+            - When `directory` exists but its identity can't be read, like when Windows
+              can't open it.
+
+            Errors in resolving `path` are raised even when `directory` doesn't exist.
+            The error names `path` or `directory` as it was given.
+
+    Examples:
+        Given this directory, where `latest` is a symlink to `v2` and `shared` is a
+        symlink to `/assets`:
+
+        ```text
+        /docs
+        ├── latest -> v2
+        ├── shared -> /assets
+        └── v2
+            └── guide.md
+        ```
+
+        A path within the directory, whether or not it exists, is relative to it:
+
+        ```python
+        relative_within(
+            "/docs/latest/guide.md",
+            "/docs/v2",
+        )
+        # PurePath("guide.md")
+
+        relative_within(
+            "/docs/v2/drafts/intro.md",
+            "/docs/v2",
+        )
+        # PurePath("drafts/intro.md")
+        ```
+
+        A path that leads out of the directory isn't within it:
+
+        ```python
+        relative_within(
+            "/docs/shared/logo.svg",
+            "/docs",
+        )
+        # None
+        ```
+    """
+    # Resolve before looking for the directory, so that a path that can't be resolved
+    # raises even when the directory doesn't exist.
+    #
+    # `resolve` can keep the caller's spelling, which a case- or normalisation-
+    # insensitive file system can store differently, so find the directory by identity
+    # rather than by name.
+    resolved = resolve(path)
+
+    directory_status = status(directory)
+
+    if directory_status is None:
+        # The paths that don't exist have no identity either, so they mustn't be
+        # compared with it.
+        return None
+
+    if not S_ISDIR(directory_status.st_mode):
+        raise _not_a_directory_error.not_a_directory(directory)
+
+    directory_identity = identity_of_status(directory_status)
+
+    if directory_identity is None:
+        raise _permission_error.unreadable_identity_error(directory)
+
+    # The resolved path had no symlinks, so one that's appeared since mustn't be
+    # followed out of the path that was checked.
+    #
+    # Reading a part's status follows any symlink in the parts before it, so walk down
+    # from the root, and stop at the first part that doesn't resolve to itself any more.
+    # The parts after it, if any, aren't on the path that was checked.
+    #
+    # A part that resolved to itself, like a folder that Windows mounts a volume in,
+    # still does, so it doesn't stop the walk.
+    parts: list[tuple[Path, stat_result]] = []
+
+    for part in reversed((resolved, *resolved.parents)):
+        part_status = status_of_resolved(
+            part,
+            path,
+            follow_symlinks=False,
+        )
+
+        if part_status is None:
+            break
+
+        parts.append((part, part_status))
+
+        if not _resolves_to_itself(part, path):
+            break
+
+    # Compare from the end, so the nearest part that's the directory wins.
+    for part, part_status in reversed(parts):
+        # The directory's identity could be read, so a part whose identity can't be
+        # read, `None`, isn't the directory, and never compares as equal to it.
+        part_identity = identity_of_status(part_status)
+
+        if part_identity == directory_identity:
+            return PurePath(resolved.relative_to(part))
+
+    return None