pathapi 0.1.0__py3-none-any.whl

pathapi/_filestat.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+import stat as _stat
+import typing as _ty
+
+from .protocols import FileStatLike as _FStat
+
+if _ty.TYPE_CHECKING:
+    from os import stat_result as _os_stat
+
+    from .path import Path
+
+__all__ = ["FileStat"]
+
+
+def sizeof_fmt(num: _ty.Union[int, float]) -> str:
+    for unit in ("", "K", "M", "G", "T", "P", "E", "Z"):
+        if abs(num) < 1024:
+            if unit:
+                return "%3.1f%s" % (num, unit)
+            else:
+                return str(int(num))
+        num /= 1024.0
+    return "%.1f%s" % (num, "Y")
+
+
+class FileStat(_FStat):
+    """Concrete, slotted `FileStatLike` for backends without a real
+    `os.stat_result` (e.g. `MemPath`, an HTTP index). `from_path()` builds one
+    from any object with a `stat()` method, or passes a `FileStat` through
+    unchanged."""
+
+    #: The stat fields proper -- what `items()` reports and `from_stat()`
+    #: copies from a foreign stat object.
+    _FIELDS = (
+        "st_mode",
+        "st_nlink",
+        "st_uid",
+        "st_gid",
+        "st_size",
+        "st_atime",
+        "st_mtime",
+        "st_ctime",
+    )
+    __slots__ = _FIELDS + ("mode_known", "size_known")
+
+    st_mode: int
+    st_nlink: int
+    st_uid: int
+    st_gid: int
+    st_size: int
+    st_atime: float
+    st_mtime: float
+    st_ctime: float
+
+    #: Whether `st_mode` was reported by the backend (True) or is a placeholder from
+    #: `is_dir` (False: `S_IFREG | 0o444`, `S_IFDIR | 0o555`). A consumer that would
+    #: write the mode (`copy(preserve_metadata=True)`) skips a placeholder.
+    mode_known: bool
+
+    #: False when the listing knew the entry's type but not its size and time: `st_size`
+    #: and `st_mtime` are placeholders (0) and only the type answers. A consumer that
+    #: needs a size or time asks the path itself, as for a stat that is `None`.
+    size_known: bool
+
+    def __init__(
+        self,
+        st_mode: int | None = None,
+        st_size: int = 0,
+        st_mtime: float = 0,
+        is_dir: bool = False,
+        size_known: bool = True,
+    ):
+        self.size_known = size_known
+        self.mode_known = bool(st_mode)
+        if st_mode and not _stat.S_IFMT(st_mode):
+            # Permission bits alone: the type comes from `is_dir`.
+            st_mode |= _stat.S_IFDIR if is_dir else _stat.S_IFREG
+        self.st_mode = st_mode or (
+            _stat.S_IFDIR | 0o555 if is_dir else _stat.S_IFREG | 0o444
+        )
+        self.st_nlink = 1
+        self.st_uid = 0
+        self.st_gid = 0
+        self.st_size = st_size
+        self.st_atime = 0
+        self.st_mtime = st_mtime
+        self.st_ctime = 0
+
+    def settime(self, value):
+        self.st_atime = self.st_mtime = self.st_ctime = value
+
+    def setmode(self, value, isdir=None):
+        if isdir is None:
+            isdir = _stat.S_ISDIR(self.st_mode)
+        if isdir:
+            self.st_mode = _stat.S_IFDIR | value
+        else:
+            self.st_mode = _stat.S_IFREG | value
+        self.mode_known = True
+
+    def __getitem__(self, key):
+        return getattr(self, key)
+
+    def items(self):
+        for key in self._FIELDS:
+            yield key, getattr(self, key)
+
+    def __repr__(self):
+        return "<%s mode=%o, size=%s, mtime=%d>" % (
+            type(self).__name__,
+            self.st_mode,
+            sizeof_fmt(self.st_size),
+            self.st_mtime,
+        )
+
+    def __str__(self):
+        props = [f"{k}={v}" for k, v in self.items()]
+        return "<%s %s>" % (type(self).__name__, ", ".join(props))
+
+    @classmethod
+    def from_stat(cls, stat: _ty.Any) -> "FileStat":
+        """Copy any stat-like object's (`os.stat_result`, paramiko's
+        `SFTPAttributes`, ...) recognized fields into a fresh `FileStat`,
+        so downstream code (e.g. `.is_dir()`) can rely on a uniform type.
+        Passes an already-`FileStat` through unchanged. The copied mode
+        counts as backend-reported (`mode_known`) unless the source says
+        otherwise or carries no mode at all (missing, `None` or `0`).
+
+        A missing or `None` field becomes `0`: paramiko's `SFTPAttributes`
+        leaves every field the server did not send as `None`, which made
+        `is_dir()` and `repr()` raise TypeError."""
+        if isinstance(stat, FileStat):
+            return stat
+        result = FileStat.__new__(FileStat)
+        for prop in FileStat._FIELDS:
+            value = getattr(stat, prop, None)
+            setattr(result, prop, 0 if value is None else value)
+        result.mode_known = bool(getattr(stat, "mode_known", True)) and bool(
+            result.st_mode
+        )
+        result.size_known = bool(getattr(stat, "size_known", True))
+        return result
+
+    @classmethod
+    def from_path(cls, path: "Path", *, follow_symlink=True):
+        try:
+            stat: _os_stat = path.stat(follow_symlinks=follow_symlink)
+        except FileNotFoundError:
+            return None
+        return cls.from_stat(stat)
+
+    def is_dir(self):
+        """
+        Whether this path is a directory.
+        """
+        return _stat.S_ISDIR(self.st_mode)
+
+    def is_file(self):
+        """
+        Whether this path is a regular file (also True for symlinks pointing
+        to regular files).
+        """
+        return _stat.S_ISREG(self.st_mode)
+
+    def is_symlink(self):
+        """
+        Whether this path is a symbolic link.
+        """
+        return _stat.S_ISLNK(self.st_mode)
+
+    def is_block_device(self):
+        """
+        Whether this path is a block device.
+        """
+        return _stat.S_ISBLK(self.st_mode)
+
+    def is_char_device(self):
+        """
+        Whether this path is a character device.
+        """
+        return _stat.S_ISCHR(self.st_mode)
+
+    def is_fifo(self):
+        """
+        Whether this path is a FIFO.
+        """
+        return _stat.S_ISFIFO(self.st_mode)
+
+    def is_socket(self):
+        """
+        Whether this path is a socket.
+        """
+        return _stat.S_ISSOCK(self.st_mode)

pathapi/_lru.py

@@ -0,0 +1,138 @@
+"""A thread-safe memoizing LRU cache."""
+
+from __future__ import annotations
+
+import collections
+import typing as _ty
+from threading import RLock
+
+__all__ = ["LRU"]
+
+try:
+    ParamSpec = _ty.ParamSpec  # 3.10+
+except AttributeError:
+    try:
+        from typing_extensions import ParamSpec
+    except ImportError:
+
+        class ParamSpec(_ty.TypeVar, _root=True):
+            """Minimal `ParamSpec` stand-in for 3.9 without `typing_extensions`.
+
+            Only the `.args` / `.kwargs` attributes are needed: they appear in
+            annotations that must merely *evaluate*, and a plain `TypeVar` has
+            neither. `typing_extensions` is not a runtime dependency, so the
+            fallback keeps a bare 3.9 install importable.
+            """
+
+            @property
+            def args(self):
+                return self
+
+            @property
+            def kwargs(self):
+                return self
+
+
+K = ParamSpec("K")
+
+
+V = _ty.TypeVar("V")
+
+
+class LRU(_ty.Generic[K, V]):
+    """Thread-safe memoizing LRU cache over a function, callable like the
+    function itself; `invalidate(*args)` evicts and recomputes an entry,
+    `discard(*args)` evicts without recomputing.
+
+    `on_evict(key, value)`, when given, is called for every value the cache
+    drops -- LRU overflow, a `maxsize` shrink, `invalidate()`/`discard()`,
+    and the losing result of two concurrent misses on one key -- so a cache
+    of live resources (connections) can close them instead of leaking them.
+    It runs outside the lock, and an exception it raises is suppressed:
+    eviction is a side effect of an unrelated lookup, which must not fail
+    because a stale resource would not close cleanly.
+
+    The computation itself runs outside the lock, so concurrent misses on
+    one key may each call `func`; the first stored result wins and is
+    returned to every caller, and the others are passed to `on_evict`.
+
+    `maxsize` follows `functools.lru_cache`: `None` is unbounded, and `0` (or
+    less) stores nothing, so `func` runs on every call and its result is
+    returned without reaching `on_evict`.
+    """
+
+    def __init__(
+        self,
+        func: _ty.Callable[K, V],
+        maxsize: int | None = 128,
+        on_evict: "_ty.Callable[[tuple, V], object] | None" = None,
+    ):
+        self.cache = collections.OrderedDict()
+        self.func = func
+        self._maxsize = maxsize
+        self.lock = RLock()
+        self.on_evict = on_evict
+
+    def _dispose(self, evicted: "list[tuple[tuple, V]]") -> None:
+        on_evict = self.on_evict
+        if on_evict is None:
+            return
+        for key, value in evicted:
+            try:
+                on_evict(key, value)
+            except Exception:
+                pass
+
+    @property
+    def maxsize(self):
+        return self._maxsize
+
+    @maxsize.setter
+    def maxsize(self, maxsize: int | None):
+        cache = self.cache
+        evicted = []
+        with self.lock:
+            self._maxsize = maxsize
+            while maxsize is not None and len(cache) > max(maxsize, 0):
+                evicted.append(cache.popitem(last=False))
+        self._dispose(evicted)
+
+    def __call__(self, *args: K.args) -> V:
+        cache = self.cache
+        with self.lock:
+            if args in cache:
+                cache.move_to_end(args)
+                return cache[args]
+        result = self.func(*args)
+        if self._maxsize is not None and self._maxsize <= 0:
+            return result
+        evicted = []
+        with self.lock:
+            if args in cache:
+                # A concurrent miss stored its result first: keep that one,
+                # so every caller shares a single value.
+                existing = cache[args]
+                cache.move_to_end(args)
+                if existing is not result:
+                    evicted.append((args, result))
+                result = existing
+            else:
+                cache[args] = result
+                if self._maxsize is not None and len(cache) > self._maxsize:
+                    evicted.append(cache.popitem(last=False))
+        self._dispose(evicted)
+        return result
+
+    def discard(self, *args: K.args) -> bool:
+        """Drop the entry for `args` (passing it to `on_evict`) without
+        recomputing it. Returns whether an entry was present."""
+        with self.lock:
+            if args not in self.cache:
+                return False
+            value = self.cache.pop(args)
+        self._dispose([(args, value)])
+        return True
+
+    def invalidate(self, *args: K.args) -> V:
+        self.discard(*args)
+        return self(*args)

pathapi/_names.py

@@ -0,0 +1,70 @@
+"""Whether a name from a listing can be joined onto a directory safely."""
+
+from __future__ import annotations
+
+from pathlib import PureWindowsPath as _PureWindowsPath
+
+__all__ = ["is_safe_child_name", "is_windows_flavoured"]
+
+
+def is_windows_flavoured(path: object) -> bool:
+    """Whether names joined onto `path` are interpreted with Windows rules.
+
+    True for a `pathlib.PureWindowsPath` (so `LocalPath` on Windows) and for
+    a path whose `filepath` is one (a `file:` URI path on Windows). Everything else --
+    `MemPath`, remote schemes, POSIX local paths -- treats `\\` and `:` as
+    ordinary filename characters.
+    """
+    if isinstance(path, _PureWindowsPath):
+        return True
+    try:
+        filepath = getattr(path, "filepath", None)
+    except Exception:
+        return False
+    return isinstance(filepath, _PureWindowsPath)
+
+
+_WINDOWS_DEVICE_NAMES = frozenset(
+    ["CON", "PRN", "AUX", "NUL"]
+    + [f"COM{n}" for n in range(1, 10)]
+    + [f"LPT{n}" for n in range(1, 10)]
+)
+
+
+def _windows_rewrites(name: str) -> bool:
+    """Whether Windows would store the non-empty `name` under another name or
+    hand it to a device. It drops a trailing dot or space, and older versions
+    open a reserved device name whatever follows its first dot (`nul.txt`)."""
+    return (
+        name[-1] in " ."
+        or name.partition(".")[0].rstrip(" ").upper() in _WINDOWS_DEVICE_NAMES
+    )
+
+
+def _is_safe_name(name: object, windows: bool, rewrites: bool) -> bool:
+    if not isinstance(name, str) or name in ("", ".", "..") or "/" in name:
+        return False
+    if "\0" in name:
+        return False
+    if windows:
+        if "\\" in name or ":" in name:
+            return False
+        if rewrites and _windows_rewrites(name):
+            return False
+    return True
+
+
+def is_safe_child_name(name: object, *, windows: bool = False) -> bool:
+    """Whether `name` is a single path component that stays inside its parent.
+
+    Use this before joining a name that came from somewhere untrusted (a
+    remote listing, an archive member, a sync source) onto a destination.
+    Always rejected: a non-`str`, `""`, `"."`, `".."`, and any name
+    containing `/` or NUL. With `windows=True` (see `is_windows_flavoured`)
+    also rejected: `\\`, `:` (a drive prefix such as `D:x`, or an NTFS
+    alternate data stream), a trailing dot or space (Windows drops it, so
+    `"report."` and `"report"` name one file), and the reserved device names
+    `CON`, `PRN`, `AUX`, `NUL`, `COM1`-`COM9` and `LPT1`-`LPT9`, in any case
+    and with or without an extension (`"nul.txt"`).
+    """
+    return _is_safe_name(name, windows, True)

pathapi/_permissions.py

@@ -0,0 +1,102 @@
+"""The permission and ownership arguments of `chmod()` and `chown()`."""
+
+from __future__ import annotations
+
+import operator as _operator
+import typing as _ty
+
+__all__ = ["UNCHANGED", "parse_mode", "parse_owner"]
+
+
+#: A `st_mode` is 16 bits: four of file type, twelve of permissions.
+_MODE_MASK = 0o177777
+
+
+def parse_mode(mode: _ty.Union[int, str]) -> int:
+    """Normalize a permission `mode` to an int, parsing `str` as **octal**.
+
+    `chmod("0755")` is the spelling everyone actually writes a mode in --
+    `chmod(1)`, Ansible, Dockerfiles, every shell script -- and stdlib
+    refuses it (`TypeError: 'str' object cannot be interpreted as an
+    integer`). This library accepts it, which makes the base explicit and
+    non-negotiable rather than leaving it to each call site.
+
+    **Why base 8 is mandatory here, and never a plain `int()`:** `"0755"`
+    parsed as decimal is 755, which is `0o1363` -- a different *and valid*
+    mode. Nothing would raise; the file would just end up with permissions
+    nobody intended. That is exactly why stdlib declines strings, so the
+    only safe way to accept them is to parse them one way, in one place.
+
+    Accepts an optional `0o`/`0O` prefix. Anything outside `[0-7]` raises
+    `ValueError` rather than being coerced -- a mode is not a number that
+    happens to be written in octal, it is octal.
+
+    An `int` passes through (including `0o755`, which *is* an int by the time
+    it gets here -- the literal is resolved by the parser, so `chmod(0o755)`
+    and `chmod("0755")` agree). A `bool` is `TypeError`, and a number that
+    cannot be a mode (negative, or wider than the 16 bits of a `st_mode`) is
+    `ValueError`, for an `int` and a `str` alike. The file-type bits of a
+    `st_mode` are in range, as `os.chmod` accepts them; `stat.S_IMODE()` drops
+    them.
+    """
+    if isinstance(mode, bool):
+        raise TypeError("a mode is an int or an octal str, not bool")
+    if isinstance(mode, str):
+        text = mode.strip()
+        if text[:2].lower() == "0o":
+            text = text[2:]
+        if not text or any(character not in "01234567" for character in text):
+            raise ValueError(f"invalid octal mode: {mode!r}")
+        value = int(text, 8)
+    else:
+        value = _operator.index(mode)
+    if not 0 <= value <= _MODE_MASK:
+        raise ValueError(f"mode out of range (0 to {_MODE_MASK:#o}): {mode!r}")
+    return value
+
+
+#: Canonical "leave this ownership field unchanged" sentinel for `chown()`.
+#: `None` is the API-level spelling; `-1` is accepted too because that is
+#: `os.chown`'s own sentinel and callers coming from it reach for it.
+UNCHANGED = None
+
+
+#: `uid_t` and `gid_t` are 32 bits wide.
+_ID_MAX = 0xFFFFFFFF
+
+
+def parse_owner(
+    uid: _ty.Union[int, str, None], gid: _ty.Union[int, str, None]
+) -> "_ty.Tuple[_ty.Optional[int], _ty.Optional[int]]":
+    """Normalize a `chown()` uid/gid pair to canonical `int | None`.
+
+    `None` means "leave unchanged". `-1` is accepted as an alias for it,
+    since that is how `os.chown` spells the same thing and callers arriving
+    from the stdlib reach for it out of habit.
+
+    The point of centralizing this is that **every backend spells
+    "unchanged" differently** -- `os.chown` wants `-1`, SFTP `setstat` wants
+    the field omitted from the attrs entirely, and other middlewares want
+    `None`. If each scheme translated the caller's input itself, that is
+    three chances for the semantics to disagree. Normalizing once on `Path`
+    means a backend's `_chown()` receives an already-canonical pair and only
+    has to convert to its own wire spelling.
+
+    A `str` is passed through as a *name* (`shutil.chown` accepts user and
+    group names, and it is useful not to force a caller to resolve them) --
+    backends that cannot resolve names should say so rather than guess.
+    """
+
+    def _one(value):
+        if value is None or isinstance(value, str):
+            return value
+        if isinstance(value, bool):
+            raise TypeError("an owner is an id, a name or None, not bool")
+        value = _operator.index(value)
+        if value == -1:
+            return None
+        if not 0 <= value <= _ID_MAX:
+            raise ValueError(f"id out of range (0 to {_ID_MAX}): {value!r}")
+        return value
+
+    return _one(uid), _one(gid)

pathapi/_stubs.py

@@ -0,0 +1,76 @@
+"""Placeholders for the methods a subclass has to supply."""
+
+from __future__ import annotations
+
+import functools as _functools
+import typing as _ty
+
+__all__ = ["derived_from", "notimplemented", "primitive"]
+
+#: Set on every function that is only the default of a primitive;
+#: `protocols.supports()` reads it.
+STUB_ATTR = "__pathapi_stub__"
+
+
+def primitive(method):
+    """Mark `method` as the default of a primitive: it raises
+    `NotImplementedError`, and a class that does not replace it does not
+    implement the primitive."""
+    setattr(method, STUB_ATTR, True)
+    return method
+
+
+def notimplemented(method):
+    """Mark a method as the stub of a primitive. Used bare (`@notimplemented`)
+    or with the reason a backend gives (`@notimplemented("why")`); calling the
+    stub raises `NotImplementedError` with the reason, or with the method's
+    name."""
+    if isinstance(method, str):
+        reason = method
+        return lambda function: _stub(function, reason)
+    return _stub(method, None)
+
+
+def _stub(method, reason):
+    @_functools.wraps(method)
+    def _notimplemented(*args, **kwargs):
+        raise NotImplementedError(
+            reason or f"Method not implemented: {method.__name__}"
+        )
+
+    setattr(_notimplemented, STUB_ATTR, True)
+    return _notimplemented
+
+
+#: Set by `derived_from` on a default that only wraps other primitives.
+DERIVED_ATTR = "__pathapi_derived_from__"
+
+
+def derived_from(*primitives: str):
+    """Mark a method as built on other primitives of the class, such as an
+    `iterdir()` that lists through `_listdir()`: `protocols.supports()` counts
+    it as implemented only when one of those primitives is."""
+
+    def mark(function):
+        setattr(function, DERIVED_ATTR, primitives)
+        return function
+
+    return mark
+
+
+def derivation(function: object) -> "tuple[str, ...]":
+    """The primitives `function` is built on (see `derived_from`), or `()`."""
+    return getattr(function, DERIVED_ATTR, ())
+
+
+def is_stub(function: object) -> bool:
+    """Whether `function` is the default of a primitive (see `primitive`)."""
+    return getattr(function, STUB_ATTR, False) is True
+
+
+def _unimplemented(name: str) -> _ty.NoReturn:
+    """Raise the error `notimplemented` raises for `name`. A protocol stub
+    returns this call rather than `...` or `raise NotImplementedError`, which
+    mypy and pyright read as "abstract": a class that subclasses the protocol
+    explicitly then cannot be instantiated."""
+    raise NotImplementedError(f"Method not implemented: {name}")