ringo-task-queue 0.1.0.dev6__py3-none-win_amd64.whl → 0.1.0.dev7__py3-none-win_amd64.whl

ringo_task_queue/errors.py

@@ -1,159 +1,159 @@
-"""Public exception hierarchy for the Ringo Task Queue Python SDK.
-
-All SDK transport failures derive from :class:`RingoError` and carry one of
-the stable public codes from ``docs/contracts/errors.md``. gRPC status
-details (``ringo.v1.ErrorDetail``) are preferred over the coarser gRPC code,
-exactly as the error contract requires.
-"""
-
-from __future__ import annotations
-
-from typing import Mapping
-
-import grpc
-from grpc_status import rpc_status
-
-from ._proto.ringo.v1 import queue_pb2
-
-
-class RingoError(Exception):
-    """Base class for every SDK-raised transport/protocol error."""
-
-    #: Stable public code (see docs/contracts/errors.md).
-    code = "INTERNAL"
-
-    def __init__(
-        self,
-        message: str = "",
-        *,
-        request_id: str | None = None,
-        metadata: Mapping[str, str] | None = None,
-        grpc_code: grpc.StatusCode | None = None,
-    ) -> None:
-        super().__init__(message)
-        self.message = message
-        self.request_id = request_id
-        self.metadata = dict(metadata) if metadata else {}
-        self.grpc_code = grpc_code
-
-    def __repr__(self) -> str:  # pragma: no cover - debugging aid
-        return f"{type(self).__name__}(code={self.code!r}, message={self.message!r})"
-
-
-class InvalidArgumentError(RingoError):
-    code = "INVALID_ARGUMENT"
-
-
-class DuplicateError(RingoError):
-    code = "DUPLICATE"
-
-
-class NotFoundError(RingoError):
-    code = "NOT_FOUND"
-
-
-class ConflictError(RingoError):
-    code = "CONFLICT"
-
-
-class LeaseLostError(RingoError):
-    code = "LEASE_LOST"
-
-
-class UnavailableError(RingoError):
-    code = "UNAVAILABLE"
-
-
-class DeadlineExceededError(RingoError):
-    code = "DEADLINE_EXCEEDED"
-
-
-class IncompatibleVersionError(RingoError):
-    code = "INCOMPATIBLE_VERSION"
-
-
-class InternalError(RingoError):
-    code = "INTERNAL"
-
-
-_CODE_TO_ERROR: dict[int, type[RingoError]] = {
-    queue_pb2.ERROR_CODE_INVALID_ARGUMENT: InvalidArgumentError,
-    queue_pb2.ERROR_CODE_DUPLICATE: DuplicateError,
-    queue_pb2.ERROR_CODE_NOT_FOUND: NotFoundError,
-    queue_pb2.ERROR_CODE_CONFLICT: ConflictError,
-    queue_pb2.ERROR_CODE_LEASE_LOST: LeaseLostError,
-    queue_pb2.ERROR_CODE_UNAVAILABLE: UnavailableError,
-    queue_pb2.ERROR_CODE_DEADLINE_EXCEEDED: DeadlineExceededError,
-    queue_pb2.ERROR_CODE_INCOMPATIBLE_VERSION: IncompatibleVersionError,
-    queue_pb2.ERROR_CODE_INTERNAL: InternalError,
-}
-
-# gRPC codes that map unambiguously onto a single public Ringo code. Other
-# gRPC codes raise the base RingoError without inventing a more specific
-# public code (docs/contracts/errors.md).
-_GRPC_FALLBACK: dict[grpc.StatusCode, type[RingoError]] = {
-    grpc.StatusCode.INVALID_ARGUMENT: InvalidArgumentError,
-    grpc.StatusCode.NOT_FOUND: NotFoundError,
-    grpc.StatusCode.ALREADY_EXISTS: DuplicateError,
-    grpc.StatusCode.ABORTED: LeaseLostError,
-    grpc.StatusCode.UNAVAILABLE: UnavailableError,
-    grpc.StatusCode.DEADLINE_EXCEEDED: DeadlineExceededError,
-    grpc.StatusCode.INTERNAL: InternalError,
-}
-
-
-def error_from_detail(detail: queue_pb2.ErrorDetail) -> RingoError:
-    """Build the mapped exception from a ``ringo.v1.ErrorDetail`` message."""
-    cls = _CODE_TO_ERROR.get(detail.code, RingoError)
-    return cls(
-        detail.message,
-        request_id=detail.request_id or None,
-        metadata=detail.metadata,
-    )
-
-
-def map_rpc_error(exc: grpc.aio.AioRpcError) -> RingoError:
-    """Map a gRPC call failure to the stable public exception.
-
-    Prefers the ``ringo.v1.ErrorDetail`` serialized in ``google.rpc.Status``
-    details; falls back to the gRPC code only when details are unavailable.
-    """
-    rich = None
-    try:
-        rich = rpc_status.from_call(exc)
-    except Exception:
-        rich = None
-    if rich is not None:
-        for any_msg in rich.details:
-            if any_msg.Is(queue_pb2.ErrorDetail.DESCRIPTOR):
-                detail = queue_pb2.ErrorDetail()
-                any_msg.Unpack(detail)
-                err = error_from_detail(detail)
-                err.grpc_code = exc.code()
-                return err
-    cls = _GRPC_FALLBACK.get(exc.code(), RingoError)
-    message = exc.details() or str(exc)
-    return cls(message, grpc_code=exc.code())
-
-
-# ---------------------------------------------------------------------------
-# Handler signalling errors (execution outcomes, not transport errors).
-
-
-class RetryTaskError(Exception):
-    """Raise from a handler to retry with an optional per-attempt delay."""
-
-    def __init__(
-        self,
-        message: str = "",
-        *,
-        delay: float | None = None,
-        congestion: bool = False,
-    ) -> None:
-        super().__init__(message)
-        self.delay = delay
-        self.congestion = congestion
-
-
-class PermanentTaskError(Exception):
-    """Raise from a handler to mark the task permanently failed (DEAD)."""
+"""Public exception hierarchy for the Ringo Task Queue Python SDK.
+
+All SDK transport failures derive from :class:`RingoError` and carry one of
+the stable public codes from ``docs/contracts/errors.md``. gRPC status
+details (``ringo.v1.ErrorDetail``) are preferred over the coarser gRPC code,
+exactly as the error contract requires.
+"""
+
+from __future__ import annotations
+
+from typing import Mapping
+
+import grpc
+from grpc_status import rpc_status
+
+from ._proto.ringo.v1 import queue_pb2
+
+
+class RingoError(Exception):
+    """Base class for every SDK-raised transport/protocol error."""
+
+    #: Stable public code (see docs/contracts/errors.md).
+    code = "INTERNAL"
+
+    def __init__(
+        self,
+        message: str = "",
+        *,
+        request_id: str | None = None,
+        metadata: Mapping[str, str] | None = None,
+        grpc_code: grpc.StatusCode | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.request_id = request_id
+        self.metadata = dict(metadata) if metadata else {}
+        self.grpc_code = grpc_code
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        return f"{type(self).__name__}(code={self.code!r}, message={self.message!r})"
+
+
+class InvalidArgumentError(RingoError):
+    code = "INVALID_ARGUMENT"
+
+
+class DuplicateError(RingoError):
+    code = "DUPLICATE"
+
+
+class NotFoundError(RingoError):
+    code = "NOT_FOUND"
+
+
+class ConflictError(RingoError):
+    code = "CONFLICT"
+
+
+class LeaseLostError(RingoError):
+    code = "LEASE_LOST"
+
+
+class UnavailableError(RingoError):
+    code = "UNAVAILABLE"
+
+
+class DeadlineExceededError(RingoError):
+    code = "DEADLINE_EXCEEDED"
+
+
+class IncompatibleVersionError(RingoError):
+    code = "INCOMPATIBLE_VERSION"
+
+
+class InternalError(RingoError):
+    code = "INTERNAL"
+
+
+_CODE_TO_ERROR: dict[int, type[RingoError]] = {
+    queue_pb2.ERROR_CODE_INVALID_ARGUMENT: InvalidArgumentError,
+    queue_pb2.ERROR_CODE_DUPLICATE: DuplicateError,
+    queue_pb2.ERROR_CODE_NOT_FOUND: NotFoundError,
+    queue_pb2.ERROR_CODE_CONFLICT: ConflictError,
+    queue_pb2.ERROR_CODE_LEASE_LOST: LeaseLostError,
+    queue_pb2.ERROR_CODE_UNAVAILABLE: UnavailableError,
+    queue_pb2.ERROR_CODE_DEADLINE_EXCEEDED: DeadlineExceededError,
+    queue_pb2.ERROR_CODE_INCOMPATIBLE_VERSION: IncompatibleVersionError,
+    queue_pb2.ERROR_CODE_INTERNAL: InternalError,
+}
+
+# gRPC codes that map unambiguously onto a single public Ringo code. Other
+# gRPC codes raise the base RingoError without inventing a more specific
+# public code (docs/contracts/errors.md).
+_GRPC_FALLBACK: dict[grpc.StatusCode, type[RingoError]] = {
+    grpc.StatusCode.INVALID_ARGUMENT: InvalidArgumentError,
+    grpc.StatusCode.NOT_FOUND: NotFoundError,
+    grpc.StatusCode.ALREADY_EXISTS: DuplicateError,
+    grpc.StatusCode.ABORTED: LeaseLostError,
+    grpc.StatusCode.UNAVAILABLE: UnavailableError,
+    grpc.StatusCode.DEADLINE_EXCEEDED: DeadlineExceededError,
+    grpc.StatusCode.INTERNAL: InternalError,
+}
+
+
+def error_from_detail(detail: queue_pb2.ErrorDetail) -> RingoError:
+    """Build the mapped exception from a ``ringo.v1.ErrorDetail`` message."""
+    cls = _CODE_TO_ERROR.get(detail.code, RingoError)
+    return cls(
+        detail.message,
+        request_id=detail.request_id or None,
+        metadata=detail.metadata,
+    )
+
+
+def map_rpc_error(exc: grpc.aio.AioRpcError) -> RingoError:
+    """Map a gRPC call failure to the stable public exception.
+
+    Prefers the ``ringo.v1.ErrorDetail`` serialized in ``google.rpc.Status``
+    details; falls back to the gRPC code only when details are unavailable.
+    """
+    rich = None
+    try:
+        rich = rpc_status.from_call(exc)
+    except Exception:
+        rich = None
+    if rich is not None:
+        for any_msg in rich.details:
+            if any_msg.Is(queue_pb2.ErrorDetail.DESCRIPTOR):
+                detail = queue_pb2.ErrorDetail()
+                any_msg.Unpack(detail)
+                err = error_from_detail(detail)
+                err.grpc_code = exc.code()
+                return err
+    cls = _GRPC_FALLBACK.get(exc.code(), RingoError)
+    message = exc.details() or str(exc)
+    return cls(message, grpc_code=exc.code())
+
+
+# ---------------------------------------------------------------------------
+# Handler signalling errors (execution outcomes, not transport errors).
+
+
+class RetryTaskError(Exception):
+    """Raise from a handler to retry with an optional per-attempt delay."""
+
+    def __init__(
+        self,
+        message: str = "",
+        *,
+        delay: float | None = None,
+        congestion: bool = False,
+    ) -> None:
+        super().__init__(message)
+        self.delay = delay
+        self.congestion = congestion
+
+
+class PermanentTaskError(Exception):
+    """Raise from a handler to mark the task permanently failed (DEAD)."""