pathapi 0.1.0__py3-none-any.whl

pathapi/protocols/links.py

@@ -0,0 +1,135 @@
+"""Symbolic links."""
+
+from __future__ import annotations
+
+import typing as _ty
+
+from .. import _stubs
+from .fs import Stat
+from .tree import Remove
+
+__all__ = ["Hardlink", "Readlink", "Symlink"]
+
+
+class Readlink(Stat, _ty.Protocol):
+    """Reading a symbolic link: `readlink()` is the primitive. A read-only
+    backend (an archive) has this and not `Symlink`."""
+
+    __slots__ = ()
+
+    __primitives__: _ty.ClassVar[tuple[object, ...]] = ("readlink",)
+
+    @_stubs.primitive
+    def readlink(self) -> _ty.Self:
+        """The path this symbolic link points to, as a path of this class whose
+        `str()` and `as_posix()` are the link text, unresolved (a stub:
+        `NotImplementedError`). `OSError(EINVAL)` where the path is not a
+        link."""
+        return _stubs._unimplemented("readlink")
+
+
+class Symlink(Remove, _ty.Protocol):
+    """Making a symbolic link: `_symlink_to()` is the primitive;
+    `symlink_to()` normalizes its target and honours `force=`."""
+
+    __slots__ = ()
+
+    __primitives__: _ty.ClassVar[tuple[object, ...]] = (("_symlink_to", "symlink_to"),)
+
+    @_stubs.primitive
+    def _symlink_to(
+        self, target: "_ty.Self", target_is_directory: bool = False
+    ) -> None:
+        """Create a symlink at this path pointing at `target`.
+
+        The backend primitive behind `symlink_to()`, in the same shape as
+        `_mkdir`/`_open`: implement only this, and the generic conveniences
+        (`force=`) come for free. `target` has already been normalized to a
+        path object of this class by `symlink_to()` -- accepting `str` and
+        turning it into a path is the wrapper's job, not the primitive's.
+
+        Implementations take the raw target string from the path object the
+        way their own backend needs it (the path of the request for wire
+        protocols, `os.fspath()`/`as_posix()` locally); it never carries a scheme or
+        host prefix, and a relative target stays relative.
+        """
+        return _stubs._unimplemented("_symlink_to")
+
+    def _symlink_target(self, target: "_ty.Self | str") -> "_ty.Self":
+        """Normalize a `symlink_to()` target argument to a path object.
+
+        A `str` target is the **literal link target** -- whatever it says
+        is what gets stored, verbatim and unresolved, exactly as
+        `pathlib.Path.symlink_to()` does. The default builds it with
+        `with_segments()`, which keeps per-instance state (a `MemPath`'s
+        backend) but normalizes the text as this class parses a path;
+        override it wherever that would reinterpret the string instead of
+        taking it literally (`LocalPath` hands it on untouched, and a class
+        for URI references must not parse it as one).
+        """
+        return self.with_segments(target) if isinstance(target, str) else target
+
+    def symlink_to(
+        self,
+        target: "_ty.Self | str",
+        target_is_directory: bool = False,
+        *,
+        force: bool = False,
+    ) -> None:
+        """Make this path a symlink pointing to `target`.
+
+        Signature-compatible with `pathlib.Path.symlink_to()`; `force` is a
+        pathapi extension (see `docs/divergences.md`).
+
+        With `force=True`, an existing entry at *this* path is removed
+        first. No filesystem or transport offers an atomic "replace a
+        symlink" operation, so this is an unlink-then-symlink sequence and
+        is therefore **not** atomic: between the two steps the path does not
+        exist, and a concurrent writer can win the race. It is a
+        convenience, not a locking primitive.
+
+        Only a non-directory entry is removed -- an existing *directory* at
+        the link path is left alone and the underlying `FileExistsError`
+        (or the backend's equivalent) propagates. Silently deleting a
+        directory tree is never what `force=` on a symlink call is asking
+        for.
+        """
+        # Through `_symlink_target()`, not `type(self)(target)`: for a URI-backed path
+        # the constructor re-parses the string as URI syntax, cutting the target at "?"
+        # or "#" and percent-decoding it.
+        target = self._symlink_target(target)
+        if force:
+            try:
+                self.unlink(missing_ok=True)
+            except (IsADirectoryError, PermissionError, OSError) as error:
+                # A directory at the link path (IsADirectoryError on POSIX; PermissionError or
+                # an OSError on Windows and remote backends) is not removed by force=: the
+                # symlink attempt below raises the error that describes the conflict.
+                if not self.is_dir():
+                    raise error
+        return self._symlink_to(target, target_is_directory)
+
+
+class Hardlink(Stat, _ty.Protocol):
+    """Making a path a second name for an existing file: `_hardlink_to()` is
+    the primitive; `hardlink_to()` turns a `str` target into a path of this
+    backend."""
+
+    __slots__ = ()
+
+    __primitives__: _ty.ClassVar[tuple[object, ...]] = (
+        ("_hardlink_to", "hardlink_to"),
+    )
+
+    @_stubs.primitive
+    def _hardlink_to(self, target: _ty.Self) -> None:
+        """Backend primitive: make this path a hard link to `target`, a path
+        of this class (a stub: `NotImplementedError`)."""
+        return _stubs._unimplemented("_hardlink_to")
+
+    def hardlink_to(self, target: "_ty.Self | str") -> None:
+        """Make this path a hard link to `target` (pathlib 3.10 parity). A
+        `str` is a path on this backend."""
+        if isinstance(target, str):
+            target = self.with_segments(target)
+        return self._hardlink_to(target)

pathapi/protocols/pure.py

@@ -0,0 +1,31 @@
+"""What the helpers that walk, match and sync need from a pure path."""
+
+from __future__ import annotations
+
+import typing as _ty
+
+__all__ = ["Named"]
+
+
+class Named(_ty.Protocol):
+    """The pure half of a path as `glob`, `walk` and `sync` read it: a name,
+    the segments it is made of, a parent, and the means of building and
+    joining paths of the same kind. Structural only: `Pathname` and
+    `pathlib.PurePath` satisfy it without naming it, and nothing subclasses it."""
+
+    @property
+    def name(self) -> str: ...
+
+    @property
+    def segments(self) -> _ty.Sequence[str]: ...
+
+    @property
+    def parent(self) -> _ty.Self: ...
+
+    def with_segments(self, *segments: str) -> _ty.Self: ...
+
+    def joinpath(self, *args: "str | _ty.Self") -> _ty.Self: ...
+
+    def __truediv__(self, key: "str | _ty.Self") -> _ty.Self: ...
+
+    def as_posix(self) -> str: ...

pathapi/protocols/resolve.py

@@ -0,0 +1,97 @@
+"""Making a path absolute and following the links on its way."""
+
+from __future__ import annotations
+
+import errno as _errno
+import stat as _stat
+import sys as _sys
+import typing as _ty
+
+from .. import _stubs
+from ._support import supports
+from .links import Readlink
+
+__all__ = ["Resolve"]
+
+#: Links followed in one `resolve()` before it reports a loop.
+_MAX_LINKS = 40
+
+
+class Resolve(Readlink, _ty.Protocol):
+    """`absolute()` and `resolve()`. `_cwd()` is the primitive: the directory
+    a relative path is relative to. `resolve()` follows links through
+    `readlink()` where the class has it and is lexical otherwise."""
+
+    __slots__ = ()
+
+    __primitives__: _ty.ClassVar[tuple[object, ...]] = (("_cwd", "absolute"),)
+
+    @_stubs.primitive
+    def _cwd(self) -> _ty.Self:
+        """The directory a relative path is relative to, as a path of this
+        class (a stub: `NotImplementedError`)."""
+        return _stubs._unimplemented("_cwd")
+
+    def absolute(self) -> _ty.Self:
+        """This path when it is absolute, else `_cwd()` joined with it."""
+        if self.is_absolute():
+            return self
+        return self._cwd().joinpath(self)
+
+    def resolve(self, strict: bool = False) -> _ty.Self:
+        """The absolute path with `..` applied and every link replaced by what
+        `readlink()` says, at most 40 of them. `strict=True` raises
+        `FileNotFoundError` for a component that is missing; otherwise the
+        rest of the names are kept as they are. A link loop raises what
+        `pathlib` raises on this interpreter: `RuntimeError` before 3.13,
+        `OSError(ELOOP)` from 3.13 when `strict` (otherwise the looping link
+        is kept)."""
+        path = self.absolute()
+        links = supports(self, Readlink)
+        root = path.with_segments(path.anchor or "/")
+        resolved = root
+        pending = [name for name in path.segments if name][::-1]
+        followed = 0
+        while pending:
+            name = pending.pop()
+            if name == ".":
+                continue
+            if name == "..":
+                resolved = resolved.parent
+                continue
+            candidate = resolved.joinpath(name)
+            if not links:
+                if strict:
+                    candidate.stat()
+                resolved = candidate
+                continue
+            try:
+                mode = candidate.stat(follow_symlinks=False).st_mode
+            except OSError:
+                if strict:
+                    raise
+                resolved = candidate
+                continue
+            if not _stat.S_ISLNK(mode):
+                resolved = candidate
+                continue
+            followed += 1
+            if followed > _MAX_LINKS:
+                if _sys.version_info < (3, 13):
+                    raise RuntimeError(f"Symlink loop from {candidate!r}")
+                if strict:
+                    raise OSError(
+                        _errno.ELOOP,
+                        "Too many levels of symbolic links",
+                        str(candidate),
+                    )
+                resolved = candidate
+                continue
+            target = candidate.readlink()
+            text = getattr(target, "path", None)
+            if not isinstance(text, str):
+                text = target.as_posix()
+            if text.startswith("/"):
+                resolved = root
+            pending.extend(part for part in reversed(text.split("/")) if part)
+        return resolved