pathapi 0.1.0__py3-none-any.whl

pathapi/protocols/_relation.py

@@ -0,0 +1,191 @@
+"""How a target stands to a source: the same entry, another name, outside or inside."""
+
+from __future__ import annotations
+
+import errno as _errno
+import os as _os
+import pathlib as _pathlib
+import typing as _ty
+
+if _ty.TYPE_CHECKING:
+    from ..path import Path
+    from .transfer import _Held
+
+
+# How `move()` and `copy()` find a target standing to the source (`_relation`).
+_SAME = "same"  # one directory entry, spelled differently
+_OTHER = "other"  # another name of the same file (a hard link, a link to it)
+_OUTER = "outer"  # the target is a directory that holds the source
+_INNER = "inner"  # the target lies inside the source
+
+
+def _local_file(path) -> "_pathlib.Path | None":
+    """The `pathlib.Path` through which `path` is a file of this machine, or
+    None: a `LocalPath`, a stdlib path, or a path holding one as `filepath`
+    (a `file:` URI class)."""
+    if isinstance(path, _pathlib.Path):
+        return path
+    try:
+        local = getattr(path, "filepath", None)
+    except Exception:
+        return None
+    return local if isinstance(local, _pathlib.Path) else None
+
+
+def _location(path: "_pathlib.Path", follow: bool) -> str:
+    """Where `path` points: absolute, with every symlink of its directory part
+    resolved and, when `follow`, the final component's too."""
+    text = _os.path.join(_os.getcwd(), _os.fspath(path))
+    head, tail = _os.path.split(text)
+    if follow or tail in ("", ".", ".."):
+        return _os.path.realpath(text)
+    return _os.path.join(_os.path.realpath(head), tail)
+
+
+def _inside(outer: str, inner: str) -> bool:
+    """Whether `inner` lies strictly below `outer` (both `normcase`d)."""
+    if outer == inner:
+        return False
+    try:
+        return _os.path.commonpath([outer, inner]) == outer
+    except ValueError:
+        return False
+
+
+def _is_one_entry(mine: str, theirs: str) -> bool:
+    """Whether two locations of one file are a single directory entry under
+    two spellings (a case or short-name alias) rather than two names of it
+    (hard links, which a directory lists both). Unsure counts as one entry:
+    that removes nothing."""
+    (head, name), (other_head, other_name) = (
+        _os.path.split(mine),
+        _os.path.split(theirs),
+    )
+    try:
+        if not _os.path.samefile(head, other_head):
+            return False
+        listed = set(_os.listdir(head))
+    except OSError:
+        return True
+    return not (name != other_name and name in listed and other_name in listed)
+
+
+def _local_relation(mine, theirs, follow: bool) -> "str | None":
+    """`_relation()` for two files of this machine, decided by where each
+    really is and, failing that, by their identity (`os.path.samefile`)."""
+    try:
+        at, there = _location(mine, follow), _location(theirs, follow)
+        normal, other = _os.path.normcase(at), _os.path.normcase(there)
+        if normal == other:
+            return _SAME
+        if _inside(other, normal):
+            return _OUTER
+        if _inside(normal, other):
+            return _INNER
+        if not _os.path.samefile(mine, theirs):
+            return None
+    except (OSError, ValueError):
+        return None
+    return _SAME if _is_one_entry(at, there) else _OTHER
+
+
+def _relation(
+    src: Path,
+    target: Path,
+    *,
+    follow: bool,
+    identity: bool = True,
+    held: "_Held | None" = None,
+) -> "str | None":
+    """How `target` stands to `src`: `_SAME`, `_OTHER`, `_OUTER`, `_INNER`,
+    or None when they are unrelated or this cannot tell.
+
+    Two files of this machine are compared by where they really are, whatever
+    their classes; a type that answers `_node_key()` is compared by that;
+    anything else only between two paths of one type that
+    `_same_filesystem()` places together, by `samefile()` where `stat()`
+    carries `st_dev`/`st_ino` (when `identity`; it costs a stat of each) and
+    by `==` otherwise. `follow` says whether a final symlink is looked
+    through (a copy reads it) or is the entry itself (a move renames it).
+    `held` is the stats of `src` and `target` the caller already took, so
+    `samefile()` does not take them again."""
+    mine, theirs = _local_file(src), _local_file(target)
+    if mine is not None and theirs is not None:
+        return _local_relation(mine, theirs, follow)
+    try:
+        keys = (src._node_key(), target._node_key())
+    except Exception:
+        keys = (None, None)
+    if None not in keys:
+        (space, names), (other_space, other_names) = keys
+        if space is not other_space:
+            return None
+        if names == other_names:
+            return _SAME
+        if names[: len(other_names)] == other_names:
+            return _OUTER
+        if other_names[: len(names)] == names:
+            return _INNER
+        return None
+    if type(src) is not type(target):
+        return None
+    if identity:
+        try:
+            if src.samefile(target) if held is None else held.same_file(src, target):
+                return _SAME
+        except (NotImplementedError, OSError, TypeError, ValueError):
+            pass
+    if not src._same_filesystem(target):
+        return None
+    try:
+        if src == target:
+            return _SAME
+        if target.is_relative_to(src):
+            return _INNER
+        if src.is_relative_to(target):
+            return _OUTER
+    except Exception:
+        pass
+    return None
+
+
+def contains(src: Path, target: Path) -> bool:
+    """Whether `target` is `src` or lies inside it (pathlib 3.14's copy()
+    refuses both), looking through symlinks. Paths `_same_filesystem()`
+    reports in different namespaces are never nested."""
+    return _relation(src, target, follow=True, identity=False) in (
+        _SAME,
+        _OTHER,
+        _INNER,
+    )
+
+
+def _same_file(src: Path, target: Path, *, identity: bool = True) -> bool:
+    """Whether `src` and `target` name the same file, looking through
+    symlinks (see `_relation`, and its `identity`)."""
+    mine, theirs = _local_file(src), _local_file(target)
+    if mine is not None and theirs is not None:
+        # The cheap form of `_local_relation()`: copy() asks this once per
+        # file, and only identity matters to it.
+        try:
+            return _os.path.samefile(mine, theirs)
+        except (OSError, ValueError):
+            pass
+        try:
+            return _os.path.normcase(_os.path.abspath(mine)) == _os.path.normcase(
+                _os.path.abspath(theirs)
+            )
+        except (OSError, ValueError):
+            return False
+    return _relation(src, target, follow=True, identity=identity) in (_SAME, _OTHER)
+
+
+def _drop_second_name(src: Path, src_stat, target: Path, target_stat) -> Path:
+    """`move()` between two names of one file: the target name already holds
+    the content, so only the source name goes. A link to the file, or a
+    directory reachable twice, is refused: removing either name would leave
+    the other pointing at nothing."""
+    if src_stat.is_symlink() or target_stat.is_symlink() or src_stat.is_dir():
+        raise OSError(_errno.EINVAL, "Source and target are the same file", str(target))
+    src.unlink()
+    return target

pathapi/protocols/_removal.py

@@ -0,0 +1,69 @@
+"""Helpers of listing and removal: the child listing, junctions and follow policies."""
+
+from __future__ import annotations
+
+import contextlib as _contextlib
+import typing as _ty
+
+from .._filestat import FileStat
+
+if _ty.TYPE_CHECKING:
+    from ..path import Path
+
+
+def _write_batch_of(path) -> "_ty.ContextManager[object]":
+    """`path._write_batch()`, where a path without the hook (a stdlib path)
+    gets a block that does nothing."""
+    hook = getattr(path, "_write_batch", None)
+    return hook() if callable(hook) else _contextlib.nullcontext()
+
+
+def _is_junction(path: "Path") -> bool:
+    """`path.is_junction()`, where a class that cannot answer says no."""
+    try:
+        return bool(path.is_junction())
+    except (NotImplementedError, OSError, ValueError):
+        return False
+
+
+def _follow_policy(policy, path: "Path") -> str:
+    """Resolve a `follow_symlinks=`/`follow_binds=` value for `path`.
+
+    `False` (the default) means "remove the entry itself, never what is
+    behind it" -- `rm -r` semantics; `True` means "remove what is behind
+    it"; `None` means "leave it alone entirely". A callable is asked per
+    entry (`policy(path)`) and returns one of those three, so one tree can
+    keep one mount and follow another.
+
+    Returns the internal name: "rm", "follow" or "ignore". An answer that is
+    none of the three raises `_InvalidPolicy`, which `rm()` never hands to
+    its `ignore_error`.
+    """
+    if callable(policy):
+        policy = policy(path)
+    if policy is None:
+        return "ignore"
+    if policy is True:
+        return "follow"
+    if policy is False:
+        return "rm"
+    raise _InvalidPolicy(f"expected True, False, None or a callable, got {policy!r}")
+
+
+class _InvalidPolicy(ValueError):
+    """A follow policy that is not `True`, `False` or `None`."""
+
+
+def _listing(path: Path) -> "_ty.Iterator[_ty.Tuple[str, _ty.Optional[FileStat]]]":
+    """`path._scandir()` as `(name, non-following stat or None)` pairs. An
+    entry that has `name` and `stat()`, as `os.scandir()` yields, is adapted;
+    `_scandir()` is documented to yield pairs."""
+    for entry in path._scandir():
+        if isinstance(entry, tuple) and len(entry) == 2:
+            yield entry
+            continue
+        try:
+            stat = FileStat.from_stat(entry.stat(follow_symlinks=False))
+        except OSError:
+            stat = None
+        yield entry.name, stat

pathapi/protocols/_support.py

@@ -0,0 +1,122 @@
+"""`supports()` and `capabilities()`: which protocols a class implements."""
+
+from __future__ import annotations
+
+import importlib as _importlib
+import typing as _ty
+
+from .. import _stubs
+
+_PACKAGE = __name__.partition(".")[0]
+
+
+def _is_protocol(candidate: object) -> bool:
+    """Whether `candidate` is a protocol of this package: a class that lists
+    its primitives."""
+    return (
+        isinstance(candidate, type)
+        and "__primitives__" in vars(candidate)
+        and (candidate.__module__ or "").startswith(_PACKAGE + ".protocols")
+    )
+
+
+def _resolve(cls: type, name: str) -> object:
+    """What `cls.name` resolves to along the MRO, unwrapped to the function
+    for a static or class method; None when no class defines it."""
+    for base in cls.__mro__:
+        if name in vars(base):
+            value = vars(base)[name]
+            return getattr(value, "__func__", value)
+    return None
+
+
+def _defined_outside(value: object) -> bool:
+    """Whether `value` comes from neither this library's protocols nor its
+    `Path`: a class's own method, a mixin's or the standard library's."""
+    module = getattr(value, "__module__", "") or ""
+    return not (
+        module.startswith(_PACKAGE + ".protocols")
+        or module == _PACKAGE + ".path"
+        or module.startswith(_PACKAGE + ".path.")
+    )
+
+
+def _implemented(cls: type, name: str) -> bool:
+    """Whether `name` resolves on `cls` to more than a stub, and, for a method
+    that is only built on other primitives, whether one of them is
+    implemented."""
+    value = _resolve(cls, name)
+    if value is None or _stubs.is_stub(value):
+        return False
+    built_on = _stubs.derivation(value)
+    return not built_on or any(_implemented(cls, other) for other in built_on)
+
+
+def _has(cls: type, entry: "str | tuple[str, ...]") -> bool:
+    """Whether `cls` implements one entry of `__primitives__`. An entry is a
+    primitive name, or a tuple whose first name is the primitive and whose
+    others are operations that replace it when something other than the
+    protocol's own default defines them (`mkdir` for `_mkdir`, `open` for
+    `_open`: `pathlib.Path` has the operation and not the primitive)."""
+    names = (entry,) if isinstance(entry, str) else entry
+    if _implemented(cls, names[0]):
+        return True
+    for name in names[1:]:
+        replacement = _resolve(cls, name)
+        if replacement is not None and _defined_outside(replacement):
+            return True
+    return False
+
+
+def _static(cls: type, protocol: type) -> bool:
+    if not protocol.__primitives__ and protocol not in cls.__mro__:
+        # Nothing to implement: the operations come with the protocol.
+        return False
+    return all(_has(cls, entry) for entry in protocol.__primitives__)
+
+
+def supports(obj: object, *protocols: type) -> bool:
+    """Whether `obj` (an instance or a class) implements every protocol
+    named: each primitive of each resolves to something other than the
+    protocol's default stub. A class whose answer depends on its connection
+    defines `_supports(protocol) -> bool | None`, asked first for an instance;
+    `None` falls through to the answer from the class. That hook makes at most
+    one request per backend, cached for the backend's lifetime, and never
+    raises: a failed request answers `None`.
+
+    The answer is advisory, like `supported_checksums()`: a primitive may
+    still raise `NotImplementedError` for an argument it cannot handle.
+    `TypeError` for no protocol, or for something that is not a protocol of
+    this package.
+    """
+    if not protocols:
+        raise TypeError("supports() needs at least one protocol")
+    for protocol in protocols:
+        if not _is_protocol(protocol):
+            raise TypeError(f"{protocol!r} is not a protocol of {_PACKAGE}")
+    instance = None if isinstance(obj, type) else obj
+    cls = obj if isinstance(obj, type) else type(obj)
+    for protocol in protocols:
+        if instance is not None:
+            hook = getattr(cls, "_supports", None)
+            if callable(hook):
+                answer = hook(instance, protocol)
+                if answer is not None:
+                    if not answer:
+                        return False
+                    continue
+        if not _static(cls, protocol):
+            return False
+    return True
+
+
+def capabilities(obj: object) -> "_ty.FrozenSet[type]":
+    """The protocols of this package that `obj` (an instance or a class)
+    supports, in the sense of `supports()`."""
+    module = _importlib.import_module(_PACKAGE + ".protocols")
+    known = [
+        value
+        for value in (getattr(module, name) for name in module.__all__)
+        if _is_protocol(value)
+    ]
+    return frozenset(protocol for protocol in known if supports(obj, protocol))

pathapi/protocols/_transfer.py

@@ -0,0 +1,100 @@
+"""What `copy()` and `move()` hand to one another: stats, identity and modes."""
+
+from __future__ import annotations
+
+import contextlib as _contextlib
+import contextvars as _contextvars
+import stat as _stat
+import typing as _ty
+
+if _ty.TYPE_CHECKING:
+    from ..path import Path
+
+
+def _stat_or_none(path: Path, follow_symlinks: bool):
+    """`path.stat()`, or None where there is none to have: a missing path, a
+    backend without `stat()`. The callers then do what they did without it."""
+    try:
+        return path.stat(follow_symlinks=follow_symlinks)
+    except (OSError, ValueError, NotImplementedError):
+        return None
+
+
+class _Handed:
+    """What `move()` found out about the two roots, for the one `copy()` it
+    calls on exactly this source and target. `source_stat` is the source's
+    own stat (None: not known to be a plain entry), `target_absent` that
+    nothing was at the target, with nothing written or removed there since."""
+
+    __slots__ = ("source", "target", "source_stat", "target_absent", "taken")
+
+    def __init__(self, source, target, source_stat, target_absent):
+        self.source, self.target = source, target
+        self.source_stat, self.target_absent = source_stat, target_absent
+        self.taken = False
+
+
+_HANDED: "_contextvars.ContextVar[_Handed | None]" = _contextvars.ContextVar(
+    "pathapi_handed_stats", default=None
+)
+
+
+@_contextlib.contextmanager
+def _handing(source, target, source_stat, target_absent):
+    """Make `source_stat` and `target_absent` available to the `copy()` of
+    `source` onto `target` made inside the block, once, and to nothing else
+    (`ObjectStorePath.copy()` and the like pass the very same objects on to
+    `Path.copy()`)."""
+    token = _HANDED.set(_Handed(source, target, source_stat, target_absent))
+    try:
+        yield
+    finally:
+        _HANDED.reset(token)
+
+
+def _take_handed(source, target) -> "_Handed | None":
+    """What `move()` handed to the copy of exactly `source` onto `target`, the
+    first time it is asked; None for any other copy."""
+    handed = _HANDED.get()
+    if (
+        handed is None
+        or handed.taken
+        or handed.source is not source
+        or handed.target is not target
+    ):
+        return None
+    handed.taken = True
+    return handed
+
+
+def _same_identity(first, second) -> bool:
+    """Whether two stats carry the same `(st_dev, st_ino)`. A stat without
+    them (a `FileStat`, an SFTP attribute set) says nothing."""
+    one = (getattr(first, "st_dev", None), getattr(first, "st_ino", None))
+    other = (getattr(second, "st_dev", None), getattr(second, "st_ino", None))
+    return None not in one and None not in other and one == other
+
+
+def _copy_mode(
+    src: Path, target: Path, follow_symlinks: bool, stat: "_ty.Any" = None
+) -> None:
+    """Give `target` the permission bits `src` reports, when it reports any.
+
+    Only a mode the source backend actually reported is metadata:
+    `FileStat`'s placeholder (0o444 for a file) is not, and applying it made
+    every copy from MemPath/HTTP/S3/... a read-only file that a re-copy or
+    re-sync could not replace. Permission bits only: the file-type bits of
+    `st_mode` are not a mode, and a backend such as FTP's SITE CHMOD sends
+    them verbatim. Between two classes the setuid, setgid and sticky bits are
+    dropped: a mode read from another backend (a tar member, a remote
+    server) must not make a privileged file here."""
+    try:
+        if stat is None:
+            stat = src.stat(follow_symlinks=follow_symlinks)
+        if getattr(stat, "mode_known", True) and stat.st_mode:
+            mode = _stat.S_IMODE(stat.st_mode)
+            if type(src) is not type(target):
+                mode &= ~(_stat.S_ISUID | _stat.S_ISGID | _stat.S_ISVTX)
+            target.chmod(mode)
+    except NotImplementedError:
+        pass

pathapi/protocols/checksum.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import typing as _ty
+
+from .. import _stubs
+
+__all__ = ["NativeChecksum"]
+
+
+class NativeChecksum(_ty.Protocol):
+    """Composable protocol for backends that can compute a file digest
+    server-side, without streaming the file's content through this
+    process.
+
+    Optional per-`Path`-subclass, like every other protocol in this
+    package (`io.BinaryOpen`, `fs.Stat`, `fs.Chmod`) -- most backends will
+    never implement it, and the base `Path` ABC does not require it.
+    `sync.PathSyncer` (and any other caller) is expected to try this
+    first and fall back to a streaming checksum (`checksum.md5`/
+    `sha256`) on `NotImplementedError`.
+
+    Two methods, two different jobs: `supported_checksums()` is an
+    *advisory* capability query (never raises, so a caller can pick a
+    shared algorithm across two paths -- e.g.
+    `source.supported_checksums() & target.supported_checksums()` -- before
+    calling anything expensive); `checksum()` is the *authoritative*
+    per-call contract and still MUST raise `NotImplementedError` on its own
+    for any algorithm it can't actually produce, even if a caller never
+    consulted `supported_checksums()` first (belt-and-suspenders -- the
+    checksum method's own contract, not just the advertisement, is what a
+    correctness-sensitive caller can rely on).
+    """
+
+    __slots__ = ()
+
+    __primitives__: _ty.ClassVar[tuple[object, ...]] = ("checksum",)
+
+    def supported_checksums(self) -> "_ty.FrozenSet[str]":
+        """Advisory set of `algorithm` names this path can currently
+        produce a native digest for (e.g. `frozenset({"md5"})`), so a
+        caller can pick a shared algorithm across two paths -- or fall back
+        to streaming -- without probing via trial-and-`NotImplementedError`
+        per candidate. Never raises. The default (no override, matching the
+        base `Path`/`Pathname` ABC not implementing this protocol at all)
+        is an empty `frozenset()` -- "no native support" -- which is also
+        the correct answer for a backend whose native-hashing capability
+        can vary at runtime (e.g. per-connection extension negotiation) and
+        currently has none available.
+
+        This can be a live/dynamic check (e.g. reflecting whether the
+        current server connection actually advertised a given SFTP
+        extension), not necessarily a hardcoded class-level constant --
+        implementations should recompute it if capability can change
+        within the object's lifetime, and are free to cache it if not.
+        """
+        return frozenset()
+
+    @_stubs.primitive
+    def checksum(self, algorithm: str = "md5") -> str:
+        """Return a hex-digest checksum of this file's content, computed by
+        the backend itself (e.g. an SFTP server implementing the filexfer draft's
+        `check-file-handle` extension -- OpenSSH does not --, a WebDAV `getetag`, ...) rather than by streaming the
+        content through `open("rb")`.
+
+        `algorithm` names a `hashlib`-style digest (at least `"md5"` must
+        be accepted, matching `PathSyncer`'s current default). A backend
+        that cannot produce the requested algorithm -- whether because it
+        supports no native hashing at all, or only a different algorithm --
+        MUST raise `NotImplementedError` rather than silently returning a
+        digest under a different algorithm or a value that isn't a true
+        content hash. This is a hard requirement, not a style preference:
+        comparing two checksums computed under different algorithms (or
+        comparing a real hash to something hash-shaped but not actually a
+        content digest, e.g. S3's ETag for a multipart upload) can silently
+        produce a false "in sync" verdict. Callers must never catch
+        anything broader than `NotImplementedError` here.
+        `supported_checksums()` not listing `algorithm` is advisory, not a
+        substitute for this method enforcing its own contract.
+        """
+        return _stubs._unimplemented("checksum")