updo-sdk 0.1.0__py3-none-any.whl

updo/__init__.py

@@ -0,0 +1,92 @@
+"""Python SDK for the Updo360 (Qlaris) public ERP API.
+
+    from updo import UpdoClient
+
+    with UpdoClient(token="sk_live_...") as client:
+        print(client.me().tenant_slug)
+        for product in client.entity("product").iterate(where={"status": "active"}):
+            print(product["sku"], product["sale_price"])
+
+The public surface is PAT-only and lives under ``/api/public/v1/``. A token is
+bound to exactly one workspace at creation, so there is no tenant to select and
+no session to maintain.
+"""
+
+from ._version import __version__
+from .aio import AsyncUpdoClient
+from .client import UpdoClient
+from .config import API_PREFIX, DEFAULT_BASE_URL, ClientConfig
+from .errors import (
+    ApprovalRequired,
+    AuthenticationError,
+    ConflictError,
+    NotFoundError,
+    PermissionDenied,
+    PlanLimitExceeded,
+    RateLimitError,
+    ServerError,
+    UpdoAPIError,
+    UpdoConfigError,
+    UpdoConnectionError,
+    UpdoError,
+    UpdoTimeoutError,
+    UpdoTransportError,
+    ValidationError,
+)
+from .models import (
+    AggregateResult,
+    ApprovalPending,
+    EntitySchema,
+    EntitySummary,
+    FieldSpec,
+    ODataPage,
+    Page,
+    PivotResult,
+    Record,
+    TokenIdentity,
+    Webhook,
+    WebhookDelivery,
+    WebhookEvent,
+)
+from .query import F
+from .webhooks import parse_event, verify_signature
+
+__all__ = [
+    "API_PREFIX",
+    "DEFAULT_BASE_URL",
+    "AggregateResult",
+    "ApprovalPending",
+    "ApprovalRequired",
+    "AsyncUpdoClient",
+    "AuthenticationError",
+    "ClientConfig",
+    "ConflictError",
+    "EntitySchema",
+    "EntitySummary",
+    "F",
+    "FieldSpec",
+    "NotFoundError",
+    "ODataPage",
+    "Page",
+    "PermissionDenied",
+    "PivotResult",
+    "PlanLimitExceeded",
+    "RateLimitError",
+    "Record",
+    "ServerError",
+    "TokenIdentity",
+    "UpdoAPIError",
+    "UpdoClient",
+    "UpdoConfigError",
+    "UpdoConnectionError",
+    "UpdoError",
+    "UpdoTimeoutError",
+    "UpdoTransportError",
+    "ValidationError",
+    "Webhook",
+    "WebhookDelivery",
+    "WebhookEvent",
+    "__version__",
+    "parse_event",
+    "verify_signature",
+]

updo/_transport.py

@@ -0,0 +1,196 @@
+"""Transport plumbing shared by the sync and async clients.
+
+Everything here is pure: it builds requests and decides what to do with
+responses, but performs no I/O. The two clients differ only by ``await``, so
+keeping the decisions in one place is what stops them from drifting apart.
+"""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+import httpx
+
+from .config import ClientConfig
+from .errors import (
+    ApprovalRequired,
+    UpdoConnectionError,
+    UpdoTimeoutError,
+    UpdoTransportError,
+    error_from_response,
+    parse_retry_after,
+)
+from .models import ApprovalPending
+
+__all__ = [
+    "APPROVAL_CODE",
+    "IDEMPOTENT_METHODS",
+    "RETRY_STATUSES",
+    "build_headers",
+    "join_path",
+    "prepare_params",
+    "process_json",
+    "retry_delay",
+    "should_retry_exception",
+    "should_retry_status",
+    "wrap_transport_error",
+]
+
+#: Methods safe to replay after a partial failure. POST and PATCH are absent on
+#: purpose: a 500 after a POST may mean the write LANDED and the response was
+#: lost, so retrying would duplicate the record.
+IDEMPOTENT_METHODS = frozenset({"GET", "HEAD", "OPTIONS", "PUT", "DELETE"})
+
+#: Statuses worth a second attempt.
+RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})
+
+#: Platform code carried by the 202 approval envelope.
+APPROVAL_CODE = "APPROVAL_REQUIRED"
+
+_BACKOFF_BASE = 0.5
+_BACKOFF_CAP = 30.0
+
+
+def build_headers(config: ClientConfig, extra: Mapping[str, str] | None = None) -> dict[str, str]:
+    """Standard headers for every call.
+
+    Notably absent: ``X-Tenant-ID``. A personal access token is bound to exactly
+    one workspace at creation time, and sending a tenant header that disagrees
+    is a 401 -- so the SDK never sends one at all.
+    """
+    headers = {
+        "Authorization": f"Bearer {config.token}",
+        "Accept": "application/json",
+        "User-Agent": config.user_agent,
+    }
+    if extra:
+        headers.update({key: value for key, value in extra.items() if value is not None})
+    return headers
+
+
+def join_path(base_url: str, path: str) -> str:
+    """Join base and path, forcing the trailing slash Django requires.
+
+    Without it Django answers a 301 to the slashed URL, and httpx drops the
+    ``Authorization`` header across some redirects -- surfacing as a baffling
+    401 on a perfectly valid token.
+    """
+    cleaned = path.strip()
+    if cleaned.startswith(("http://", "https://")):
+        return cleaned
+    cleaned = cleaned.lstrip("/")
+    if cleaned and not cleaned.endswith("/"):
+        cleaned += "/"
+    return f"{base_url.rstrip('/')}/{cleaned}"
+
+
+def prepare_params(*sources: Mapping[str, Any] | None) -> dict[str, Any]:
+    """Merge parameter mappings, dropping ``None`` values (unset, not empty)."""
+    merged: dict[str, Any] = {}
+    for source in sources:
+        if not source:
+            continue
+        for key, value in source.items():
+            if value is None:
+                continue
+            merged[key] = value
+    return merged
+
+
+def should_retry_status(method: str, status: int, attempt: int, max_retries: int) -> bool:
+    """Whether to replay after an HTTP error response."""
+    if attempt >= max_retries:
+        return False
+    if status not in RETRY_STATUSES:
+        return False
+    if status == 429:
+        # The request was rejected by the throttle BEFORE any side effect, so
+        # replaying is safe even for a POST.
+        return True
+    return method.upper() in IDEMPOTENT_METHODS
+
+
+def should_retry_exception(method: str, exc: Exception, attempt: int, max_retries: int) -> bool:
+    """Whether to replay after a transport failure."""
+    if attempt >= max_retries:
+        return False
+    if isinstance(exc, (httpx.ConnectError, httpx.ConnectTimeout)):
+        # The connection was never established: nothing can have been applied.
+        return True
+    if isinstance(exc, (httpx.TimeoutException, httpx.NetworkError, httpx.RemoteProtocolError)):
+        return method.upper() in IDEMPOTENT_METHODS
+    return False
+
+
+def retry_delay(attempt: int, response: httpx.Response | None = None) -> float:
+    """Seconds to wait before the next attempt (``Retry-After`` wins if sent)."""
+    if response is not None:
+        explicit = parse_retry_after(response.headers.get("Retry-After"))
+        if explicit is not None:
+            return min(explicit, _BACKOFF_CAP)
+    window = min(_BACKOFF_CAP, _BACKOFF_BASE * (2**attempt))
+    # Full jitter: identical clients retrying in lockstep would re-empty the
+    # bucket the instant it refills.
+    return random.uniform(0.0, window)  # noqa: S311 - jitter, not cryptography
+
+
+def wrap_transport_error(exc: Exception) -> UpdoTransportError:
+    """Translate an httpx transport failure into this SDK's vocabulary."""
+    if isinstance(exc, httpx.TimeoutException):
+        return UpdoTimeoutError(f"Request timed out: {exc}")
+    if isinstance(exc, httpx.ConnectError):
+        return UpdoConnectionError(f"Could not connect: {exc}")
+    return UpdoTransportError(f"Transport failure: {exc}")
+
+
+def _json_or_none(response: httpx.Response) -> Any:
+    try:
+        return response.json()
+    except Exception:  # noqa: BLE001 - a non-JSON success body is still a success
+        return None
+
+
+def process_json(response: httpx.Response, *, on_approval: str) -> Any:
+    """Turn a response into a payload, raising the right exception otherwise.
+
+    Three outcomes the caller must not have to spell out each time:
+
+    * **204** (and an empty body) -> ``None``
+    * **202 APPROVAL_REQUIRED** -> the write is queued, not applied. Raising by
+      default is deliberate: returning a record-shaped object with no ``id``
+      would let the caller carry on as if the write had landed.
+    * **>= 400** -> the normalised exception from :mod:`updo.errors`
+    """
+    status = response.status_code
+
+    if status >= 400:
+        raise error_from_response(response)
+
+    if status == 204 or not response.content:
+        return None
+
+    payload = _json_or_none(response)
+
+    if status == 202 and isinstance(payload, Mapping) and payload.get("code") == APPROVAL_CODE:
+        pending = ApprovalPending.from_dict(payload)
+        if on_approval == "return":
+            return pending
+        raise ApprovalRequired(
+            pending.detail or "This write requires an approval before it is applied.",
+            approval_request_id=pending.approval_request_id,
+            status=pending.status,
+            body=dict(payload),
+        )
+
+    return payload
+
+
+def stream_to(target: Any, chunks: Iterable[bytes]) -> int:
+    """Write chunks to a binary file object, returning the byte count."""
+    total = 0
+    for chunk in chunks:
+        target.write(chunk)
+        total += len(chunk)
+    return total

updo/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the package version (read by ``pyproject.toml``)."""
+
+__version__ = "0.1.0"

updo/aio.py

@@ -0,0 +1,235 @@
+"""The asynchronous client -- a mirror of :mod:`updo.client`.
+
+Every decision (retry policy, error mapping, parameter building) lives in the
+shared modules, so this file is the sync client with ``await`` in front of the
+I/O and nothing else different.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Mapping
+from pathlib import Path
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from ._transport import (
+    build_headers,
+    join_path,
+    prepare_params,
+    process_json,
+    retry_delay,
+    should_retry_exception,
+    should_retry_status,
+    wrap_transport_error,
+)
+from .config import ClientConfig, OnApproval, mask_token
+from .errors import error_from_response
+from .models import EntitySchema, TokenIdentity
+from .resources.entities import AsyncEntitiesResource
+from .resources.records import AsyncRecordsResource
+from .resources.webhooks import AsyncWebhooksResource
+
+__all__ = ["AsyncUpdoClient"]
+
+
+class AsyncUpdoClient:
+    """Asynchronous client for the Updo public API.
+
+    import asyncio
+    from updo import AsyncUpdoClient
+
+    async def main():
+        async with AsyncUpdoClient(token="sk_live_...") as client:
+            print(await client.me())
+
+    asyncio.run(main())
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        base_url: str | None = None,
+        *,
+        timeout: Any = 30.0,
+        max_retries: int = 3,
+        on_approval: OnApproval = "raise",
+        user_agent: str | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.config = ClientConfig.build(
+            token=token,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            on_approval=on_approval,
+            user_agent=user_agent,
+        )
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=self.config.timeout)
+        self._schemas: dict[str, EntitySchema] = {}
+
+        self.entities = AsyncEntitiesResource(self)
+        self.webhooks = AsyncWebhooksResource(self)
+
+    # -- lifecycle ----------------------------------------------------------
+
+    async def close(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncUpdoClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    def __repr__(self) -> str:
+        return (
+            f"AsyncUpdoClient(base_url={self.config.base_url!r}, "
+            f"token={mask_token(self.config.token)!r})"
+        )
+
+    # -- schema cache -------------------------------------------------------
+
+    def cached_schema(self, slug: str) -> EntitySchema | None:
+        return self._schemas.get(slug)
+
+    def store_schema(self, schema: EntitySchema) -> None:
+        self._schemas[schema.slug] = schema
+
+    def clear_schema_cache(self) -> None:
+        self._schemas.clear()
+
+    # -- HTTP ---------------------------------------------------------------
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        response = await self._send(method, path, params=params, json=json, headers=headers)
+        return process_json(response, on_approval=self.config.on_approval)
+
+    async def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> httpx.Response:
+        url = join_path(self.config.base_url, path)
+        query = prepare_params(params)
+        request_headers = build_headers(self.config, headers)
+
+        attempt = 0
+        while True:
+            try:
+                response = await self._http.request(
+                    method.upper(),
+                    url,
+                    params=query or None,
+                    json=json,
+                    headers=request_headers,
+                )
+            except Exception as exc:  # noqa: BLE001 - re-raised as our own type below
+                if should_retry_exception(method, exc, attempt, self.config.max_retries):
+                    await asyncio.sleep(retry_delay(attempt))
+                    attempt += 1
+                    continue
+                raise wrap_transport_error(exc) from exc
+
+            if should_retry_status(method, response.status_code, attempt, self.config.max_retries):
+                delay = retry_delay(attempt, response)
+                await response.aclose()
+                await asyncio.sleep(delay)
+                attempt += 1
+                continue
+            return response
+
+    async def download(
+        self,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        dest: Any = None,
+    ) -> Any:
+        url = join_path(self.config.base_url, path)
+        query = prepare_params(params)
+        headers = build_headers(self.config, {"Accept": "*/*"})
+
+        attempt = 0
+        while True:
+            try:
+                async with self._http.stream(
+                    "GET", url, params=query or None, headers=headers
+                ) as response:
+                    if should_retry_status(
+                        "GET", response.status_code, attempt, self.config.max_retries
+                    ):
+                        delay = retry_delay(attempt, response)
+                        await asyncio.sleep(delay)
+                        attempt += 1
+                        continue
+                    if response.status_code >= 400:
+                        await response.aread()
+                        raise error_from_response(response)
+                    return await _consume(response.aiter_bytes(), dest)
+            except httpx.HTTPError as exc:
+                if should_retry_exception("GET", exc, attempt, self.config.max_retries):
+                    await asyncio.sleep(retry_delay(attempt))
+                    attempt += 1
+                    continue
+                raise wrap_transport_error(exc) from exc
+
+    # -- endpoints ----------------------------------------------------------
+
+    async def me(self) -> TokenIdentity:
+        return TokenIdentity.from_dict(await self.request("GET", "me") or {})
+
+    async def entity(self, slug: str, *, coerce: bool = False) -> AsyncRecordsResource:
+        """Access one entity's records.
+
+        Unlike the sync counterpart this is a coroutine, because ``coerce=True``
+        may need to fetch the schema first.
+        """
+        schema = await self.entities.schema(slug) if coerce else None
+        return AsyncRecordsResource(self, slug, schema=schema)
+
+    async def openapi(self) -> Any:
+        return await self.request("GET", "schema", params={"format": "json"})
+
+    async def ping(self) -> bool:
+        await self.me()
+        return True
+
+
+async def _consume(chunks: Any, dest: Any) -> Any:
+    if dest is None:
+        buffer = bytearray()
+        async for chunk in chunks:
+            buffer.extend(chunk)
+        return bytes(buffer)
+    if hasattr(dest, "write"):
+        async for chunk in chunks:
+            dest.write(chunk)
+        return dest
+    target = Path(dest)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with target.open("wb") as handle:
+        async for chunk in chunks:
+            handle.write(chunk)
+    return target