getanyapi 0.1.0__py3-none-any.whl

getanyapi/_errors.py

@@ -0,0 +1,115 @@
+"""Error hierarchy for the getanyapi SDK (SPEC 3.6).
+
+Every failed call raises a subclass of :class:`AnyAPIError`. The HTTP status to
+class mapping is frozen:
+
+    400 -> BadRequestError
+    401 -> AuthenticationError
+    402 -> InsufficientBalanceError
+    404 -> NotFoundError
+    429 -> RateLimitedError
+    502 -> UpstreamError
+    (any other non-2xx) -> AnyAPIError
+
+Transport failures raise :class:`ConnectionError` (status 0); timeouts raise
+:class:`TimeoutError` (status 0). Both names intentionally shadow the Python
+builtins of the same name and are exported from the package root.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "AnyAPIError",
+    "BadRequestError",
+    "AuthenticationError",
+    "InsufficientBalanceError",
+    "NotFoundError",
+    "ResultNotFoundError",
+    "RateLimitedError",
+    "UpstreamError",
+    "ConnectionError",
+    "TimeoutError",
+    "error_for_status",
+]
+
+
+class AnyAPIError(Exception):
+    """Base class for every error raised by the SDK.
+
+    Attributes:
+        status: HTTP status code, or 0 for transport-level failures.
+        request_id: The x-request-id response header when present, else None.
+    """
+
+    def __init__(
+        self, message: str, *, status: int, request_id: str | None = None
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.request_id = request_id
+
+
+class BadRequestError(AnyAPIError):
+    """HTTP 400: the input failed validation."""
+
+
+class AuthenticationError(AnyAPIError):
+    """HTTP 401: the API key is missing or invalid."""
+
+
+class InsufficientBalanceError(AnyAPIError):
+    """HTTP 402: the wallet balance or per-key cap was exceeded."""
+
+
+class NotFoundError(AnyAPIError):
+    """HTTP 404: the slug or resource does not exist."""
+
+
+class ResultNotFoundError(NotFoundError):
+    """Raised by :func:`getanyapi.unwrap` when a found-data result had ``found: false``.
+
+    A subclass of :class:`NotFoundError` so ``except NotFoundError`` still catches
+    it; catch ``ResultNotFoundError`` specifically to handle only empty results
+    (not HTTP 404s). See SPEC 2.3 erratum.
+    """
+
+
+class RateLimitedError(AnyAPIError):
+    """HTTP 429: too many requests. Retried automatically."""
+
+
+class UpstreamError(AnyAPIError):
+    """HTTP 502: an upstream backend failed."""
+
+
+class ConnectionError(AnyAPIError):
+    """A network or transport failure (status 0).
+
+    This name intentionally shadows the Python builtin ``ConnectionError``.
+    """
+
+
+class TimeoutError(AnyAPIError):
+    """A request that exceeded its timeout (status 0).
+
+    This name intentionally shadows the Python builtin ``TimeoutError``.
+    Timeouts are never retried.
+    """
+
+
+_STATUS_MAP: dict[int, type[AnyAPIError]] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    402: InsufficientBalanceError,
+    404: NotFoundError,
+    429: RateLimitedError,
+    502: UpstreamError,
+}
+
+
+def error_for_status(
+    status: int, message: str, *, request_id: str | None = None
+) -> AnyAPIError:
+    """Build the mapped error for a non-2xx HTTP status (SPEC 3.6)."""
+    cls = _STATUS_MAP.get(status, AnyAPIError)
+    return cls(message, status=status, request_id=request_id)

getanyapi/_pagination.py

@@ -0,0 +1,295 @@
+"""Cursor pagination for the sync and async clients (SPEC 2.5, 3.5).
+
+A ``Paginator`` walks a paginated SKU one page at a time, yielding either the
+flattened items (``__iter__``) or whole run-result pages (``.pages()``). Items
+are validated into the SKU's pydantic item model, so callers get attribute
+access (``post.title``), not raw dicts (SPEC 3.3 erratum, B3).
+
+Walk semantics (frozen):
+    * Page 1 is ``run(slug, input, options)``.
+    * Read the page data object: for a found-data SKU that is ``output.data``
+      (or None when ``found`` is false); for a BARE SKU it is ``output`` itself
+      (SPEC 1.2 erratum).
+    * Yield each item from ``items_field``. If ``nextCursor`` is a non-empty
+      string, set ``input["cursor"] = nextCursor`` and repeat; a null/empty
+      ``nextCursor`` ends the walk.
+    * ``options["max_items"]`` caps the TOTAL items yielded across all pages.
+      It is NOT sent as the wire ``max_items`` shaping param from the iterator;
+      the iterator manages paging itself.
+
+The emitter targets the module-level helpers :func:`paginate` (sync) and
+:func:`apaginate` (async): each takes the bound client, slug, input dict, the
+items field name, the item model, the page-result model, and the envelope mode.
+"""
+
+from __future__ import annotations
+
+import copy
+from collections.abc import AsyncIterator, Iterator
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Generic,
+    TypeVar,
+    cast,
+)
+
+from pydantic import BaseModel
+
+from ._transport import as_dict, validate_run_result
+from .types import (
+    AnyBareRunResult,
+    BareRunResult,
+    RequestOptions,
+    RunResult,
+)
+
+if TYPE_CHECKING:
+    from ._async_client import AsyncAnyAPI
+    from ._client import AnyAPI
+
+__all__ = ["Paginator", "AsyncPaginator", "paginate", "apaginate"]
+
+Item = TypeVar("Item")
+Data = TypeVar("Data")
+
+_NEXT_CURSOR = "nextCursor"
+_CURSOR = "cursor"
+
+
+def _raw_page_data(raw: dict[str, Any], bare: bool) -> dict[str, Any] | None:
+    """The page data dict from the RAW run dict, per envelope, using WIRE keys.
+
+    For a bare SKU the data IS ``raw["output"]``; for a found-data SKU it is
+    ``raw["output"]["data"]`` when ``found`` is true, else None. Reading from the
+    raw dict (not the validated model) keeps cursor/items lookups keyed on the
+    camelCase wire names even though the model exposes snake_case attributes.
+    """
+    output = raw.get("output")
+    if not isinstance(output, dict):
+        return None
+    output_dict = cast("dict[str, Any]", output)
+    if bare:
+        return output_dict
+    if output_dict.get("found") is not True:
+        return None
+    data = output_dict.get("data")
+    return cast("dict[str, Any]", data) if isinstance(data, dict) else None
+
+
+def _field(data: dict[str, Any] | None, key: str) -> object:
+    """Read a WIRE-keyed field from the raw page data dict."""
+    if data is None:
+        return None
+    return data.get(key)
+
+
+def _validate_page(
+    raw: dict[str, Any],
+    data_model: type[BaseModel] | None,
+    bare: bool,
+) -> RunResult[Any] | BareRunResult[Any]:
+    """Validate a raw run dict into the typed page result (found-data or bare)."""
+    if bare:
+        if data_model is None:
+            return AnyBareRunResult.model_validate(raw)
+        return BareRunResult[data_model].model_validate(raw)  # type: ignore[valid-type]
+    if data_model is None:
+        return validate_run_result(raw)
+    return RunResult[data_model].model_validate(raw)  # type: ignore[valid-type]
+
+
+def _validate_item(item: object, item_model: type[BaseModel] | None) -> Any:
+    """Validate one page item into its pydantic model (or pass scalars through)."""
+    if item_model is None:
+        return item
+    return item_model.model_validate(item)
+
+
+class Paginator(Generic[Item, Data]):
+    """Sync cursor walk over a paginated SKU."""
+
+    def __init__(
+        self,
+        client: AnyAPI,
+        slug: str,
+        input: dict[str, Any],
+        items_field: str,
+        item_model: type[BaseModel] | None,
+        data_model: type[BaseModel] | None,
+        bare: bool,
+        options: Any = None,
+    ) -> None:
+        self._client = client
+        self._slug = slug
+        self._input = copy.deepcopy(input)
+        self._items_field = items_field
+        self._item_model = item_model
+        self._data_model = data_model
+        self._bare = bare
+        self._options = options
+        self._cap = _max_items(options)
+        self._page_options = _page_options(options)
+
+    def _walk(
+        self,
+    ) -> Iterator[tuple[RunResult[Data] | BareRunResult[Data], dict[str, Any] | None]]:
+        cursor: str | None = None
+        while True:
+            page_input = dict(self._input)
+            if cursor is not None:
+                page_input[_CURSOR] = cursor
+            raw = self._client._run_raw(  # pyright: ignore[reportPrivateUsage]
+                self._slug,
+                page_input,
+                cast("RequestOptions | None", self._page_options),
+            )
+            page = _validate_page(raw, self._data_model, self._bare)
+            data = _raw_page_data(raw, self._bare)
+            yield cast("RunResult[Data] | BareRunResult[Data]", page), data
+            cursor = _next_cursor(data)
+            if cursor is None:
+                return
+
+    def pages(self) -> Iterator[RunResult[Data] | BareRunResult[Data]]:
+        """Yield whole run-result pages (read ``cost_usd`` per page)."""
+        for page, _ in self._walk():
+            yield page
+
+    def __iter__(self) -> Iterator[Item]:
+        count = 0
+        for _page, data in self._walk():
+            for item in _items(data, self._items_field):
+                if self._cap is not None and count >= self._cap:
+                    return
+                yield cast("Item", _validate_item(item, self._item_model))
+                count += 1
+            if self._cap is not None and count >= self._cap:
+                return
+
+
+class AsyncPaginator(Generic[Item, Data]):
+    """Async cursor walk over a paginated SKU."""
+
+    def __init__(
+        self,
+        client: AsyncAnyAPI,
+        slug: str,
+        input: dict[str, Any],
+        items_field: str,
+        item_model: type[BaseModel] | None,
+        data_model: type[BaseModel] | None,
+        bare: bool,
+        options: Any = None,
+    ) -> None:
+        self._client = client
+        self._slug = slug
+        self._input = copy.deepcopy(input)
+        self._items_field = items_field
+        self._item_model = item_model
+        self._data_model = data_model
+        self._bare = bare
+        self._options = options
+        self._cap = _max_items(options)
+        self._page_options = _page_options(options)
+
+    async def _walk(
+        self,
+    ) -> AsyncIterator[
+        tuple[RunResult[Data] | BareRunResult[Data], dict[str, Any] | None]
+    ]:
+        cursor: str | None = None
+        while True:
+            page_input = dict(self._input)
+            if cursor is not None:
+                page_input[_CURSOR] = cursor
+            raw = await self._client._arun_raw(  # pyright: ignore[reportPrivateUsage]
+                self._slug,
+                page_input,
+                cast("RequestOptions | None", self._page_options),
+            )
+            page = _validate_page(raw, self._data_model, self._bare)
+            data = _raw_page_data(raw, self._bare)
+            yield cast("RunResult[Data] | BareRunResult[Data]", page), data
+            cursor = _next_cursor(data)
+            if cursor is None:
+                return
+
+    async def pages(self) -> AsyncIterator[RunResult[Data] | BareRunResult[Data]]:
+        """Yield whole run-result pages (read ``cost_usd`` per page)."""
+        async for page, _ in self._walk():
+            yield page
+
+    async def __aiter__(self) -> AsyncIterator[Item]:
+        count = 0
+        async for _page, data in self._walk():
+            for item in _items(data, self._items_field):
+                if self._cap is not None and count >= self._cap:
+                    return
+                yield cast("Item", _validate_item(item, self._item_model))
+                count += 1
+            if self._cap is not None and count >= self._cap:
+                return
+
+
+def _items(data: dict[str, Any] | None, items_field: str) -> list[Any]:
+    raw_items = _field(data, items_field)
+    if isinstance(raw_items, (list, tuple)):
+        return list(cast("list[Any]", raw_items))
+    return []
+
+
+def _next_cursor(data: dict[str, Any] | None) -> str | None:
+    next_cursor = _field(data, _NEXT_CURSOR)
+    if isinstance(next_cursor, str) and next_cursor:
+        return next_cursor
+    return None
+
+
+def _max_items(options: object) -> int | None:
+    cap = as_dict(options).get("max_items")
+    return cap if isinstance(cap, int) else None
+
+
+def _page_options(options: object) -> object:
+    """Strip max_items before sending: the iterator paces itself (SPEC 2.5)."""
+    if not isinstance(options, dict):
+        return options
+    source = as_dict(cast("object", options))
+    if "max_items" not in source:
+        return source or None
+    stripped: dict[str, object] = dict(source)
+    stripped.pop("max_items", None)
+    return stripped or None
+
+
+def paginate(
+    client: AnyAPI,
+    slug: str,
+    input: dict[str, Any],
+    items_field: str,
+    item_model: type[BaseModel] | None = None,
+    data_model: type[BaseModel] | None = None,
+    bare: bool = False,
+    options: Any = None,
+) -> Paginator[Any, Any]:
+    """Build a sync Paginator bound to the client's run seam (emitter target)."""
+    return Paginator(
+        client, slug, input, items_field, item_model, data_model, bare, options
+    )
+
+
+def apaginate(
+    client: AsyncAnyAPI,
+    slug: str,
+    input: dict[str, Any],
+    items_field: str,
+    item_model: type[BaseModel] | None = None,
+    data_model: type[BaseModel] | None = None,
+    bare: bool = False,
+    options: Any = None,
+) -> AsyncPaginator[Any, Any]:
+    """Build an async Paginator bound to the client's run seam (emitter target)."""
+    return AsyncPaginator(
+        client, slug, input, items_field, item_model, data_model, bare, options
+    )

getanyapi/_transport.py

@@ -0,0 +1,239 @@
+"""Shared wire and retry engine for the sync and async clients (SPEC 2.2, 2.8).
+
+Both :class:`getanyapi.AnyAPI` and :class:`getanyapi.AsyncAnyAPI` route every SKU run
+through here. The wire contract is frozen:
+
+    POST {base_url}/v1/run/{slug}
+    Authorization: Bearer <api_key>
+    Content-Type: application/json
+    Accept: application/json
+    body = json(input)
+    query params (only when set): fields (comma-joined), max_items, summary=true
+
+HTTP 200 parses into ``RunResult[Any]``; any other status maps to the frozen
+error hierarchy. Retries cover only HTTP 429 and network failures, never
+timeouts, with jittered exponential backoff honoring ``Retry-After`` on 429.
+"""
+
+from __future__ import annotations
+
+import email.utils
+import random
+import time
+from datetime import datetime, timezone
+from typing import Any, cast
+
+import httpx
+from pydantic import ValidationError
+
+from ._errors import (
+    AnyAPIError,
+    ConnectionError,
+    RateLimitedError,
+    TimeoutError,
+    error_for_status,
+)
+from .types import RequestOptions, RunResult
+
+__all__ = [
+    "build_request",
+    "parse_raw",
+    "validate_run_result",
+    "compute_delay",
+    "RetryState",
+    "error_message",
+    "as_dict",
+    "is_retryable_error",
+    "sleep",
+]
+
+_BASE_DELAY = 0.5  # seconds
+_MAX_DELAY = 8.0  # seconds
+_REQUEST_ID_HEADER = "x-request-id"
+_RNG = random.Random()
+
+
+def _query_params(options: RequestOptions | None) -> dict[str, str]:
+    """Build the response-shaping query params from options (SPEC 2.2)."""
+    params: dict[str, str] = {}
+    if not options:
+        return params
+    fields = options.get("fields")
+    if fields:
+        params["fields"] = ",".join(fields)
+    max_items = options.get("max_items")
+    if max_items is not None:
+        params["max_items"] = str(max_items)
+    if options.get("summary"):
+        params["summary"] = "true"
+    return params
+
+
+def build_request(
+    *,
+    base_url: str,
+    slug: str,
+    input: dict[str, Any],
+    api_key: str,
+    options: RequestOptions | None,
+    timeout: float,
+) -> httpx.Request:
+    """Assemble the httpx.Request for a SKU run (no client bound).
+
+    The per-request timeout is carried on the request's ``extensions`` so it
+    applies on ``client.send(request)`` without depending on the client default.
+    """
+    url = f"{base_url.rstrip('/')}/v1/run/{slug}"
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    }
+    return httpx.Request(
+        "POST",
+        url,
+        params=_query_params(options),
+        headers=headers,
+        json=input,
+        extensions={"timeout": httpx.Timeout(timeout).as_dict()},
+    )
+
+
+def _fallback_message(status: int) -> str:
+    return f"request failed with status {status}"
+
+
+def as_dict(value: object) -> dict[str, object]:
+    """Narrow an arbitrary JSON value to a str-keyed dict (empty if not one)."""
+    if isinstance(value, dict):
+        return cast("dict[str, object]", value)
+    return {}
+
+
+def error_message(body: object, status: int) -> str:
+    """Extract the ``{error}`` string from a JSON body, else a generic message."""
+    err = as_dict(body).get("error")
+    if isinstance(err, str):
+        return err
+    return _fallback_message(status)
+
+
+def parse_raw(response: httpx.Response) -> dict[str, Any]:
+    """Return the parsed JSON dict on 200, or raise the mapped error otherwise.
+
+    The raw-dict seam (SPEC N2): generated methods validate this dict directly
+    into their concrete ``RunResult[XData]`` / ``BareRunResult[XData]`` model, so
+    there is no model_validate(model_dump(...)) double-parse. The bare-vs-found
+    envelope choice is the caller's (the generated code knows its SKU's shape).
+    """
+    request_id = response.headers.get(_REQUEST_ID_HEADER)
+    if response.status_code == 200:
+        try:
+            body = response.json()
+        except ValueError as exc:
+            raise AnyAPIError(
+                f"could not parse run response: {exc}",
+                status=200,
+                request_id=request_id,
+            ) from exc
+        if not isinstance(body, dict):
+            raise AnyAPIError(
+                "run response was not a JSON object",
+                status=200,
+                request_id=request_id,
+            )
+        return cast("dict[str, Any]", body)
+
+    err_body: object = None
+    try:
+        err_body = response.json()
+    except ValueError:
+        err_body = None
+    message = error_message(err_body, response.status_code)
+    raise error_for_status(
+        response.status_code, message, request_id=request_id
+    )
+
+
+def validate_run_result(raw: dict[str, Any]) -> RunResult[Any]:
+    """Validate a raw run dict into a generic ``RunResult[Any]`` (found-data).
+
+    Used by the generic ``client.run(slug, ...)`` helper. Bare SKUs are best
+    reached through their typed namespace method (which validates into a
+    ``BareRunResult``); the generic path assumes the found-data envelope.
+    """
+    try:
+        return RunResult[Any].model_validate(raw)
+    except ValidationError as exc:
+        raise AnyAPIError(
+            f"could not parse run response: {exc}", status=200
+        ) from exc
+
+
+def _retry_after_seconds(response: httpx.Response) -> float | None:
+    """Parse a Retry-After header (seconds or HTTP-date), capped at max delay."""
+    raw = response.headers.get("retry-after")
+    if not raw:
+        return None
+    raw = raw.strip()
+    try:
+        secs = float(raw)
+    except ValueError:
+        secs = None
+    if secs is not None:
+        return min(max(secs, 0.0), _MAX_DELAY)
+    try:
+        parsed = email.utils.parsedate_to_datetime(raw)
+    except (TypeError, ValueError):
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    delta = (parsed - datetime.now(timezone.utc)).total_seconds()
+    return min(max(delta, 0.0), _MAX_DELAY)
+
+
+def compute_delay(attempt: int, rng: random.Random | None = None) -> float:
+    """Jittered exponential backoff for retry ``attempt`` (0-based) (SPEC 2.8)."""
+    r: random.Random = rng or _RNG
+    base = min(_BASE_DELAY * float(2 ** attempt), _MAX_DELAY)
+    jitter = 0.5 + r.random()
+    return base * jitter
+
+
+class RetryState:
+    """Tracks retry budget and computes the next delay across attempts.
+
+    Shared by the sync and async run loops so the retry policy lives in one
+    place. The caller drives the loop; this object only decides whether another
+    attempt is allowed and how long to wait.
+    """
+
+    def __init__(self, max_retries: int) -> None:
+        self.max_retries = max(0, max_retries)
+        self.attempt = 0
+
+    @property
+    def can_retry(self) -> bool:
+        return self.attempt < self.max_retries
+
+    def next_delay(self, response: httpx.Response | None) -> float:
+        """Delay before the next retry; honors Retry-After on a 429 response."""
+        delay = compute_delay(self.attempt)
+        if response is not None:
+            retry_after = _retry_after_seconds(response)
+            if retry_after is not None:
+                delay = retry_after
+        self.attempt += 1
+        return delay
+
+
+def is_retryable_error(exc: AnyAPIError) -> bool:
+    """Retry only rate limits and connection failures, never timeouts."""
+    if isinstance(exc, TimeoutError):
+        return False
+    return isinstance(exc, (RateLimitedError, ConnectionError))
+
+
+def sleep(seconds: float) -> None:
+    """Blocking sleep seam (monkeypatched in tests)."""
+    time.sleep(seconds)