sharkmagic 0.1.0__py3-none-any.whl

sharkmagic/__init__.py

@@ -0,0 +1,25 @@
+"""Shark SDK for Python (docs/spec/v1/sdk.md). Standard library only.
+
+    from sharkmagic import Shark
+    shark = Shark()                      # SHARK_API_KEY, SHARK_API
+    space = shark.spaces.create(name="demo")
+    print(space.run("echo hi").stdout)
+"""
+
+from ._errors import (AuthenticationError, CapacityError, CommandFailedError, CommandTimeoutError, ConflictError,
+                      CreditsExhaustedError, DurableUnavailableError, IdempotencyMismatchError, InfraError,
+                      InvalidRequestError, LeaseCapError, NotFoundError, OpExpiredError, PermissionDeniedError,
+                      QuotaExceededError, RateLimitError, ServerError, SharkError, SpaceLimitError, UnsupportedError,
+                      WaitTimeoutError)
+from ._errors import ConnectionError
+from ._transport import ROUTES, VERSION, Event, Transport
+from .client import (AccountPorts, AccountSecrets, AsyncShark, Egress, ExecResult, FileEntry, Op, Ports, Shark, Space, SpaceDefaults,
+                     SpaceEgress, SpaceSecrets, new_op_id)
+
+__version__ = VERSION
+__all__ = ["Shark", "AsyncShark", "Space", "SpaceSecrets", "SpaceEgress", "Egress", "AccountSecrets", "SpaceDefaults", "Ports", "AccountPorts", "Op", "ExecResult", "FileEntry", "Event", "Transport", "ROUTES", "new_op_id",
+           "SharkError", "AuthenticationError", "PermissionDeniedError", "NotFoundError", "ConflictError",
+           "IdempotencyMismatchError", "OpExpiredError", "InvalidRequestError", "UnsupportedError", "RateLimitError",
+           "LeaseCapError", "SpaceLimitError", "QuotaExceededError", "CreditsExhaustedError", "ServerError",
+           "CapacityError", "DurableUnavailableError", "CommandFailedError", "InfraError", "CommandTimeoutError",
+           "WaitTimeoutError", "ConnectionError"]

sharkmagic/_errors.py

@@ -0,0 +1,172 @@
+"""Typed errors (docs/spec/v1/sdk.md §5): one class per error.code family."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class SharkError(Exception):
+    """Base of every SDK error. ``code`` is the API's stable error code."""
+
+    def __init__(self, message: str, *, code: str = "", status: int = 0, request_id: str = "",
+                 details: Optional[dict] = None, retryable: bool = False, retry_after: Optional[float] = None):
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status = status
+        self.request_id = request_id
+        self.details = details or {}
+        self.retryable = retryable
+        self.retry_after = retry_after
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(code={self.code!r}, status={self.status}, message={self.message!r})"
+
+
+class AuthenticationError(SharkError):
+    pass
+
+
+class PermissionDeniedError(SharkError):
+    pass
+
+
+class NotFoundError(SharkError):
+    pass
+
+
+class ConflictError(SharkError):
+    pass
+
+
+class IdempotencyMismatchError(ConflictError):
+    pass
+
+
+class OpExpiredError(SharkError):
+    pass
+
+
+class InvalidRequestError(SharkError):
+    pass
+
+
+class UnsupportedError(SharkError):
+    pass
+
+
+class RateLimitError(SharkError):
+    pass
+
+
+class LeaseCapError(RateLimitError):
+    @property
+    def scope(self) -> str:
+        return str(self.details.get("scope", ""))
+
+
+class SpaceLimitError(RateLimitError):
+    pass
+
+
+class QuotaExceededError(SharkError):
+    pass
+
+
+class CreditsExhaustedError(SharkError):
+    pass
+
+
+class ServerError(SharkError):
+    pass
+
+
+class CapacityError(ServerError):
+    pass
+
+
+class DurableUnavailableError(ServerError):
+    pass
+
+
+class ConnectionError(SharkError):  # noqa: A001 - the SDK's own, raised after retries
+    pass
+
+
+class CommandFailedError(SharkError):
+    """Raised by run(..., check=True) when the command exits non-zero."""
+
+    def __init__(self, result: Any):
+        super().__init__(f"command exited {result.exit}", code="command_failed")
+        self.result = result
+        self.exit = result.exit
+        self.stdout = result.stdout
+        self.stderr = result.stderr
+        self.op_id = result.op_id
+
+
+class InfraError(SharkError):
+    pass
+
+
+class CommandTimeoutError(SharkError):
+    pass
+
+
+class WaitTimeoutError(SharkError):
+    """op.wait(timeout=...) ran out of time (code ``wait_timeout``). The command keeps running: wait again,
+    ``op.refresh()``, or ``op.signal()`` it. ``.op_id``, ``.timeout`` (seconds)."""
+
+    def __init__(self, op_id: str, timeout: float):
+        super().__init__(f"op {op_id} still running after {timeout:g} s", code="wait_timeout",
+                         details={"op_id": op_id, "timeout_s": timeout})
+        self.op_id = op_id
+        self.timeout = timeout
+
+
+# code -> class (sdk.md §5)
+CODE_CLASSES = {
+    "unauthenticated": AuthenticationError,
+    "auth_rate_limited": AuthenticationError,
+    "insufficient_scope": PermissionDeniedError,
+    "plan_restriction": PermissionDeniedError,
+    "tenant_not_allowed": PermissionDeniedError,
+    "not_found": NotFoundError,
+    "conflict": ConflictError,
+    "idempotency_mismatch": IdempotencyMismatchError,
+    "idempotency_in_progress": IdempotencyMismatchError,
+    "op_expired": OpExpiredError,
+    "invalid_request": InvalidRequestError,
+    "invalid_op_id": InvalidRequestError,
+    "path_outside_space": InvalidRequestError,
+    "payload_too_large": InvalidRequestError,
+    "precondition_failed": ConflictError,
+    "upgrade_required": InvalidRequestError,
+    "unsupported": UnsupportedError,
+    "rate_limited": RateLimitError,
+    "lease_cap_reached": LeaseCapError,
+    "space_limit_reached": SpaceLimitError,
+    "quota_exceeded": QuotaExceededError,
+    "credits_exhausted": CreditsExhaustedError,
+    "internal": ServerError,
+    "capacity_unavailable": CapacityError,
+    "out_of_capacity": CapacityError,
+    "insufficient_storage": QuotaExceededError,
+    "canceled": CapacityError,
+    "durable_unavailable": DurableUnavailableError,
+}
+
+# HTTP status -> class, for codes this SDK does not know yet
+STATUS_CLASSES = {400: InvalidRequestError, 401: AuthenticationError, 402: CreditsExhaustedError, 403: PermissionDeniedError,
+                  404: NotFoundError, 409: ConflictError, 410: OpExpiredError, 412: ConflictError, 413: InvalidRequestError,
+                  422: UnsupportedError, 429: RateLimitError}
+
+
+def error_class(code: str, status: int) -> type:
+    if code in CODE_CLASSES:
+        return CODE_CLASSES[code]
+    if status in STATUS_CLASSES:
+        return STATUS_CLASSES[status]
+    if status >= 500:
+        return ServerError
+    return SharkError