thunder-solution-sdk 1.0.0__py3-none-any.whl

thunder_slip/__init__.py

@@ -0,0 +1,12 @@
+"""Typed sync and async clients for the public slip API."""
+
+from .client import Client as Client, AsyncClient as AsyncClient
+from .models import AccountType as AccountType, QrType as QrType
+from ._codec import UNSET as UNSET
+from ._base_error import SDKError as SDKError
+
+__version__ = "1.0.0"  # x-release-please-version
+
+from ._base_error import ThunderError as ThunderError
+
+Thunder = Client

thunder_slip/_base_error.py

@@ -0,0 +1,8 @@
+"""Root error for this distribution."""
+
+
+class ThunderError(Exception):
+    """Base class for API and transport failures."""
+
+
+SDKError = ThunderError

thunder_slip/_codec.py

@@ -0,0 +1,102 @@
+"""Dataclass wire conversion with separate absent and null values."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import MISSING, fields, is_dataclass
+from enum import Enum
+import types
+from typing import Any, Literal, TypeVar, Union, cast, get_args, get_origin, get_type_hints
+
+from ._base_error import SDKError
+
+
+class UnsetType(Enum):
+    """An absent JSON field, distinct from an explicit null."""
+
+    UNSET = 0
+
+
+UNSET = UnsetType.UNSET
+
+
+class DecodeError(SDKError):
+    """The response does not match the expected model."""
+
+
+T = TypeVar("T")
+
+
+def decode(model: type[T], value: object) -> T:
+    """Decode a JSON object into a dataclass without flattening nested models."""
+    return cast(T, _decode(model, value))
+
+
+def _decode(annotation: Any, value: Any) -> Any:
+    origin = get_origin(annotation)
+    args = get_args(annotation)
+    if annotation is Any:
+        return value
+    if origin in (Union, types.UnionType):
+        for candidate in args:
+            if candidate is UnsetType:
+                continue
+            try:
+                return _decode(candidate, value)
+            except DecodeError:
+                pass
+        raise DecodeError("Response field has an unexpected type")
+    if origin is Literal:
+        if any(type(value) is type(option) and value == option for option in args):
+            return value
+        raise DecodeError("Response field has an unexpected value")
+    if annotation is type(None):
+        if value is None:
+            return None
+        raise DecodeError("Expected a null response field")
+    if is_dataclass(annotation):
+        if not isinstance(value, dict):
+            raise DecodeError("Expected a response object")
+        hints = get_type_hints(annotation)
+        kwargs: dict[str, Any] = {}
+        for item in fields(annotation):
+            if not item.init:
+                continue
+            key = item.metadata.get("wire", item.name)
+            if key in value:
+                kwargs[item.name] = _decode(hints[item.name], value[key])
+            elif item.default is MISSING and item.default_factory is MISSING:
+                raise DecodeError(f"Missing response field: {item.name}")
+        return cast(Callable[..., Any], annotation)(**kwargs)
+    if origin is list:
+        if not isinstance(value, list):
+            raise DecodeError("Expected a response array")
+        return [_decode(args[0], item) for item in value]
+    if origin is dict:
+        if not isinstance(value, dict):
+            raise DecodeError("Expected a response object")
+        return {_decode(args[0], key): _decode(args[1], item) for key, item in value.items()}
+    if annotation in (str, int, bool):
+        if type(value) is not annotation:
+            raise DecodeError("Response field has an unexpected type")
+        return value
+    if annotation is float and type(value) in (int, float):
+        return float(value)
+    raise DecodeError("Unsupported response field type")
+
+
+def encode(value: object) -> Any:
+    """Encode dataclasses, omitting absent fields and preserving explicit nulls."""
+    if is_dataclass(value) and not isinstance(value, type):
+        return {
+            item.metadata.get("wire", item.name): encode(getattr(value, item.name))
+            for item in fields(value)
+            if not item.metadata.get("ignore") and getattr(value, item.name) is not UNSET
+        }
+    if isinstance(value, dict):
+        return {key: encode(item) for key, item in value.items() if item is not UNSET}
+    if isinstance(value, (list, tuple)):
+        return [encode(item) for item in value]
+    if isinstance(value, Enum):
+        return value.value
+    return value

thunder_slip/_transport.py

@@ -0,0 +1,282 @@
+"""Shared HTTP policy for synchronous and asynchronous clients."""
+
+from __future__ import annotations
+
+import asyncio
+import email.utils
+import math
+import platform
+import random
+import time
+from collections.abc import Awaitable, Callable
+from datetime import datetime, timezone
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+
+from .errors import NetworkError, TimeoutError, api_error, SanitizedTransportError
+
+
+def _url(base_url: str) -> str:
+    parsed = urlsplit(base_url)
+    if (
+        parsed.scheme not in ("https", "http")
+        or not parsed.netloc
+        or parsed.username
+        or parsed.password
+    ):
+        raise ValueError("base_url must be an HTTP(S) URL without credentials")
+    if parsed.query or parsed.fragment:
+        raise ValueError("base_url cannot contain query or fragment")
+    return base_url.rstrip("/")
+
+
+def _delay(response: httpx.Response | None, attempt: int) -> float:
+    if response is not None:
+        value = response.headers.get("retry-after")
+        if value:
+            try:
+                seconds = float(value)
+                if math.isfinite(seconds):
+                    return max(0.0, seconds)
+            except ValueError:
+                try:
+                    date = email.utils.parsedate_to_datetime(value)
+                    return max(0.0, (date - datetime.now(timezone.utc)).total_seconds())
+                except (ValueError, TypeError):
+                    pass
+    return float(min(8.0, 0.5 * 2**attempt) * random.uniform(0.5, 1.0))
+
+
+class Transport:
+    """Internal synchronous transport. Injected HTTP clients remain caller-owned."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        *,
+        http: httpx.Client | None = None,
+        timeout: float = 30,
+        max_retries: int = 2,
+        user_agent: str = "sdk/1.0.0",  # x-release-please-version
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        if (
+            not api_key
+            or not math.isfinite(timeout)
+            or timeout <= 0
+            or isinstance(max_retries, bool)
+            or not isinstance(max_retries, int)
+            or not 0 <= max_retries <= 20
+        ):
+            raise ValueError("api_key, timeout and max_retries must be valid")
+        self._key = api_key
+        self._base = _url(base_url)
+        self._http = (
+            http if http is not None else httpx.Client(trust_env=False, follow_redirects=False)
+        )
+        self._owned = http is None
+        self._timeout = timeout
+        self._retries = max_retries
+        self._agent = f"{user_agent} python/{platform.python_version()}"
+        self._sleep = sleep
+
+    def request(
+        self, method: str, path: str, *, safe: bool = False, **kwargs: Any
+    ) -> httpx.Response:
+        """Send once, retrying only explicitly safe operations."""
+        if not path.startswith("/") or path.startswith("//"):
+            raise ValueError("path must be relative to the configured API")
+        deadline = kwargs.pop("_deadline", None)
+        headers = httpx.Headers(kwargs.pop("headers", {}))
+        headers["Accept"] = "application/json"
+        headers["Authorization"] = f"Bearer {self._key}"
+        headers["User-Agent"] = self._agent
+        for attempt in range(self._retries + 1):
+            remaining = (
+                self._timeout
+                if deadline is None
+                else min(self._timeout, deadline - time.monotonic())
+            )
+            if remaining <= 0:
+                raise TimeoutError("HTTP request timed out")
+            response = None
+            failure: NetworkError | None = None
+            connect_failure = False
+            try:
+                response = self._http.request(
+                    method,
+                    self._base + path,
+                    headers=headers,
+                    timeout=remaining,
+                    follow_redirects=False,
+                    **kwargs,
+                )
+            except httpx.TimeoutException as error:
+                connect_failure = isinstance(error, httpx.ConnectTimeout)
+                failure = TimeoutError(
+                    "HTTP request timed out", SanitizedTransportError(error, self._key)
+                )
+            except httpx.RequestError as error:
+                connect_failure = isinstance(error, httpx.ConnectError)
+                failure = NetworkError(
+                    "HTTP network request failed", SanitizedTransportError(error, self._key)
+                )
+            if failure is not None:
+                if (safe or connect_failure) and attempt < self._retries:
+                    self._sleep(
+                        min(_delay(None, attempt), max(0, deadline - time.monotonic()))
+                        if deadline
+                        else _delay(None, attempt)
+                    )
+                    continue
+                raise failure
+            assert response is not None
+            if deadline is not None and time.monotonic() >= deadline:
+                response.close()
+                raise TimeoutError("HTTP request timed out")
+            delay = _delay(response, attempt)
+            if (
+                (
+                    response.status_code == 429
+                    or (safe and response.status_code in (500, 502, 503, 504))
+                )
+                and attempt < self._retries
+                and delay <= 60
+            ):
+                response.close()
+                self._sleep(min(delay, max(0, deadline - time.monotonic())) if deadline else delay)
+                continue
+            if response.status_code >= 300:
+                raise api_error(response, self._key)
+            return response
+        raise AssertionError("unreachable retry state")
+
+    def close(self) -> None:
+        """Close an internally created HTTP client."""
+        if self._owned:
+            self._http.close()
+
+    def __enter__(self) -> Transport:
+        return self
+
+    def __exit__(self, *_args: object) -> None:
+        self.close()
+
+
+class AsyncTransport:
+    """Internal async transport with cancellation-safe retry sleeps."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        *,
+        http: httpx.AsyncClient | None = None,
+        timeout: float = 30,
+        max_retries: int = 2,
+        user_agent: str = "sdk/1.0.0",  # x-release-please-version
+        sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+    ) -> None:
+        if (
+            not api_key
+            or not math.isfinite(timeout)
+            or timeout <= 0
+            or isinstance(max_retries, bool)
+            or not isinstance(max_retries, int)
+            or not 0 <= max_retries <= 20
+        ):
+            raise ValueError("api_key, timeout and max_retries must be valid")
+        self._key = api_key
+        self._base = _url(base_url)
+        self._http = (
+            http if http is not None else httpx.AsyncClient(trust_env=False, follow_redirects=False)
+        )
+        self._owned = http is None
+        self._timeout = timeout
+        self._retries = max_retries
+        self._agent = f"{user_agent} python/{platform.python_version()}"
+        self._sleep = sleep
+
+    async def request(
+        self, method: str, path: str, *, safe: bool = False, **kwargs: Any
+    ) -> httpx.Response:
+        """Send once, retrying only explicitly safe operations."""
+        if not path.startswith("/") or path.startswith("//"):
+            raise ValueError("path must be relative to the configured API")
+        deadline = kwargs.pop("_deadline", None)
+        headers = httpx.Headers(kwargs.pop("headers", {}))
+        headers["Accept"] = "application/json"
+        headers["Authorization"] = f"Bearer {self._key}"
+        headers["User-Agent"] = self._agent
+        for attempt in range(self._retries + 1):
+            remaining = (
+                self._timeout
+                if deadline is None
+                else min(self._timeout, deadline - time.monotonic())
+            )
+            if remaining <= 0:
+                raise TimeoutError("HTTP request timed out")
+            response = None
+            failure: NetworkError | None = None
+            connect_failure = False
+            try:
+                response = await self._http.request(
+                    method,
+                    self._base + path,
+                    headers=headers,
+                    timeout=remaining,
+                    follow_redirects=False,
+                    **kwargs,
+                )
+            except httpx.TimeoutException as error:
+                connect_failure = isinstance(error, httpx.ConnectTimeout)
+                failure = TimeoutError(
+                    "HTTP request timed out", SanitizedTransportError(error, self._key)
+                )
+            except httpx.RequestError as error:
+                connect_failure = isinstance(error, httpx.ConnectError)
+                failure = NetworkError(
+                    "HTTP network request failed", SanitizedTransportError(error, self._key)
+                )
+            if failure is not None:
+                if (safe or connect_failure) and attempt < self._retries:
+                    await self._sleep(
+                        min(_delay(None, attempt), max(0, deadline - time.monotonic()))
+                        if deadline
+                        else _delay(None, attempt)
+                    )
+                    continue
+                raise failure
+            assert response is not None
+            delay = _delay(response, attempt)
+            if (
+                (
+                    response.status_code == 429
+                    or (safe and response.status_code in (500, 502, 503, 504))
+                )
+                and attempt < self._retries
+                and delay <= 60
+            ):
+                await response.aclose()
+                await self._sleep(
+                    min(delay, max(0, deadline - time.monotonic())) if deadline else delay
+                )
+                continue
+            if response.status_code >= 300:
+                raise api_error(response, self._key)
+            return response
+        raise AssertionError("unreachable retry state")
+
+    async def close(self) -> None:
+        """Close an internally created HTTP client."""
+        if self._owned:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncTransport:
+        return self
+
+    async def __aexit__(self, *_args: object) -> None:
+        await self.close()