timbro-protocol 0.10.0__py3-none-any.whl

timbro_protocol/__init__.py

@@ -0,0 +1,45 @@
+"""Shared errors and Standard Webhooks verification of the Timbro Python SDKs.
+
+SDK packages build on `timbro_protocol.runtime`.
+"""
+
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    ConflictError,
+    InvalidRequestError,
+    NotFoundError,
+    PermissionDeniedError,
+    ProblemDetail,
+    RateLimitError,
+    ServerError,
+    TimbroError,
+    UnexpectedResponseError,
+    WebhookRejection,
+    WebhookVerificationError,
+)
+from ._version import __version__
+from ._webhooks import sign_webhook, verify_webhook_signature
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APITimeoutError",
+    "AuthenticationError",
+    "ConflictError",
+    "InvalidRequestError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "ProblemDetail",
+    "RateLimitError",
+    "ServerError",
+    "TimbroError",
+    "UnexpectedResponseError",
+    "WebhookRejection",
+    "WebhookVerificationError",
+    "__version__",
+    "sign_webhook",
+    "verify_webhook_signature",
+]

timbro_protocol/_client.py

@@ -0,0 +1,343 @@
+"""Sync and async executors over the sans-I/O core; only sending, reading, and sleeping differ."""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Callable, Mapping
+from types import TracebackType
+from typing import Any, TypeVar
+
+import httpx
+
+from . import _core
+from ._core import ClientSettings, FileResponse, TimeoutTypes
+from ._errors import TimbroError
+from ._operation import Operation
+
+T = TypeVar("T")
+Decode = Callable[[httpx.Response, bytes], T]
+
+
+class SyncAPIClient:
+    """Sends Timbro operations over an `httpx.Client` with the contract's retry rules."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        user_agent: str,
+        base_url: str = _core.DEFAULT_BASE_URL,
+        timeout: TimeoutTypes = _core.DEFAULT_TIMEOUT,
+        max_retries: int = _core.DEFAULT_MAX_RETRIES,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._settings = ClientSettings.create(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            user_agent=user_agent,
+        )
+        self._http_client = http_client
+        self._owns_http_client = http_client is None
+        self._lock = threading.Lock()
+        self._closed = False
+
+    def request(
+        self,
+        operation: Operation,
+        *,
+        path_params: Mapping[str, str] | None = None,
+        query: Mapping[str, object] | None = None,
+        body: Mapping[str, Any] | None = None,
+        idempotency_key: str | None = None,
+        access_token: str | None = None,
+        expect: Mapping[str, str] | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> Any:
+        """Sends a JSON operation and returns its decoded object, or None for a 204."""
+        request = _core.build_request(
+            self._settings,
+            operation,
+            path_params=path_params or {},
+            query=query,
+            body=body,
+            idempotency_key=idempotency_key,
+            access_token=access_token,
+            timeout=self._timeout(timeout),
+        )
+        return self._send(
+            operation,
+            request,
+            lambda response, content: _core.decode_response(operation, response, content, expect),
+        )
+
+    def download(
+        self,
+        operation: Operation,
+        *,
+        media_type: str,
+        path_params: Mapping[str, str] | None = None,
+        access_token: str | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> FileResponse:
+        """Sends a file operation and returns its bytes and headers, unverified."""
+        request = _core.build_request(
+            self._settings,
+            operation,
+            path_params=path_params or {},
+            query=None,
+            body=None,
+            idempotency_key=None,
+            access_token=access_token,
+            accept=media_type,
+            timeout=self._timeout(timeout),
+        )
+        return self._send(
+            operation,
+            request,
+            lambda response, content: _core.decode_file(operation, response, content),
+        )
+
+    def _send(self, operation: Operation, request: httpx.Request, decode: Decode[T]) -> T:
+        http_client = self._client()
+        retry = 0
+        reached = False
+        while True:
+            try:
+                response = http_client.send(request, follow_redirects=False, stream=True)
+                try:
+                    content = _read(response)
+                finally:
+                    response.close()
+            except httpx.TransportError as error:
+                reached = reached or _core.may_have_arrived(error)
+                delay = _core.retry_delay_after_transport_error(
+                    operation, request, retry, self._settings.max_retries
+                )
+                if delay is None:
+                    failure = _core.transport_error(operation, error)
+                    raise _core.settle(operation, request, failure, reached) from error
+            else:
+                reached = True
+                _core.log_response(operation, response, retry + 1)
+                delay = _core.retry_delay_after_response(
+                    operation, request, response, retry, self._settings.max_retries
+                )
+                if delay is None:
+                    try:
+                        return decode(response, content)
+                    except TimbroError as failure:
+                        _core.settle(operation, request, failure, reached)
+                        raise
+            time.sleep(delay)
+            retry += 1
+
+    def _timeout(self, timeout: TimeoutTypes | None) -> httpx.Timeout | None:
+        if timeout is not None:
+            return _core.as_timeout(timeout)
+        return self._settings.timeout if self._owns_http_client else None
+
+    def close(self) -> None:
+        """Closes the HTTP client this object created; a caller-supplied client stays open."""
+        with self._lock:
+            self._closed = True
+            if self._owns_http_client and self._http_client is not None:
+                self._http_client.close()
+
+    def __enter__(self) -> SyncAPIClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def _client(self) -> httpx.Client:
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("The Timbro client is closed.")
+            if self._http_client is None:
+                self._http_client = httpx.Client(timeout=self._settings.timeout)
+            return self._http_client
+
+
+class AsyncAPIClient:
+    """Sends Timbro operations over an `httpx.AsyncClient` with the contract's retry rules."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        user_agent: str,
+        base_url: str = _core.DEFAULT_BASE_URL,
+        timeout: TimeoutTypes = _core.DEFAULT_TIMEOUT,
+        max_retries: int = _core.DEFAULT_MAX_RETRIES,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._settings = ClientSettings.create(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            user_agent=user_agent,
+        )
+        self._http_client = http_client
+        self._owns_http_client = http_client is None
+        self._closed = False
+
+    async def request(
+        self,
+        operation: Operation,
+        *,
+        path_params: Mapping[str, str] | None = None,
+        query: Mapping[str, object] | None = None,
+        body: Mapping[str, Any] | None = None,
+        idempotency_key: str | None = None,
+        access_token: str | None = None,
+        expect: Mapping[str, str] | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> Any:
+        """Sends a JSON operation and returns its decoded object, or None for a 204."""
+        request = _core.build_request(
+            self._settings,
+            operation,
+            path_params=path_params or {},
+            query=query,
+            body=body,
+            idempotency_key=idempotency_key,
+            access_token=access_token,
+            timeout=self._timeout(timeout),
+        )
+        return await self._send(
+            operation,
+            request,
+            lambda response, content: _core.decode_response(operation, response, content, expect),
+        )
+
+    async def download(
+        self,
+        operation: Operation,
+        *,
+        media_type: str,
+        path_params: Mapping[str, str] | None = None,
+        access_token: str | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> FileResponse:
+        """Sends a file operation and returns its bytes and headers, unverified."""
+        request = _core.build_request(
+            self._settings,
+            operation,
+            path_params=path_params or {},
+            query=None,
+            body=None,
+            idempotency_key=None,
+            access_token=access_token,
+            accept=media_type,
+            timeout=self._timeout(timeout),
+        )
+        return await self._send(
+            operation,
+            request,
+            lambda response, content: _core.decode_file(operation, response, content),
+        )
+
+    async def _send(self, operation: Operation, request: httpx.Request, decode: Decode[T]) -> T:
+        # Imported here so that synchronous callers never pay for importing asyncio.
+        import asyncio
+
+        http_client = self._client()
+        retry = 0
+        reached = False
+        while True:
+            try:
+                response = await http_client.send(request, follow_redirects=False, stream=True)
+                try:
+                    content = await _aread(response)
+                finally:
+                    await response.aclose()
+            except httpx.TransportError as error:
+                reached = reached or _core.may_have_arrived(error)
+                delay = _core.retry_delay_after_transport_error(
+                    operation, request, retry, self._settings.max_retries
+                )
+                if delay is None:
+                    failure = _core.transport_error(operation, error)
+                    raise _core.settle(operation, request, failure, reached) from error
+            else:
+                reached = True
+                _core.log_response(operation, response, retry + 1)
+                delay = _core.retry_delay_after_response(
+                    operation, request, response, retry, self._settings.max_retries
+                )
+                if delay is None:
+                    try:
+                        return decode(response, content)
+                    except TimbroError as failure:
+                        _core.settle(operation, request, failure, reached)
+                        raise
+            await asyncio.sleep(delay)
+            retry += 1
+
+    def _timeout(self, timeout: TimeoutTypes | None) -> httpx.Timeout | None:
+        if timeout is not None:
+            return _core.as_timeout(timeout)
+        return self._settings.timeout if self._owns_http_client else None
+
+    async def aclose(self) -> None:
+        """Closes the HTTP client this object created; a caller-supplied client stays open."""
+        self._closed = True
+        if self._owns_http_client and self._http_client is not None:
+            await self._http_client.aclose()
+
+    async def __aenter__(self) -> AsyncAPIClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    def _client(self) -> httpx.AsyncClient:
+        if self._closed:
+            raise RuntimeError("The Timbro client is closed.")
+        if self._http_client is None:
+            self._http_client = httpx.AsyncClient(timeout=self._settings.timeout)
+        return self._http_client
+
+
+def _read(response: httpx.Response) -> bytes:
+    """Reads the body, stopping one chunk past the limit so the decoder can refuse it.
+
+    A body whose declared length is already past the limit is not read at all.
+    """
+    if _core.declares_too_much(response):
+        return b""
+    chunks: list[bytes] = []
+    size = 0
+    for chunk in response.iter_bytes():
+        chunks.append(chunk)
+        size += len(chunk)
+        if size > _core.MAX_RESPONSE_BYTES:
+            break
+    return b"".join(chunks)
+
+
+async def _aread(response: httpx.Response) -> bytes:
+    if _core.declares_too_much(response):
+        return b""
+    chunks: list[bytes] = []
+    size = 0
+    async for chunk in response.aiter_bytes():
+        chunks.append(chunk)
+        size += len(chunk)
+        if size > _core.MAX_RESPONSE_BYTES:
+            break
+    return b"".join(chunks)