objpath 0.1.0__py3-none-any.whl

objpath/_az_errors.py

@@ -0,0 +1,110 @@
+"""How a failure of Azure Blob Storage becomes an `OSError`: the status of an
+error reply, the SDK's report of a connection failure, and the translation of
+both."""
+
+from __future__ import annotations
+
+import contextlib as _contextlib
+import errno as _errno
+import sys as _sys
+
+from . import _failures
+
+
+def http_status(error: BaseException) -> "int | None":
+    """The HTTP status of an `azure.core.exceptions.HttpResponseError`
+    (`ResourceNotFoundError`, `ResourceExistsError`, ...), read from its
+    `status_code` attribute -- or its type when the SDK set none -- so the
+    SDK need not be importable to classify it. None for anything that is
+    not an error reply."""
+    if isinstance(error, OSError):
+        return None
+    status = getattr(error, "status_code", None)
+    if isinstance(status, int) and not isinstance(status, bool):
+        return status
+    try:
+        from azure.core import exceptions as _azexc
+    except ImportError:
+        return None
+    if isinstance(error, _azexc.ResourceNotFoundError):
+        return 404
+    if isinstance(error, _azexc.ResourceExistsError):
+        return 409
+    if isinstance(error, _azexc.ClientAuthenticationError):
+        return 401
+    if isinstance(error, _azexc.HttpResponseError):
+        return 500
+    return None
+
+
+def transport_kind(error: BaseException) -> "str | None":
+    """Which `_failures.transport_error()` kind `error` is when it is the SDK's
+    report of a connection failure (not of a reply), else None."""
+    # An SDK error exists only once its module is loaded, so there is nothing
+    # to import here.
+    azexc = _sys.modules.get("azure.core.exceptions")
+    if azexc is None:
+        return None
+    timeouts = tuple(
+        getattr(azexc, name)
+        for name in ("ServiceRequestTimeoutError", "ServiceResponseTimeoutError")
+        if hasattr(azexc, name)
+    )
+    if isinstance(error, timeouts):
+        return _failures.TIMEOUT
+    if isinstance(error, azexc.ServiceRequestError):
+        # The request could not be sent: no connection, no name, no route.
+        return (
+            _failures.TIMEOUT
+            if _failures.mentions_timeout(error)
+            else _failures.UNREACHABLE
+        )
+    if isinstance(error, azexc.ServiceResponseError):
+        # Sent, but the answer did not arrive whole.
+        return (
+            _failures.TIMEOUT
+            if _failures.mentions_timeout(error)
+            else _failures.INTERRUPTED
+        )
+    incomplete = getattr(azexc, "IncompleteReadError", None)
+    if incomplete is not None and isinstance(error, incomplete):
+        return _failures.INTERRUPTED
+    return None
+
+
+def oserror(error: BaseException, path, *, create=False):
+    """The OSError an error reply or a connection failure means for `path`,
+    or None for any other exception (a missing SDK, bad configuration, a
+    bug), which must propagate as itself rather than read as "no such
+    file". `create`: the reply answers a conditional create, where 409/412
+    mean the blob exists (elsewhere a 412 is e.g. a lease held by someone
+    else). A request that ran out of time is TimeoutError, an endpoint that
+    cannot be reached ConnectionError. Raise it `from None`."""
+    kind = transport_kind(error)
+    if kind is not None:
+        return _failures.transport_error(kind, "Azure", path, error)
+    status = http_status(error)
+    if status is None:
+        return None
+    if status == 404:
+        return FileNotFoundError(
+            _errno.ENOENT, f"No such file or directory ({error})", str(path)
+        )
+    if status in (401, 403):
+        return PermissionError(_errno.EACCES, str(error), str(path))
+    if create and status in (409, 412):
+        return FileExistsError(_errno.EEXIST, f"File exists ({error})", str(path))
+    if status in (408, 504):
+        return _failures.transport_error(_failures.TIMEOUT, "Azure", path, error)
+    return OSError(_errno.EIO, f"Azure request failed: {error}", str(path))
+
+
+@_contextlib.contextmanager
+def translate_errors(path, *, create=False):
+    try:
+        yield
+    except Exception as error:
+        translated = oserror(error, path, create=create)
+        if translated is None:
+            raise
+        raise translated from None

objpath/_clients.py

@@ -0,0 +1,108 @@
+"""What the backend of every store shares: the context manager, the client
+built on first use, and what a pickled or copied backend keeps."""
+
+from __future__ import annotations
+
+import threading as _threading
+
+#: Backend attributes that are the live client and what guards it: left out
+#: of a pickled or copied backend, which builds its own on first use.
+_LIVE = frozenset({"_client", "_client_lock", "__dict__", "__weakref__"})
+
+
+def lazy_client(backend, build):
+    """`backend._client`, made by `build()` the first time under
+    `backend._client_lock` so that threads racing for it build one."""
+    client = backend._client
+    if client is None:
+        with backend._client_lock:
+            client = backend._client
+            if client is None:
+                client = backend._client = build()
+    return client
+
+
+def backend_state(backend) -> dict:
+    """What a pickled or copied backend keeps: its slots and `__dict__`,
+    without the client it built and the lock that guarded the build."""
+    state = {}
+    for cls in type(backend).__mro__:
+        slots = getattr(cls, "__slots__", ())
+        for name in (slots,) if isinstance(slots, str) else slots:
+            if name not in _LIVE and hasattr(backend, name):
+                state[name] = getattr(backend, name)
+    state.update(
+        (name, value)
+        for name, value in getattr(backend, "__dict__", {}).items()
+        if name not in _LIVE
+    )
+    return state
+
+
+def restore_backend(backend, state: dict) -> None:
+    """The inverse of `backend_state()`: a backend with no client yet."""
+    for name, value in state.items():
+        setattr(backend, name, value)
+    backend._client = None
+    backend._client_lock = _threading.Lock()
+
+
+class ClientBackend(object):
+    """The base of the backend contract of every store: a context manager
+    whose `close()` releases what the backend holds, and the `picklable` flag.
+
+    `picklable` says whether a path that holds the backend pickles it. It is
+    `False`: the options of a client carry credentials, so a pickled path
+    names its place only and the receiving process builds the default backend.
+    """
+
+    # Weakly referenceable so a path can be told which backends it built.
+    __slots__ = ("__weakref__",)
+
+    picklable = False
+
+    def close(self) -> None:
+        """Releases what this backend holds. Nothing here; a backend that holds
+        a client closes it. Harmless when called again; the backend stays
+        usable."""
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc_info) -> None:
+        self.close()
+
+
+class LazyClientBackend(ClientBackend):
+    """A backend that builds its SDK client the first time it is asked for it
+    (`_build_client()`), once however many threads ask first, and keeps it.
+
+    `close()` closes the client when the SDK's has a `close()`, and the next
+    `client()` builds a new one. A pickled or copied backend keeps its
+    options and builds its own client."""
+
+    __slots__ = ("_client", "_client_lock")
+
+    def __init__(self) -> None:
+        self._client = None
+        self._client_lock = _threading.Lock()
+
+    def client(self):
+        """The SDK client every call of a path goes through."""
+        return lazy_client(self, self._build_client)
+
+    def _build_client(self):
+        raise NotImplementedError
+
+    def close(self) -> None:
+        with self._client_lock:
+            client, self._client = self._client, None
+        closer = getattr(client, "close", None)
+        if callable(closer):
+            closer()
+
+    def __getstate__(self):
+        return backend_state(self)
+
+    def __setstate__(self, state):
+        restore_backend(self, state)

objpath/_digests.py

@@ -0,0 +1,10 @@
+"""The digests a store reports."""
+
+from __future__ import annotations
+
+import base64 as _base64
+
+
+def digest_hex(encoded: str) -> str:
+    """The hex digest of `encoded`, the base64 text a store reports one in."""
+    return _base64.b64decode(encoded).hex()

objpath/_failures.py

@@ -0,0 +1,84 @@
+"""How a failure of the connection to a store becomes an `OSError`, and how a
+stream tells that its object changed."""
+
+from __future__ import annotations
+
+import errno as _errno
+
+from .exceptions import ObjectChangedError
+
+#: What a failure of the connection to the store is, as `transport_error()` raises
+#: it: the request ran out of time, the endpoint was unreachable, the connection
+#: broke after the store began to answer, or anything else the HTTP client reported.
+TIMEOUT, UNREACHABLE, INTERRUPTED, FAILED = (
+    "timeout",
+    "unreachable",
+    "interrupted",
+    "failed",
+)
+
+_TRANSPORT = {
+    TIMEOUT: (TimeoutError, _errno.ETIMEDOUT, "request timed out"),
+    UNREACHABLE: (ConnectionError, _errno.EHOSTUNREACH, "endpoint unreachable"),
+    INTERRUPTED: (
+        ConnectionResetError,
+        _errno.ECONNRESET,
+        "connection lost before the response was complete",
+    ),
+    FAILED: (OSError, _errno.EIO, "request failed"),
+}
+
+
+def transport_error(kind: str, store: str, path, error: BaseException) -> OSError:
+    """The `OSError` for a transport failure of `store` ("S3", "GCS", "Azure")
+    on `path`: `TimeoutError`, `ConnectionError`, `ConnectionResetError` or
+    plain `OSError` by `kind`, with the path as `filename`. Only the type name
+    of `error` reaches the message: an HTTP client's own text carries the
+    request URL, and with it any query-string credential. Raise it
+    `from None`."""
+    cls, number, text = _TRANSPORT[kind]
+    return cls(number, f"{store} {text} ({type(error).__name__})", str(path))
+
+
+def mentions_timeout(error: BaseException) -> bool:
+    """Whether `error`, or an exception it wraps (`__cause__`, `__context__`,
+    an SDK's `inner_exception` or `cause`, a `reason` or an argument), is a
+    timeout of any HTTP client: a type named `Timeout`, `ReadTimeout`,
+    `ConnectTimeoutError`, ..., or `TimeoutError` itself. The client libraries
+    are matched by name so none has to be imported. urllib3's
+    `NewConnectionError` derives from its `ConnectTimeoutError` but means the
+    connection was refused or the name did not resolve: it is not one."""
+    pending = [error]
+    for _ in range(8):
+        if not pending:
+            break
+        current = pending.pop()
+        if current is None:
+            continue
+        names = {cls.__name__ for cls in type(current).__mro__}
+        if "NewConnectionError" in names:
+            continue
+        if any(
+            name.endswith(("Timeout", "TimeoutError")) or name == "timeout"
+            for name in names
+        ):
+            return True
+        for attr in ("__cause__", "__context__", "inner_exception", "cause", "reason"):
+            pending.append(getattr(current, attr, None))
+        pending.extend(
+            arg
+            for arg in getattr(current, "args", ())
+            if isinstance(arg, BaseException)
+        )
+    return False
+
+
+def changed_error(path) -> ObjectChangedError:
+    """The error for a stream whose object was replaced while it was being
+    read: a read is one version of the object, and what follows the change is
+    another's. `ESTALE` where the platform has it, else `EIO`."""
+    return ObjectChangedError(
+        getattr(_errno, "ESTALE", _errno.EIO),
+        "the object changed while it was being read",
+        str(path),
+    )