pathapi 0.1.0__py3-none-any.whl

pathapi/mempath.py

@@ -0,0 +1,438 @@
+from __future__ import annotations
+
+import errno as _errno
+import io
+import posixpath as _posix
+import time as _time
+from io import IOBase
+from urllib.parse import quote as _urlquote
+
+from .path import Path, Pathname
+from .protocols._errors import _os_error
+from ._filestat import FileStat
+
+__all__ = ["MemBytesIO", "MemFile", "MemPath", "MemPathBackend"]
+
+
+class MemPathBackend(dict):
+    """Nested-dict storage backing one or more `MemPath` trees. A `dict`
+    value is a directory; a `bytearray` value is a file's content. Share
+    one instance across `MemPath`s (via `backend=`) to give them the same
+    virtual filesystem."""
+
+
+class MemFile(bytearray):
+    """A file's content in a `MemPathBackend`, carrying its modification
+    time. A plain `bytearray` placed in a backend by hand still works; it
+    reports `st_mtime` 0."""
+
+    __slots__ = ("mtime",)
+
+    def __init__(self, *args) -> None:
+        super().__init__(*args)
+        self.mtime = 0.0
+        _touch(self)
+
+    def __reduce_ex__(self, protocol):
+        # `bytearray.__reduce_ex__` carries slot state only from 3.11; without
+        # this a copy or a pickle is re-stamped with the time it was made.
+        return _memfile, (bytes(self), self.mtime)
+
+
+def _memfile(content: bytes, mtime: float) -> "MemFile":
+    """Rebuild a `MemFile` with the modification time it had."""
+    file = MemFile(content)
+    file.mtime = mtime
+    return file
+
+
+def _touch(content) -> None:
+    """Advance `content`'s mtime -- strictly, even within one clock tick:
+    a sync quick check comparing (size, mtime) must see every write."""
+    try:
+        content.mtime = max(_time.time(), getattr(content, "mtime", 0.0) + 1e-6)
+    except AttributeError:
+        pass
+
+
+class MemBytesIO(io.BytesIO):
+    """A `BytesIO` that writes its buffer back into the backing
+    `bytearray` (`dest`) on `flush()` and close, so `MemPath` files persist
+    across `open()` calls. With `append=True` every write lands at the end,
+    like `O_APPEND`, whatever the current position, and only the bytes this
+    handle wrote are added to `dest`, so two appenders both land."""
+
+    def __init__(self, dest: bytearray, *, append: bool = False) -> None:
+        self._bytes = dest
+        self._append = append
+        self._published = 0
+        super().__init__()
+        if append:
+            snapshot = bytes(dest)
+            super().write(snapshot)
+            self._published = len(snapshot)
+
+    def _publish(self) -> None:
+        # getvalue(), not seek(0);read(): a caller that seeks before
+        # closing (or opened in append mode, positioned at EOF) would
+        # otherwise lose everything before the current position.
+        content = self.getvalue()
+        if self._append:
+            # One extend() of the new bytes: a second appender's bytes
+            # already in `dest` stay, and a reader never sees a shorter file.
+            self._bytes.extend(content[self._published :])
+            self._published = len(content)
+        else:
+            # One slice assignment, not clear() then extend(): a reader
+            # never sees the file emptied in between.
+            self._bytes[:] = content
+        _touch(self._bytes)
+
+    def write(self, data) -> int:
+        if self._append and not self.closed:
+            self.seek(0, io.SEEK_END)
+        return super().write(data)
+
+    def writelines(self, lines) -> None:
+        # BytesIO.writelines bypasses an overridden write().
+        for line in lines:
+            self.write(line)
+
+    def flush(self) -> None:
+        # A real file's flush makes the written bytes visible to readers.
+        super().flush()
+        self._publish()
+
+    def close(self) -> None:
+        if not self.closed:
+            self._publish()
+        return super().close()
+
+
+class _MemReader(io.BytesIO):
+    """A read-only snapshot of a file's content: `open("rb")` on a real
+    file cannot be written, and a plain `BytesIO` accepted writes that went
+    nowhere."""
+
+    def writable(self) -> bool:
+        if self.closed:
+            raise ValueError("I/O operation on closed file.")
+        return False
+
+    def write(self, data):
+        self.writable()
+        raise io.UnsupportedOperation("write")
+
+    def writelines(self, lines):
+        self.writable()
+        raise io.UnsupportedOperation("write")
+
+    def truncate(self, size=None):
+        self.writable()
+        raise io.UnsupportedOperation("truncate")
+
+
+class MemPath(Path):
+    """In-memory `Path` implementation over nested dicts (see
+    `MemPathBackend`) -- a lightweight virtual filesystem for mocks, tests,
+    or transient storage, and the reference exemplar for Track A of
+    extending this library (subclassing `Path` directly; see
+    `docs/guides/extending.md`)."""
+
+    __slots__ = ("_backend", "_segments", "_normalized")
+
+    def __init__(
+        self, *segments: str | Pathname | Path, backend: MemPathBackend = None
+    ):
+        # Joined and normalized like `PurePosixPath`: empty and "." segments collapse and
+        # an absolute argument restarts the join (`MemPath("/root") / "/etc"` is "/etc").
+        path = ""
+        _backend = None
+        for segment in segments:
+            if isinstance(segment, MemPath):
+                text = segment.as_posix()
+                # The first MemPath argument names the filesystem, as the
+                # left operand does for `/`; a later one (often a pattern or
+                # a name built without a backend) only contributes its text.
+                if _backend is None:
+                    _backend = segment.backend
+            elif isinstance(segment, Path):
+                raise NotImplementedError()
+            elif isinstance(segment, Pathname):
+                text = "/".join(segment.segments)
+            elif isinstance(segment, str):
+                text = segment
+            else:
+                raise TypeError(
+                    "argument should be a str or a Pathname, "
+                    f"not {type(segment).__name__!r}"
+                )
+            if text.startswith("/") or not path:
+                path = text
+            elif text:
+                path = f"{path}/{text}"
+        self._segments = self._parse(path)
+        # `is not None`, not truthiness: a fresh root's backend is an empty dict, which
+        # is falsy, and a join off it would get a disconnected new backend.
+        if _backend is not None and backend is None:
+            backend = _backend
+        self._backend = backend if backend is not None else MemPathBackend()
+        self._normalized = None
+
+    @staticmethod
+    def _parse(path: str) -> tuple:
+        """Segments of a joined path string: `("", "")` for the root,
+        `("", name, ...)` for another absolute path, `(name, ...)` for a
+        relative one and `()` for the empty path (so its `root` is "")."""
+        names = [name for name in path.split("/") if name and name != "."]
+        if path.startswith("/"):
+            return ("", *names) if names else ("", "")
+        return tuple(names)
+
+    def __repr__(self):
+        return "{}({!r})".format(type(self).__name__, self.as_posix())
+
+    def __str__(self) -> str:
+        return self.as_posix()
+
+    @property
+    def backend(self):
+        return self._backend
+
+    def _same_filesystem(self, other: "MemPath") -> bool:
+        # Equality ignores the backend; two trees are one filesystem only
+        # when they share the `MemPathBackend` instance.
+        return self._backend is other._backend
+
+    def _node_key(self):
+        # "a.txt", "/a.txt" and "/d/../a.txt" are one node. This reads no tree, so `..` is
+        # applied to the text; I/O applies it to the tree (`_parent_container`) and agrees
+        # wherever the path exists (`/missing/../a.txt` fails on I/O whatever it equals).
+        return self._backend, tuple(name for name in self.normalized if name)
+
+    @property
+    def normalized(self):
+        """The names of this path with `..` applied to the text and clamped
+        at the root; `[""]` for the root. `_node_key()` reads it."""
+        if self._normalized is None:
+            # Normalize against a virtual root ("/" + posix) so a ".."-escaping path is clamped
+            # at the root (posixpath.normpath("..") is ".."). The leading "/" is stripped first:
+            # normpath keeps an exactly double leading slash, which would turn "/" into "//".
+            posix = self.as_posix().lstrip("/")
+            self._normalized = _posix.normpath("/" + posix).removeprefix("/").split("/")
+        return self._normalized
+
+    @property
+    def segments(self):
+        return self._segments
+
+    @property
+    def parts(self):
+        return self.segments, self.backend
+
+    @property
+    def parent(self):
+        segments = self.segments
+        if not segments or segments == ("", ""):
+            return self
+        if len(segments) == 2 and segments[0] == "":
+            # "/a" -> "/": dropping the root gave the relative empty path.
+            return self.with_segments("", "")
+        return self.with_segments(*segments[:-1])
+
+    def relative_to(self, other, *, walk_up: bool = False):
+        """`self` below `other`, as a relative path on the same backend.
+
+        `other` is a `MemPath` of the same backend or a `str`. Names are
+        compared as written, with no `..` applied. `ValueError` when `self`
+        is not below `other`, when the two differ in being rooted, or when
+        the backends differ. With `walk_up`, a path beside `other` gets a
+        `..` per level climbed; a `..` in `other` cannot be walked."""
+        if isinstance(other, MemPath):
+            if other.backend is not self.backend:
+                raise ValueError(
+                    f"{str(self)!r} and {str(other)!r} are on different backends"
+                )
+        else:
+            other = self.with_segments(other)
+        rooted = self.segments[:1] == ("",)
+        other_rooted = other.segments[:1] == ("",)
+        names = [name for name in self.segments if name]
+        other_names = [name for name in other.segments if name]
+        for step in range(len(other_names) + 1):
+            keep = len(other_names) - step
+            if rooted == other_rooted and names[:keep] == other_names[:keep]:
+                return self.with_segments(*[".."] * step, *names[keep:])
+            if not walk_up:
+                raise ValueError(
+                    f"{str(self)!r} is not in the subpath of {str(other)!r}"
+                )
+            if keep and other_names[keep - 1] == "..":
+                raise ValueError(f"'..' segment in {str(other)!r} cannot be walked")
+        raise ValueError(f"{str(self)!r} and {str(other)!r} have different anchors")
+
+    def _cwd(self):
+        return self.with_segments("/")
+
+    def with_segments(self, *segments: str):
+        if all(isinstance(segment, str) for segment in segments):
+            # The `Pathname` protocol's spelling: segments joined with "/",
+            # a leading "" marking the root (`("", "a")` is "/a").
+            segments = ("/".join(segments),)
+        return type(self)(*segments, backend=self.backend)
+
+    def as_uri(self):
+        return f"mempath:{_urlquote(self.as_posix())}"
+
+    def _parent_container(self) -> tuple[dict[str, bytearray], str]:
+        """`(container, name)` of the node this path names; `name` is "" for
+        the root, whose container is the backend. `..` is applied to the tree:
+        the directory it leaves must exist, and the root is its own parent."""
+        containers = [self.backend]
+        names: list[str] = []
+        components = [name for name in self.segments if name]
+        for index, component in enumerate(components):
+            if component == "..":
+                if names:
+                    names.pop()
+                    containers.pop()
+                continue
+            if index == len(components) - 1:
+                return containers[-1], component
+            child = containers[-1].get(component)
+            if child is None:
+                raise _os_error(FileNotFoundError, _errno.ENOENT, self)
+            if not isinstance(child, dict):
+                # An ancestor names a file: without this the next step raises TypeError, which
+                # passes the OSError guards of stat()/exists()/is_dir(). NotADirectoryError is an
+                # OSError, as stdlib raises.
+                raise _os_error(
+                    NotADirectoryError,
+                    _errno.ENOTDIR,
+                    self.with_segments(*names, component),
+                )
+            containers.append(child)
+            names.append(component)
+        if not names:
+            return self.backend, ""
+        return containers[-2], names[-1]
+
+    def _mkdir(self, mode: int):
+        parent, name = self._parent_container()
+        # setdefault is one atomic step: a separate check-then-set let two
+        # concurrent mkdir() calls both succeed, the second replacing a
+        # directory the first may already have populated.
+        new = {}
+        if not name or parent.setdefault(name, new) is not new:
+            raise _os_error(FileExistsError, _errno.EEXIST, self)
+
+    def rmdir(self):
+        parent, name = self._parent_container()
+        if not name:
+            # The root exists, so it is not "missing", and a tree cannot lose it.
+            raise OSError(
+                _errno.EBUSY, "The root of a MemPath tree cannot be removed", str(self)
+            )
+        content = parent.get(name)
+        if content is None:
+            raise _os_error(FileNotFoundError, _errno.ENOENT, self)
+        elif not isinstance(content, dict):
+            raise _os_error(NotADirectoryError, _errno.ENOTDIR, self)
+        elif len(content) != 0:
+            # pathlib raises OSError(ENOTEMPTY); FileExistsError (EEXIST)
+            # carried no errno and matched no caller's ENOTEMPTY check.
+            raise OSError(_errno.ENOTEMPTY, "Directory not empty", str(self))
+        parent.pop(name)
+
+    def unlink(self, missing_ok=False):
+        parent, name = self._parent_container()
+        if not name:
+            # The root exists and is a directory: missing_ok does not apply.
+            raise _os_error(IsADirectoryError, _errno.EISDIR, self)
+        content = parent.get(name)
+        if content is None:
+            if missing_ok:
+                return
+            raise _os_error(FileNotFoundError, _errno.ENOENT, self)
+        elif isinstance(content, dict):
+            raise _os_error(IsADirectoryError, _errno.EISDIR, self)
+        parent.pop(name)
+
+    def stat(self, *, follow_symlinks=True):
+        parent, name = self._parent_container()
+        if not name:
+            return FileStat(is_dir=True)
+
+        if name not in parent:
+            raise _os_error(FileNotFoundError, _errno.ENOENT, self)
+
+        content = parent[name]
+        is_dir = isinstance(content, dict)
+        # st_size was never set for files (always defaulted to 0), which
+        # silently broke any size-based checksum (e.g. PathSyncer's default
+        # usage pattern).
+        return FileStat(
+            is_dir=is_dir,
+            st_size=0 if is_dir else len(content),
+            st_mtime=getattr(content, "mtime", 0),
+        )
+
+    def _utime(self, *, atime=None, mtime=None) -> None:
+        # Only a file's modification time is kept: a directory (a plain dict)
+        # and a bytearray put in the backend by hand have nowhere to put one.
+        parent, name = self._parent_container()
+        content = parent.get(name) if name else parent
+        if content is None:
+            raise _os_error(FileNotFoundError, _errno.ENOENT, self)
+        if not isinstance(content, MemFile):
+            raise NotImplementedError("_utime() of a directory or a plain bytearray")
+        if mtime is not None:
+            content.mtime = float(mtime)
+
+    def iterdir(self):
+        parent, name = self._parent_container()
+        content = parent.get(name) if name else parent
+        if content is None:
+            raise _os_error(FileNotFoundError, _errno.ENOENT, self)
+        if not isinstance(content, dict):
+            raise _os_error(NotADirectoryError, _errno.ENOTDIR, self)
+        for c in list(content.keys()):
+            yield self.with_segments(*self.segments, c)
+
+    def _open(self, mode="r", buffering=-1) -> IOBase:
+        # mode contract: "r"/"w" are required; "x"/"a" are supported here
+        # as an extension. Anything else raises NotImplementedError.
+        parent, name = self._parent_container()
+        if not name:
+            # An empty name is the virtual root, which stat() reports as a
+            # directory. Without this guard "w"/"a" created a bogus ""
+            # entry in the backend and "r" claimed FileNotFoundError.
+            raise _os_error(IsADirectoryError, _errno.EISDIR, self)
+        if mode == "r":
+            if name not in parent:
+                raise _os_error(FileNotFoundError, _errno.ENOENT, self)
+            content = parent[name]
+            if isinstance(content, dict):
+                raise _os_error(IsADirectoryError, _errno.EISDIR, self)
+            return _MemReader(content)
+        if mode not in ("w", "x", "a"):
+            raise NotImplementedError(f"mode={mode!r}")
+        # Creation goes through setdefault, one atomic step: a separate
+        # "exists?" check followed by an assignment let two concurrent
+        # open("x") calls both succeed.
+        new = MemFile()
+        content = parent.setdefault(name, new)
+        if isinstance(content, dict):
+            # Truncating over a directory silently replaced the whole
+            # subtree with a file; stdlib raises IsADirectoryError.
+            raise _os_error(IsADirectoryError, _errno.EISDIR, self)
+        if mode == "x":
+            if content is not new:
+                raise _os_error(FileExistsError, _errno.EEXIST, self)
+            return MemBytesIO(content)
+        if mode == "w" and content is not new:
+            # Truncate the same file, as "w" does on disk: its mtime then
+            # still advances past the previous write's.
+            content.clear()
+            _touch(content)
+        return MemBytesIO(content, append=mode == "a")

pathapi/path/__init__.py

@@ -0,0 +1,19 @@
+"""Object-oriented filesystem paths.
+
+This module provides classes to represent abstract paths and concrete
+paths with operations that have semantics appropriate for different
+operating systems.
+"""
+
+from __future__ import annotations
+
+from ._pure import FsPathLike, P, PN, Pathname, PurePathLike
+from ._path import Path, PathLike
+
+__all__ = [
+    "FsPathLike",
+    "Path",
+    "PathLike",
+    "Pathname",
+    "PurePathLike",
+]

pathapi/path/_info.py

@@ -0,0 +1,10 @@
+"""`Path.info`'s object lives with the protocol that returns it; this name
+stays importable and is the same module."""
+
+from __future__ import annotations
+
+import sys as _sys
+
+from ..protocols import _info
+
+_sys.modules[__name__] = _info

pathapi/path/_path.py

@@ -0,0 +1,198 @@
+"""`Path`: a pathname with I/O, built from the protocols."""
+
+from __future__ import annotations
+
+import pathlib as _pathlib
+import sys as _sys
+import types as _types
+import typing as _ty
+
+from ..protocols import (
+    BinaryOpen,
+    Chmod,
+    Chown,
+    Copy,
+    Create,
+    Hardlink,
+    Identity,
+    Listing,
+    Move,
+    Owned,
+    Readlink,
+    Remove,
+    Resolve,
+    Stat,
+    Symlink,
+    Utime,
+)
+from ._pure import Pathname
+
+# Operations that must come from pathapi even when a concrete `pathlib`
+# class precedes it in a subclass's MRO; `Path.__init_subclass__` applies
+# them and says why.
+_OPERATION_NAMES = (
+    "copy",
+    "move",
+    "copy_into",
+    "move_into",
+    "exists",
+    "rglob",
+    "read_text",
+    "write_text",
+    "symlink_to",
+)
+
+
+def _local_primitives() -> "dict[str, _ty.Callable]":
+    """The functions `LocalPath` defines, by name: what a class that mixes a
+    concrete stdlib path with `Path` but not `LocalPath` is given for its
+    local primitives (`stat`, `chmod`, `is_junction`, `is_mount`, `glob`,
+    `walk`, `_scandir`, `_symlink_to`, `_chown`, ...). Taken from the class
+    itself so the list cannot fall behind it. Empty while `LocalPath` is
+    still being created."""
+    module = _sys.modules.get(__name__.partition(".")[0] + ".fspath")
+    local = getattr(module, "LocalPath", None)
+    if local is None:
+        return {}
+    return {
+        name: value
+        for name, value in vars(local).items()
+        if isinstance(value, _types.FunctionType)
+        and not (name.startswith("__") and name.endswith("__"))
+    }
+
+
+def _inherits_foreign_default(cls: type, name: str) -> bool:
+    """Whether `cls` gets `name` from stdlib `pathlib` or from this
+    library's own generic defaults (`Path`, `Pathname`, the protocols)
+    rather than from its own body or a mixin of its own."""
+    if name in vars(cls):
+        return False
+    owner = next((base for base in cls.__mro__[1:] if name in vars(base)), None)
+    if owner is None:
+        return True
+    module = getattr(owner, "__module__", "") or ""
+    package = __name__.partition(".")[0]
+    return (
+        module == "pathlib"
+        or module.startswith("pathlib.")
+        or module == package + ".path"
+        or module.startswith(package + ".path.")
+        or module == package + ".protocols"
+        or module.startswith(package + ".protocols.")
+    )
+
+
+class Path(
+    Pathname,
+    Move,
+    Copy,
+    Identity,
+    Create,
+    Symlink,
+    Remove,
+    Listing,
+    Resolve,
+    Readlink,
+    Hardlink,
+    Owned,
+    Stat,
+    Chmod,
+    Chown,
+    Utime,
+    BinaryOpen,
+):
+    """Base class for manipulating paths with I/O."""
+
+    __slots__ = ()
+
+    def __init_subclass__(cls, **kwargs):
+        """Guarantee pathapi operation precedence in every subclass.
+
+        Concrete path classes are routinely built by mixing a `pathlib`
+        class with this one -- our own `LocalPath` does it, and the
+        documented downstream recipe (`class X(PosixPathname, Path)`) does
+        it transitively. Python's MRO then resolves a name to whichever
+        base declares it first, which for those classes can be `pathlib`
+        rather than `pathapi` -- and which one wins changes with the
+        interpreter version, because stdlib `pathlib` keeps gaining and
+        changing methods (see `_OPERATION_NAMES`).
+
+        Rather than making every downstream implementer rediscover this and
+        hand-write forwarding methods, re-assert our implementations here
+        for any subclass that would otherwise inherit a non-pathapi
+        one. A subclass (or an intermediate mixin) that defines the method
+        *itself* is always left alone -- this only displaces implementations
+        coming from outside this library.
+
+        `_OPERATION_NAMES` lists what is re-asserted, for two opposite
+        reasons. Newer stdlib overrides ours: 3.14's `copy` and `move` expect
+        the private `_copy_from` protocol, so such a class either raises
+        `AttributeError` on non-local backends or silently succeeds on local
+        ones with stdlib's metadata semantics (timestamps preserved, where
+        ours preserves `st_mode`), so mtime-based syncs converge on 3.14 and
+        not before; 3.14's `copy_into` and `move_into` call `copy()` and
+        `move()` with stdlib's keywords and defaults. Older stdlib lacks our
+        keywords: `exists(follow_symlinks=)` (3.12+), `read_text` and
+        `write_text(newline=)` (3.13+), `rglob`'s extensions, and
+        `symlink_to(force=)`, which no stdlib has. `replace` is not listed:
+        `LocalPath` keeps stdlib's `os.replace`, which `move()` uses to swap a
+        local file atomically.
+
+        A class that mixes a concrete stdlib path with `Path` but not
+        `LocalPath` is a local class too, and gets what `LocalPath` has for
+        each name it defines (`_local_primitives`) wherever stdlib or a
+        generic default would otherwise answer: the generic `is_junction()`
+        and `is_mount()` say False, so `rm(recursive=True)` would walk into a
+        junction, and stdlib's `stat()`, `chmod()` and `_scandir()` do not
+        take pathapi's arguments.
+        """
+        super().__init_subclass__(**kwargs)
+        primitives = _local_primitives() if issubclass(cls, _pathlib.Path) else {}
+        if primitives:
+            from ..fspath import _BaseFSPathname
+
+            for name, ours in primitives.items():
+                if name == "glob" and not issubclass(cls, _BaseFSPathname):
+                    # LocalPath.glob needs the flavour helpers of
+                    # _BaseFSPathname.
+                    ours = Path.glob
+                if _inherits_foreign_default(cls, name):
+                    setattr(cls, name, ours)
+        for name in _OPERATION_NAMES:
+            # A class that defines the operation in its OWN body is always
+            # authoritative -- never displace a deliberate override (this
+            # also covers `LocalPath.copy`/`move`'s explicit routing).
+            if name in vars(cls):
+                continue
+            # The owner is the base that supplies the implementation, not the module of
+            # the resolved function: a downstream mixin may define it in its own module.
+            owner = next((base for base in cls.__mro__[1:] if name in vars(base)), None)
+            if owner is None:
+                continue
+            # Only stdlib `pathlib` is displaced; a mixin, a user base or pathapi
+            # itself is deliberate and stays, which keeps this off third-party code.
+            owner_module = getattr(owner, "__module__", "") or ""
+            if owner_module != "pathlib" and not owner_module.startswith("pathlib."):
+                continue
+            ours = getattr(Path, name, None)
+            if ours is None:
+                continue
+            setattr(cls, name, ours)
+
+    def __new__(cls, *args: _ty.Any, **kwargs: _ty.Any) -> _ty.Self:
+        if cls is Path:
+            from ..fspath import LocalPath
+
+            # `LocalPath.__new__` is `pathlib.Path.__new__`, which parses `args` into
+            # `_drv/_root/_parts` before 3.12 (3.12+ does it in `PurePath.__init__`);
+            # `Pathname.__new__(cls)` would skip that and drop `args`.
+            return _ty.cast("_ty.Self", LocalPath.__new__(LocalPath, *args, **kwargs))
+        return Pathname.__new__(cls)
+
+    def is_hidden(self):
+        """Return True if the final path component is a hidden file/directory."""
+        return self.name.startswith(".")
+
+
+PathLike = _ty.Union[str, Path]