objpath 0.1.0__py3-none-any.whl

objpath/_keys.py

@@ -0,0 +1,119 @@
+"""Which keys of a prefix a directory walk can reach.
+
+A walk lists one level at a time with a delimiter, so it never visits a key
+whose name has an empty, `.` or `..` segment, the subtree below a key that is
+also an object, or the content of a key that ends in the delimiter. A flat
+listing of the prefix holds all of them.
+"""
+
+from __future__ import annotations
+
+import contextlib as _contextlib
+import errno as _errno
+import threading as _threading
+import typing as _ty
+
+from pathapi import providers as _providers
+
+from .exceptions import UnreachableKeysError
+
+_state = _threading.local()
+
+
+def unreachable_keys(
+    prefix: str, entries: "_ty.Iterable[tuple[str, int]]"
+) -> "list[str]":
+    """The keys among `entries` (`(key, size)` pairs, a flat listing of
+    `prefix`) that a walk of the directory `prefix` never visits.
+
+    `prefix` is `"dir/"`, or `""` for a bucket or container root. A key is
+    reached when every name below the prefix is one path component, no
+    directory on the way is also an object (the object wins and its subtree is
+    not listed), and a key ending in `/` is an empty marker rather than data.
+    The prefix's own marker (`prefix` itself) is reached.
+    """
+    entries = list(entries)
+    keys = {key for key, _size in entries}
+    unreachable = []
+    for key, size in entries:
+        rest = key[len(prefix) :]
+        if not rest:
+            continue
+        *directories, leaf = rest.split("/")
+        marker = leaf == ""
+        if not all(_providers.is_safe_child_name(name) for name in directories) or (
+            not marker and not _providers.is_safe_child_name(leaf)
+        ):
+            unreachable.append(key)
+        elif marker and size:
+            unreachable.append(key)
+        elif any(
+            prefix + "/".join(directories[:depth]) in keys
+            for depth in range(1, len(directories) + 1)
+        ):
+            unreachable.append(key)
+    return unreachable
+
+
+def refusal(path, action: str, keys: "list[str]") -> UnreachableKeysError:
+    """The error for `action` ("copy" or "remove") on a prefix that holds
+    `keys` a directory walk cannot reach; nothing has been changed."""
+    shown = ", ".join(repr(key) for key in keys[:5])
+    more = f" and {len(keys) - 5} more" if len(keys) > 5 else ""
+    return UnreachableKeysError(
+        _errno.EINVAL,
+        f"cannot {action} a prefix holding keys a listing does not show "
+        f"({shown}{more}); nothing was changed",
+        str(path),
+    )
+
+
+def object_key(path: str) -> str:
+    """The object key a path text names: every leading `/` dropped and exactly
+    one trailing `/`. `dir/` is the key `dir`, the way pathlib drops a trailing
+    slash, so `dir/` the marker object and `dir` the prefix are not two names;
+    `dir//` is the key `dir/`. Interior empty segments (`a//b`) are literal key
+    bytes and stay."""
+    key = path.lstrip("/")
+    return key[:-1] if key.endswith("/") else key
+
+
+def parse_names(path: str) -> "tuple[str, ...]":
+    """The segments of a path text: `()` for the empty path, `("", "")` for
+    the root, `("", *names)` for a rooted path and `names` for a relative one.
+    The names are those of `object_key(path)`, an interior empty name among
+    them; a `.` name is dropped, as pathlib drops it."""
+    names = [name for name in object_key(path).split("/") if name != "."]
+    if names == [""]:
+        names = []
+    if path.startswith("/"):
+        return ("", *names) if names else ("", "")
+    return tuple(names)
+
+
+def split_names(text: str) -> "tuple[str, ...]":
+    """The segments a joined text spells, with no name dropped: the inverse of
+    `"/".join(segments)`, which a trailing empty name and an interior one
+    survive."""
+    if text in ("", "."):
+        return ()
+    return tuple(text.split("/"))
+
+
+@_contextlib.contextmanager
+def checked_copy(path, recursive: bool):
+    """Around `Path.copy()` of an object-store `path`: a recursive copy of a
+    prefix is refused, before anything is created, when it holds keys the
+    walk would leave behind. Children are copied through the same method;
+    only the outermost call checks."""
+    if not recursive or getattr(_state, "copying", False):
+        yield
+        return
+    unreachable = path._unreachable_keys()
+    if unreachable:
+        raise refusal(path, "copy", unreachable)
+    _state.copying = True
+    try:
+        yield
+    finally:
+        _state.copying = False

objpath/_optional.py

@@ -0,0 +1,60 @@
+"""Client libraries a store needs and the extra that installs them.
+
+A path always constructs; it does pure-path work (joins, parents, comparison)
+without its client library, and the first operation that needs the library
+raises the `ImportError` built here.
+"""
+
+from __future__ import annotations
+
+import importlib as _importlib
+
+
+def missing_extra(package: str, extra: str, cause: "BaseException | None" = None):
+    """The `ImportError` for a client library that cannot be imported, naming
+    the extra to install."""
+    reason = f" ({cause})" if cause is not None else ""
+    return ImportError(
+        f"{package} could not be imported{reason}; the '{extra}' extra provides "
+        f'it: pip install "objpath[{extra}]"',
+        name=package,
+    )
+
+
+class _Unavailable:
+    """Stands in for a client module that cannot be imported: reading any
+    attribute of it raises the `ImportError` of `missing_extra()`."""
+
+    __slots__ = ("_package", "_extra", "_cause")
+
+    def __init__(self, package: str, extra: str, cause: BaseException):
+        self._package = package
+        self._extra = extra
+        self._cause = cause
+
+    def __getattr__(self, name: str):
+        if name.startswith("__"):
+            # Introspection (`inspect`, `copy`, doctest) probes dunders.
+            raise AttributeError(name)
+        raise missing_extra(self._package, self._extra, self._cause) from self._cause
+
+    def __repr__(self) -> str:
+        return f"<{self._package}: not installed, needs the {self._extra!r} extra>"
+
+
+def import_or_stub(package: str, extra: str):
+    """The module `package`, or a stand-in that raises `missing_extra()` on
+    first use when it cannot be imported."""
+    try:
+        return _importlib.import_module(package)
+    except ImportError as error:
+        return _Unavailable(package, extra, error)
+
+
+def import_client(package: str, extra: str):
+    """The module `package`, imported at the point of use; the `ImportError`
+    of `missing_extra()` when it cannot be."""
+    try:
+        return _importlib.import_module(package)
+    except ImportError as error:
+        raise missing_extra(package, extra, error) from error

objpath/_places.py

@@ -0,0 +1,26 @@
+"""The bucket or container a path is in, and how a pickled path gets it back."""
+
+from __future__ import annotations
+
+
+def check_place(kind: str, value, donor, owner: str) -> str:
+    """The name of the bucket or container (`kind`) that the constructor of
+    `owner` was given as `value`, else the one of the path `donor` it is
+    joined from. `TypeError` when there is none or it is not a string,
+    `ValueError` when it is empty or holds a `/`."""
+    if value is None:
+        if donor is None:
+            raise TypeError(f"{owner} needs {kind}= (or a segment that is an {owner})")
+        return donor._place
+    if not isinstance(value, str):
+        raise TypeError(f"{kind}= must be a str, not {type(value).__name__!r}")
+    if not value or "/" in value:
+        raise ValueError(f"{kind}= must be a name with no '/' in it, not {value!r}")
+    return value
+
+
+def rebuild_path(cls, segments, keywords):
+    """Unpickles a path: `cls(**keywords)` with the names it had."""
+    path = cls(**keywords)
+    path._segments = segments
+    return path

objpath/_reader.py

@@ -0,0 +1,83 @@
+"""The ranged reader of an object stream."""
+
+from __future__ import annotations
+
+import io as _io
+
+READ_CHUNK = 4 * 1024**2
+"""Bytes of an object that one ranged request of a streamed read asks for."""
+
+
+class RangeReader(_io.RawIOBase):
+    """Reads an object as it is asked for, in ranged requests of `chunk` bytes,
+    so a read holds one chunk and not the object, and the stream can seek.
+
+    `fetch(start, length)` returns the bytes of the object from `start`, at
+    most `length`, and nothing at or past its end; it raises the `OSError` a
+    failed request means. `size()` is the object's size, asked only by
+    `seek(..., SEEK_END)`. `first` is the first chunk, already fetched."""
+
+    def __init__(self, fetch, size, first=b"", chunk=None):
+        super().__init__()
+        chunk = chunk or READ_CHUNK
+        self._fetch, self._size_of, self._chunk_size = fetch, size, chunk
+        self._start, self._pos = 0, 0
+        self._view = memoryview(first)
+        # A first chunk that falls short is the whole object.
+        self._size = len(first) if len(first) < chunk else None
+
+    def readable(self):
+        return True
+
+    def seekable(self):
+        return True
+
+    def tell(self):
+        self._check_open()
+        return self._pos
+
+    def seek(self, offset, whence=_io.SEEK_SET):
+        self._check_open()
+        if whence == _io.SEEK_SET:
+            pos = offset
+        elif whence == _io.SEEK_CUR:
+            pos = self._pos + offset
+        elif whence == _io.SEEK_END:
+            if self._size is None:
+                self._size = self._size_of()
+            pos = self._size + offset
+        else:
+            raise ValueError(f"invalid whence ({whence}, should be 0, 1 or 2)")
+        if pos < 0:
+            raise ValueError(f"negative seek value {pos}")
+        self._pos = pos
+        return pos
+
+    def readinto(self, buffer):
+        self._check_open()
+        if not len(buffer):
+            return 0
+        if not self._start <= self._pos < self._start + len(self._view):
+            if self._size is not None and self._pos >= self._size:
+                return 0
+            # The chunk that is done with goes before the next one arrives.
+            self._view = memoryview(b"")
+            data = self._fetch(self._pos, self._chunk_size)
+            self._start, self._view = self._pos, memoryview(data)
+            if len(data) < self._chunk_size:
+                self._size = self._pos + len(data)
+            if not data:
+                return 0
+        at = self._pos - self._start
+        count = min(len(buffer), len(self._view) - at)
+        buffer[:count] = self._view[at : at + count]
+        self._pos += count
+        return count
+
+    def _check_open(self):
+        if self.closed:
+            raise ValueError("I/O operation on closed file.")
+
+    def close(self):
+        self._view = memoryview(b"")
+        super().close()