superartifacts 0.1.0__py3-none-any.whl

superartifacts/__init__.py

@@ -0,0 +1,39 @@
+"""Python SDK for the Super Artifacts REST API. https://superartifacts.app/docs/sdks/python"""
+
+from ._client import AsyncSuperArtifacts, SuperArtifacts, __version__
+from ._errors import (
+    APIConnectionError,
+    APITimeoutError,
+    AuthenticationError,
+    ConflictError,
+    InternalError,
+    InvalidArgumentsError,
+    NotFoundError,
+    PayloadTooLargeError,
+    PermissionError,
+    PlanLimitError,
+    RateLimitError,
+    ScopeRequiredError,
+    SuperArtifactsError,
+)
+from ._generated import models
+
+__all__ = [
+    "APIConnectionError",
+    "APITimeoutError",
+    "AsyncSuperArtifacts",
+    "AuthenticationError",
+    "ConflictError",
+    "InternalError",
+    "InvalidArgumentsError",
+    "NotFoundError",
+    "PayloadTooLargeError",
+    "PermissionError",
+    "PlanLimitError",
+    "RateLimitError",
+    "ScopeRequiredError",
+    "SuperArtifacts",
+    "SuperArtifactsError",
+    "__version__",
+    "models",
+]

superartifacts/_client.py

@@ -0,0 +1,280 @@
+"""The two clients. One retry policy, written once, driven by two small loops."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import random
+import time
+import uuid
+from importlib.metadata import PackageNotFoundError, version
+from itertools import count
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from ._errors import (
+    APIConnectionError,
+    APITimeoutError,
+    AuthenticationError,
+    error_from,
+    parse_seconds,
+)
+from ._generated.resources import AsyncResources, SyncResources
+from ._helpers import OMIT
+
+DEFAULT_BASE_URL = "https://superartifacts.app"
+MAX_RETRY_AFTER = 60.0
+BACKOFF_BASE = 0.5
+BACKOFF_MAX = 8.0
+
+try:
+    __version__ = version("superartifacts")
+except PackageNotFoundError:
+    # Vendored without its metadata; only the User-Agent reads this.
+    __version__ = "0.0.0"
+
+
+def _backoff(attempt: int) -> float:
+    """Exponential, jittered over the top half: 0.25-0.5 s, 0.5-1 s, ..., 4-8 s."""
+    ceiling = min(BACKOFF_BASE * 2**attempt, BACKOFF_MAX)
+    return random.uniform(ceiling / 2, ceiling)
+
+
+def _connection_error(exc: httpx.TransportError) -> APIConnectionError:
+    if isinstance(exc, httpx.TimeoutException):
+        return APITimeoutError(
+            "The request timed out. Raise `timeout`, or try again.", status=0, code="timeout"
+        )
+    return APIConnectionError(
+        f"Could not reach the API ({type(exc).__name__}). Try again.",
+        status=0,
+        code="connection_error",
+    )
+
+
+def _answer(response: httpx.Response) -> dict[str, Any]:
+    if response.status_code == 304:
+        return {"etag": response.headers.get("etag"), "notModified": True}
+    # An upload PUT may answer with no JSON at all; its status said what mattered.
+    try:
+        body = response.json()
+    except ValueError:
+        return {}
+    answer = body if isinstance(body, dict) else {"data": body}
+    if "etag" in response.headers:
+        answer.update(etag=response.headers["etag"], notModified=False)
+    return answer
+
+
+class _Base:
+    def __init__(self, api_key: str | None, base_url: str, timeout: float, max_retries: int):
+        key = api_key or os.environ.get("SUPERARTIFACTS_API_KEY")
+        if not key:
+            raise AuthenticationError(
+                "No API key. Pass api_key= or set SUPERARTIFACTS_API_KEY. "
+                "Create one at https://superartifacts.app/settings/api-keys.",
+                status=0,
+                code="missing_api_key",
+            )
+        self._api_key = key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+    def _prepare(
+        self,
+        method: str,
+        path: str,
+        path_params: dict[str, Any] | None,
+        query: dict[str, Any] | None,
+        body: dict[str, Any] | None,
+        nullable: dict[str, Any] | None,
+        idempotency_key: str | None,
+    ) -> tuple[str, dict[str, Any]]:
+        """The URL and httpx arguments for one operation."""
+        for name, value in (path_params or {}).items():
+            path = path.replace("{" + name + "}", quote(str(value), safe=""))
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": f"superartifacts-python/{__version__}",
+        }
+        # Made here, once, so every retry of this call carries the same key.
+        if method == "POST":
+            headers["Idempotency-Key"] = idempotency_key or str(uuid.uuid4())
+        parts: dict[str, Any] = {"headers": headers}
+        if query:
+            parts["params"] = {k: v for k, v in query.items() if v is not None}
+        if body is not None:
+            parts["json"] = {k: v for k, v in body.items() if v is not None}
+            parts["json"].update({k: v for k, v in (nullable or {}).items() if v is not OMIT})
+        return self.base_url + path, parts
+
+    def _retry_delay(
+        self,
+        method: str,
+        parts: dict[str, Any],
+        attempt: int,
+        status: int | None = None,
+        retry_after: str | None = None,
+    ) -> float | None:
+        """Seconds to wait before another try, or None to stop. `status` None is a network error."""
+        if attempt >= self.max_retries:
+            return None
+        if status == 429:
+            seconds = parse_seconds(retry_after)
+            if seconds is None:
+                return _backoff(attempt)
+            # Past a minute (the hourly email limit) waiting it out would hang the caller:
+            # the RateLimitError comes straight back with retry_after set, as in the TypeScript SDK.
+            return seconds if seconds <= MAX_RETRY_AFTER else None
+        if status not in (None, 502, 503, 504):
+            return None
+        safe = method in ("GET", "DELETE") or "Idempotency-Key" in parts.get("headers", {})
+        return _backoff(attempt) if safe else None
+
+
+class SuperArtifacts(_Base, SyncResources):
+    """Synchronous client. Use it as a context manager, or call `close()`."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        _Base.__init__(self, api_key, base_url, timeout, max_retries)
+        SyncResources.__init__(self)
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.Client()
+
+    def _call(
+        self,
+        method: str,
+        path: str,
+        *,
+        path_params: dict[str, Any] | None = None,
+        query: dict[str, Any] | None = None,
+        body: dict[str, Any] | None = None,
+        nullable: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+        headers: dict[str, Any] | None = None,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        url, parts = self._prepare(
+            method, path, path_params, query, body, nullable, idempotency_key
+        )
+        parts["headers"].update({k: v for k, v in (headers or {}).items() if v is not None})
+        return self._request(method, url, timeout, parts)
+
+    def _request(
+        self, method: str, url: str, timeout: float | None, parts: dict[str, Any]
+    ) -> dict[str, Any]:
+        wait = self.timeout if timeout is None else timeout
+        for attempt in count():
+            try:
+                response = self._http.request(method, url, timeout=wait, **parts)
+            except httpx.TransportError as exc:
+                delay = self._retry_delay(method, parts, attempt)
+                if delay is None:
+                    raise _connection_error(exc) from exc
+            else:
+                if response.is_success or response.status_code == 304:
+                    return _answer(response)
+                delay = self._retry_delay(
+                    method,
+                    parts,
+                    attempt,
+                    response.status_code,
+                    response.headers.get("retry-after"),
+                )
+                if delay is None:
+                    raise error_from(response)
+            time.sleep(delay)
+
+    def close(self) -> None:
+        """Close the HTTP client, unless it was passed in."""
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> SuperArtifacts:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+class AsyncSuperArtifacts(_Base, AsyncResources):
+    """Asynchronous client, the same surface awaited. `async with`, or `await close()`."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        _Base.__init__(self, api_key, base_url, timeout, max_retries)
+        AsyncResources.__init__(self)
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.AsyncClient()
+
+    async def _call(
+        self,
+        method: str,
+        path: str,
+        *,
+        path_params: dict[str, Any] | None = None,
+        query: dict[str, Any] | None = None,
+        body: dict[str, Any] | None = None,
+        nullable: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+        headers: dict[str, Any] | None = None,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        url, parts = self._prepare(
+            method, path, path_params, query, body, nullable, idempotency_key
+        )
+        parts["headers"].update({k: v for k, v in (headers or {}).items() if v is not None})
+        return await self._request(method, url, timeout, parts)
+
+    async def _request(
+        self, method: str, url: str, timeout: float | None, parts: dict[str, Any]
+    ) -> dict[str, Any]:
+        wait = self.timeout if timeout is None else timeout
+        for attempt in count():
+            try:
+                response = await self._http.request(method, url, timeout=wait, **parts)
+            except httpx.TransportError as exc:
+                delay = self._retry_delay(method, parts, attempt)
+                if delay is None:
+                    raise _connection_error(exc) from exc
+            else:
+                if response.is_success or response.status_code == 304:
+                    return _answer(response)
+                delay = self._retry_delay(
+                    method,
+                    parts,
+                    attempt,
+                    response.status_code,
+                    response.headers.get("retry-after"),
+                )
+                if delay is None:
+                    raise error_from(response)
+            await asyncio.sleep(delay)
+
+    async def close(self) -> None:
+        """Close the HTTP client, unless it was passed in."""
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncSuperArtifacts:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()

superartifacts/_errors.py

@@ -0,0 +1,125 @@
+"""What a refused or failed call raises."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class SuperArtifactsError(Exception):
+    """Base of every error here. `code` is stable; `message` is for a person."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        code: str | None = None,
+        retry_after: float | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.retry_after = retry_after
+        self.details = details or {}
+
+
+class InvalidArgumentsError(SuperArtifactsError):
+    """400: the request was refused as written."""
+
+
+class AuthenticationError(SuperArtifactsError):
+    """401, or no key to send."""
+
+
+class PlanLimitError(SuperArtifactsError):
+    """402: the account's plan does not allow this."""
+
+
+class PermissionError(SuperArtifactsError):
+    """403 forbidden."""
+
+
+class ScopeRequiredError(PermissionError):
+    """403 scope_required: a read key called a write."""
+
+
+class NotFoundError(SuperArtifactsError):
+    """404."""
+
+
+class ConflictError(SuperArtifactsError):
+    """409."""
+
+
+class PayloadTooLargeError(SuperArtifactsError):
+    """413: over 1 MiB of JSON. Use `uploads.upload` for files."""
+
+
+class RateLimitError(SuperArtifactsError):
+    """429 after the retries ran out. `retry_after` is in seconds."""
+
+
+class InternalError(SuperArtifactsError):
+    """5xx."""
+
+
+class APIConnectionError(SuperArtifactsError):
+    """The request never got an answer."""
+
+
+class APITimeoutError(APIConnectionError):
+    """The request took longer than `timeout`."""
+
+
+_BY_STATUS = {
+    400: InvalidArgumentsError,
+    401: AuthenticationError,
+    402: PlanLimitError,
+    403: PermissionError,
+    404: NotFoundError,
+    409: ConflictError,
+    413: PayloadTooLargeError,
+    429: RateLimitError,
+}
+
+
+def parse_seconds(value: Any) -> float | None:
+    """A Retry-After in seconds; the HTTP-date form and junk read as absent."""
+    try:
+        seconds = float(value)
+    except (TypeError, ValueError):
+        return None
+    return seconds if seconds >= 0 else None
+
+
+def error_from(response: httpx.Response) -> SuperArtifactsError:
+    """The error for a non-2xx answer, whatever its body turned out to be."""
+    try:
+        body = response.json()
+    except ValueError:
+        # A proxy's HTML page rather than the API: the status is all there is.
+        body = None
+    error = body.get("error") if isinstance(body, dict) else None
+    error = error if isinstance(error, dict) else {}
+
+    status = response.status_code
+    code = error.get("code") if isinstance(error.get("code"), str) else None
+    message = error.get("message")
+    if not isinstance(message, str):
+        message = f"The API answered {status} {response.reason_phrase}".strip()
+
+    if status == 403 and code == "scope_required":
+        kind = ScopeRequiredError
+    elif status >= 500:
+        kind = InternalError
+    else:
+        kind = _BY_STATUS.get(status, SuperArtifactsError)
+
+    retry_after = parse_seconds(response.headers.get("retry-after"))
+    if retry_after is None:
+        retry_after = parse_seconds(error.get("retryAfterSeconds"))
+    return kind(message, status=status, code=code, retry_after=retry_after, details=error)