rootle 1.1.0__tar.gz → 1.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rootle
-Version: 1.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/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.1.0 → rootle-1.2.0}/src/rootle/exceptions/_os_error.py

@@ -1,6 +1,18 @@
+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

{rootle-1.1.0 → rootle-1.2.0}/src/rootle/identity.py

@@ -48,6 +48,7 @@ def identity(path: PathLike[str] | str) -> Identity | None:
             - 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.
 

{rootle-1.1.0 → rootle-1.2.0}/src/rootle/relative_within.py

@@ -100,6 +100,7 @@ def relative_within(
             - 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.

{rootle-1.1.0 → rootle-1.2.0}/src/rootle/resolve.py

@@ -51,6 +51,7 @@ def resolve(path: PathLike[str] | str) -> Path:
             - 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.
 
             The error names `path` as it was given.
 
@@ -78,16 +79,22 @@ def resolve(path: PathLike[str] | str) -> Path:
         # Path("/docs/v2/guide.md/intro.md")
         ```
     """
+    name = fspath(path)
+
     # `Path` reads an empty path as `.`, the working directory, but it names nothing,
     # like `os.stat` says.
-    if not fspath(path):
+    if not name:
         raise FileNotFoundError(
             ENOENT,
             strerror(ENOENT),
-            fspath(path),
+            name,
         )
 
-    current = Path(path)
+    # No path can contain a null character.
+    if "\0" in name:
+        raise _os_error.null_character(name)
+
+    current = Path(name)
     tail: list[str] = []
 
     while True:

{rootle-1.1.0 → rootle-1.2.0}/src/rootle/status.py

@@ -1,5 +1,5 @@
 from contextlib import suppress
-from os import PathLike, stat, stat_result
+from os import PathLike, fspath, stat, stat_result
 from os.path import isabs
 
 from ._status_of_resolved import status_of_resolved
@@ -39,6 +39,7 @@ def status(path: PathLike[str] | str) -> stat_result | None:
             - 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.
 
             The error names `path` as it was given.
 
@@ -68,10 +69,12 @@ def status(path: PathLike[str] | str) -> stat_result | None:
     """
     # A path that ends like a directory is left to `resolve`, which raises when it
     # leads to a file, because Windows' `stat` drops a trailing separator or `.`.
-
-    # So is a relative path, because `stat` can still find `.` and `..` after the
+    #
+    # ...and so is a relative path, because `stat` can still find `.` and `..` after the
     # working directory is gone, and that mustn't pass.
-    if isabs(path) and not ends_like_directory(path):
+    #
+    # ...and so is a path that holds a null character.
+    if isabs(path) and not ends_like_directory(path) and "\0" not in fspath(path):
         # A path that can be `stat`-ed already names the file that it resolves to, so
         # it needn't be resolved. An error is left to the route below to describe.
         with suppress(OSError):

rootle-1.2.0/src/rootle/testing/__init__.py

@@ -0,0 +1,11 @@
+from .can_chmod_deny_listing import can_chmod_deny_listing
+from .can_chmod_deny_search import can_chmod_deny_search
+from .can_chmod_deny_writing import can_chmod_deny_writing
+from .is_treated_as_same_name import is_treated_as_same_name
+
+__all__ = [
+    "can_chmod_deny_listing",
+    "can_chmod_deny_search",
+    "can_chmod_deny_writing",
+    "is_treated_as_same_name",
+]

rootle-1.2.0/src/rootle/testing/can_chmod_deny_listing.py

@@ -0,0 +1,62 @@
+from os import listdir
+from pathlib import Path
+from shutil import rmtree
+from stat import S_IRWXU, S_IWUSR, S_IXUSR
+from tempfile import mkdtemp
+
+
+def can_chmod_deny_listing(directory: Path) -> bool:
+    """
+    Check whether removing a directory's "read" (`r`) permission with
+    [`chmod`][os.chmod] denies it to this process.
+
+    The read permission is required by listing a directory, like with
+    [`listdir`][os.listdir].
+
+    This function only checks reading, not search (opening or [`stat`][os.stat]-ing a
+    file within the directory) or writing (creating, renaming or deleting files within
+    it).
+
+    **Linux & macOS:** `False` for root, for a process that can override permissions
+    (like one with Linux's `CAP_DAC_OVERRIDE` or `CAP_DAC_READ_SEARCH` capability), and
+    on file systems that ignore permissions, like FAT.
+
+    **Windows:** Always `False`, because `chmod` only sets the read-only flag.
+
+    Args:
+        directory: Path to the directory to interrogate.
+
+    Returns:
+        `True` when `chmod(0o300)` denies this process the read permission on a
+        directory, otherwise `False`.
+
+    Raises:
+        OSError: When the permission probe cannot be written or deleted.
+
+    Examples:
+        ```python
+        def test_raises_when_listing_denied(tmp_path: Path) -> None:
+            if not can_chmod_deny_listing(tmp_path):
+                skip("chmod can't deny listing here")
+
+            ...
+        ```
+    """
+    probe_dir = Path(mkdtemp(dir=directory))
+
+    try:
+        probe_dir.chmod(S_IWUSR | S_IXUSR)
+
+        try:
+            listdir(probe_dir)
+
+        except PermissionError:
+            return True
+
+        finally:
+            probe_dir.chmod(S_IRWXU)
+
+        return False
+
+    finally:
+        rmtree(probe_dir)

{rootle-1.1.0 → rootle-1.2.0}/src/rootle/testing/can_chmod_deny_search.py

@@ -52,8 +52,10 @@ def can_chmod_deny_search(directory: Path) -> bool:
         except PermissionError:
             return True
 
+        finally:
+            probe_dir.chmod(S_IRWXU)
+
         return False
 
     finally:
-        probe_dir.chmod(S_IRWXU)
         rmtree(probe_dir)

rootle-1.2.0/src/rootle/testing/can_chmod_deny_writing.py

@@ -0,0 +1,71 @@
+from pathlib import Path
+from shutil import rmtree
+from stat import S_IMODE, S_IRGRP, S_IROTH, S_IRUSR, S_IRWXU, S_IXGRP, S_IXOTH, S_IXUSR
+from tempfile import mkdtemp
+
+
+def can_chmod_deny_writing(directory: Path) -> bool:
+    """
+    Check whether removing a directory's "write" (`w`) permission with
+    [`chmod`][os.chmod] denies it to this process.
+
+    The write permission is required by creating, renaming or deleting a file within a
+    directory.
+
+    This function only checks writing, not reading (listing the directory) or search
+    (opening or [`stat`][os.stat]-ing a file within it).
+
+    **Linux & macOS:** `False` for root, for a process that can override permissions
+    (like one with Linux's `CAP_DAC_OVERRIDE` capability), and on file systems that
+    ignore permissions, like FAT.
+
+    **Windows:** Always `False`, because `chmod` only sets the read-only flag, which
+    Windows doesn't honour on directories.
+
+    Args:
+        directory: Path to the directory to interrogate.
+
+    Returns:
+        `True` when `chmod(0o555)` denies this process the write permission on a
+        directory, otherwise `False`.
+
+    Raises:
+        OSError: When the permission probe cannot be written or deleted.
+
+    Examples:
+        ```python
+        def test_raises_when_writing_denied(tmp_path: Path) -> None:
+            if not can_chmod_deny_writing(tmp_path):
+                skip("chmod can't deny writing here")
+
+            ...
+        ```
+    """
+    probe_dir = Path(mkdtemp(dir=directory))
+
+    try:
+        original_mode = S_IMODE(probe_dir.stat().st_mode)
+
+        # chmod(0o555), which keeps every read and search bit rather than only the
+        # owner's.
+        #
+        # Linux's FAT driver silently ignores a chmod that removes a read or search bit
+        # that its mount options allow, but with the `rodir` option it honours one that
+        # removes every write bit and nothing else.
+        probe_dir.chmod(S_IRUSR | S_IXUSR | S_IRGRP | S_IXGRP | S_IROTH | S_IXOTH)
+
+        try:
+            (probe_dir / "file").touch()
+
+        except PermissionError:
+            return True
+
+        finally:
+            # The original mode plus every owner permission, which rmtree needs even if
+            # the umask left some out.
+            probe_dir.chmod(original_mode | S_IRWXU)
+
+        return False
+
+    finally:
+        rmtree(probe_dir)

rootle-1.2.0/src/rootle/testing/is_treated_as_same_name.py

@@ -0,0 +1,82 @@
+from pathlib import Path, PurePath
+from tempfile import mkdtemp
+
+
+def is_treated_as_same_name(directory: Path, name: str, alt_name: str) -> bool:
+    """
+    Check whether the file system treats two spellings as the same name.
+
+    For example:
+
+    - `README.md` and `readme.md`
+    - the NFC and NFD forms of `café.md`.
+
+    Some file systems choose for each directory how to compare names, and a new
+    directory takes its parent's choice. The probe is made in a new directory within
+    `directory`, so the answer holds for `directory` and for new directories made
+    within it.
+
+    File systems that ignore case or normalisation don't all fold the same characters,
+    so probe with the names that a test uses.
+
+    **Linux:** Usually `False` for a different case or Unicode normalisation, because
+    most file systems compare names byte for byte. FAT, though, ignores the case of
+    ASCII letters by default, and an ext4 directory with case folding turned on ignores
+    both case and normalisation.
+
+    **macOS:** `True` for a different case unless APFS or HFS+ was formatted as
+    case-sensitive, and for a different Unicode normalisation on APFS, HFS+, FAT and
+    exFAT.
+
+    **Windows:** `True` for a different case unless the directory is case-sensitive,
+    but `False` for a different Unicode normalisation, because Windows compares names
+    without normalising them.
+
+    Args:
+        directory: Path to the directory to interrogate.
+        name: Name of the file to create.
+        alt_name: Another spelling of `name` to look for.
+
+    Returns:
+        `True` when `alt_name` names the file created as `name`, otherwise `False`.
+
+    Raises:
+        OSError: When the probe cannot be written or deleted.
+        ValueError: When `name` or `alt_name` is or contains a directory.
+
+    Examples:
+        ```python
+        def test_identity_by_different_case(tmp_path: Path) -> None:
+            if not is_treated_as_same_name(tmp_path, "readme.md", "README.md"):
+                skip("This file system doesn't treat 'README.md' as 'readme.md'")
+
+            ...
+        ```
+    """
+    for given in (name, alt_name):
+        if given in ("", ".", "..") or PurePath(given).name != given:
+            raise ValueError(f"{given!r} is or contains a directory")
+
+    probe_dir = Path(mkdtemp(dir=directory))
+    probe_file = probe_dir / name
+    alt_file = probe_dir / alt_name
+
+    try:
+        probe_file.touch()
+
+        try:
+            # On Windows, a name can lead somewhere other than the probe's file (like
+            # `NUL` to the null device) so check that `alt_name` names the probe's file
+            # — not only that something exists there.
+            #
+            # `exists()` goes first because `samefile()` raises for a name that's
+            # missing or that Windows rejects.
+            return alt_file.exists() and alt_file.samefile(probe_file)
+
+        finally:
+            probe_file.unlink()
+
+    finally:
+        # Removing the file and then the directory, rather than the whole tree, doesn't
+        # need the permission to list the directory, which the umask can leave out.
+        probe_dir.rmdir()

{rootle-1.1.0 → rootle-1.2.0}/tests/marks.py

@@ -1,7 +1,12 @@
+import os
 import sys
 
 from pytest import mark
 
+IS_ROOT = sys.platform != "win32" and os.geteuid() == 0
+"""Whether the tests are running as root on Linux or macOS."""
+
+
 posix_only = mark.skipif(
     sys.platform == "win32",
     reason="POSIX-only behaviour",

rootle-1.2.0/tests/test_can_chmod_deny_listing.py

@@ -0,0 +1,112 @@
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+from pytest import mark, raises
+
+from rootle.testing import can_chmod_deny_listing
+from tests.marks import IS_ROOT, windows_only
+
+
+def test_can_chmod_deny_listing_cleans_up(tmp_path: Path) -> None:
+    """Assert that `can_chmod_deny_listing` removes everything that it creates."""
+    can_chmod_deny_listing(tmp_path)
+
+    remaining = list(tmp_path.iterdir())
+
+    assert remaining == []
+
+
+def test_can_chmod_deny_listing_cleans_up_when_chmod_fails(tmp_path: Path) -> None:
+    """
+    Assert that `can_chmod_deny_listing` removes the probe when it isn't permitted to
+    change the probe's permissions, like on a file system owned by another user.
+    """
+    with (
+        patch.object(Path, "chmod", side_effect=PermissionError),
+        raises(PermissionError),
+    ):
+        can_chmod_deny_listing(tmp_path)
+
+    remaining = list(tmp_path.iterdir())
+
+    assert remaining == []
+
+
+@mark.skipif(
+    not IS_ROOT,
+    reason="Expects to run as root on POSIX, which ignores read permission",
+)
+def test_can_chmod_deny_listing_is_false_for_root_on_posix(tmp_path: Path) -> None:
+    """Assert that `can_chmod_deny_listing` is `False` for root on Linux and macOS."""
+    denied = can_chmod_deny_listing(tmp_path)
+
+    assert denied is False
+
+
+@windows_only
+def test_can_chmod_deny_listing_is_false_on_windows(tmp_path: Path) -> None:
+    """
+    Assert that `can_chmod_deny_listing` is `False` on Windows, where `chmod` only sets
+    the read-only flag.
+    """
+    denied = can_chmod_deny_listing(tmp_path)
+
+    assert denied is False
+
+
+def test_can_chmod_deny_listing_is_false_when_chmod_is_ignored(tmp_path: Path) -> None:
+    """
+    Assert that `can_chmod_deny_listing` is `False` when `chmod` doesn't take effect,
+    like on a file system that ignores permissions.
+    """
+    with patch.object(Path, "chmod"):
+        denied = can_chmod_deny_listing(tmp_path)
+
+    assert denied is False
+
+
+def test_can_chmod_deny_listing_is_true_when_chmod_denies_listing(
+    tmp_path: Path,
+) -> None:
+    """
+    Assert that `can_chmod_deny_listing` is `True` when `chmod` denies the read
+    permission.
+    """
+    with (
+        patch.object(Path, "chmod"),
+        patch(
+            "rootle.testing.can_chmod_deny_listing.listdir",
+            side_effect=PermissionError,
+        ),
+    ):
+        denied = can_chmod_deny_listing(tmp_path)
+
+    assert denied is True
+
+
+@mark.skipif(
+    sys.platform == "win32" or IS_ROOT,
+    reason="chmod can't deny read permission on Windows, or to root",
+)
+def test_can_chmod_deny_listing_on_posix(tmp_path: Path) -> None:
+    """
+    Assert that `can_chmod_deny_listing` is `True` on Linux and macOS for a process
+    other than root.
+    """
+    denied = can_chmod_deny_listing(tmp_path)
+
+    assert denied is True
+
+
+def test_can_chmod_deny_listing_raises_when_directory_does_not_exist(
+    tmp_path: Path,
+) -> None:
+    """
+    Assert that `can_chmod_deny_listing` raises `FileNotFoundError` when the directory
+    to probe doesn't exist.
+    """
+    missing = tmp_path / "missing"
+
+    with raises(FileNotFoundError):
+        can_chmod_deny_listing(missing)

{rootle-1.1.0 → rootle-1.2.0}/tests/test_can_chmod_deny_search.py

@@ -1,14 +1,11 @@
-import os
 import sys
 from pathlib import Path
 from unittest.mock import patch
 
-from pytest import mark
+from pytest import mark, raises
 
 from rootle.testing import can_chmod_deny_search
-from tests.marks import windows_only
-
-IS_ROOT = sys.platform != "win32" and os.geteuid() == 0
+from tests.marks import IS_ROOT, windows_only
 
 
 def test_can_chmod_deny_search_cleans_up(tmp_path: Path) -> None:
@@ -20,6 +17,22 @@ def test_can_chmod_deny_search_cleans_up(tmp_path: Path) -> None:
     assert remaining == []
 
 
+def test_can_chmod_deny_search_cleans_up_when_chmod_fails(tmp_path: Path) -> None:
+    """
+    Assert that `can_chmod_deny_search` removes the probe when it isn't permitted to
+    change the probe's permissions, like on a file system owned by another user.
+    """
+    with (
+        patch.object(Path, "chmod", side_effect=PermissionError),
+        raises(PermissionError),
+    ):
+        can_chmod_deny_search(tmp_path)
+
+    remaining = list(tmp_path.iterdir())
+
+    assert remaining == []
+
+
 @mark.skipif(
     not IS_ROOT,
     reason="Expects to run as root on POSIX, which ignores search permission",
@@ -60,7 +73,10 @@ def test_can_chmod_deny_search_is_true_when_chmod_denies_search(
     Assert that `can_chmod_deny_search` is `True` when `chmod` denies the search
     permission.
     """
-    with patch.object(Path, "stat", side_effect=PermissionError):
+    with (
+        patch.object(Path, "chmod"),
+        patch.object(Path, "stat", side_effect=PermissionError),
+    ):
         denied = can_chmod_deny_search(tmp_path)
 
     assert denied is True
@@ -78,3 +94,16 @@ def test_can_chmod_deny_search_on_posix(tmp_path: Path) -> None:
     denied = can_chmod_deny_search(tmp_path)
 
     assert denied is True
+
+
+def test_can_chmod_deny_search_raises_when_directory_does_not_exist(
+    tmp_path: Path,
+) -> None:
+    """
+    Assert that `can_chmod_deny_search` raises `FileNotFoundError` when the directory
+    to probe doesn't exist.
+    """
+    missing = tmp_path / "missing"
+
+    with raises(FileNotFoundError):
+        can_chmod_deny_search(missing)