okdata 0.1.0__py3-none-any.whl

okdata/_money.py

@@ -0,0 +1,44 @@
+"""US dollars as decimal strings outside, Decimal inside: no float ever touches a price or budget."""
+from __future__ import annotations
+
+import re
+from decimal import ROUND_HALF_UP, Decimal, InvalidOperation
+from typing import Union
+
+_USD = re.compile(r"\d{1,12}(\.\d{1,6})?")
+MAX_PRICE = re.compile(r"\d{1,7}(\.\d{1,6})?")
+"""What X-Max-Price accepts: up to 7 digits, then up to 6 decimals."""
+_MICRO = Decimal("0.000001")
+
+
+def usd(value: Union[str, Decimal, int, float], name: str) -> Decimal:
+    """A budget or cap as a Decimal; text must be a plain decimal, numbers are rounded to 6 places."""
+    if isinstance(value, bool):
+        raise TypeError(f"{name} must be US dollars, not a bool")
+    if isinstance(value, str):
+        text = value.strip()
+        if not _USD.fullmatch(text):
+            raise ValueError(f"{name} must be US dollars as a decimal string, like '0.05'")
+        return Decimal(text)
+    try:
+        amount = Decimal(str(value)) if isinstance(value, float) else Decimal(value)
+    except (InvalidOperation, ValueError) as err:
+        raise ValueError(f"{name} must be US dollars") from err
+    if not amount.is_finite() or amount < 0:
+        raise ValueError(f"{name} must be 0 or more US dollars")
+    return amount.quantize(_MICRO, rounding=ROUND_HALF_UP)
+
+
+def text(amount: Decimal) -> str:
+    """Decimal("0.0400") -> "0.04"; Decimal("0") -> "0"."""
+    normalized = amount.quantize(_MICRO, rounding=ROUND_HALF_UP).normalize()
+    out = format(normalized, "f")
+    return out if out != "-0" else "0"
+
+
+def max_price_header(value: Union[str, Decimal, int, float]) -> str:
+    """The price cap as X-Max-Price wants it."""
+    out = text(usd(value, "max_price"))
+    if not MAX_PRICE.fullmatch(out):
+        raise ValueError("max_price must be at most 7 digits before the point, like '0.05'")
+    return out

okdata/_paging.py

@@ -0,0 +1,208 @@
+"""pages() and items(): follow page.next_cursor with the same parameters, and stop before the next
+call could take the total past max_spend (counted from meta.billing.amount of the pages so far)."""
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Any, AsyncIterator, Awaitable, Callable, Dict, Generic, Iterator, Literal, Mapping, Optional, Tuple, TypeVar
+
+from ._errors import OkDataError
+from ._money import text, usd
+from ._types import EndpointInfo, Page, Price, Result
+
+T = TypeVar("T")
+StopReason = Literal["end", "max_pages", "max_items", "max_spend", "balance"]
+"""Why paging ended: no next page, a limit you set, or a balance that will not cover the next page."""
+
+
+def _positive(n: Optional[int], name: str) -> Optional[int]:
+    if n is not None and (isinstance(n, bool) or not isinstance(n, int) or n < 1):
+        raise ValueError(f"{name} must be a whole number, 1 or more")
+    return n
+
+
+class _Budget:
+    """The paging state both pagers share: pages, spend, the per-call cap, why it stopped."""
+
+    def __init__(self, endpoint_id: str, info: Optional[EndpointInfo], params: Mapping[str, Any],
+                 max_pages: Optional[int], max_spend: Optional[Price]) -> None:
+        if info is not None and not info.list:
+            raise TypeError(f"{endpoint_id} returns one object, not pages")
+        self.endpoint_id = endpoint_id
+        self.worst = Decimal(info.max_charge) if info is not None else Decimal(0)
+        self.params: Dict[str, Any] = dict(params)
+        self.max_pages = _positive(max_pages, "max_pages")
+        self.max_spend = usd(max_spend, "max_spend") if max_spend is not None else None
+        cap = self.params.get("max_price")
+        self.user_cap = usd(cap, "max_price") if cap is not None else None
+        self.spent = Decimal(0)
+        self.calls = 0
+        self.stop_reason: Optional[StopReason] = None
+        self.started = False
+
+    def start(self) -> None:
+        if self.started:
+            raise RuntimeError("a pager can be iterated once; call pages() again for a new run")
+        self.started = True
+
+    def next_call(self) -> Optional[Tuple[Dict[str, Any], bool]]:
+        """The params of the next call and whether our own cap is on it, or None to stop."""
+        if self.max_pages is not None and self.calls >= self.max_pages:
+            self.stop_reason = "max_pages"
+            return None
+        left = self.max_spend - self.spent if self.max_spend is not None else None
+        if left is not None and self.worst > left:
+            self.stop_reason = "max_spend"
+            return None
+        capped = left is not None and (self.user_cap is None or left < self.user_cap)
+        return ({**self.params, "max_price": text(left)} if capped and left is not None else self.params), capped
+
+    def refused(self, err: OkDataError, capped: bool) -> bool:
+        """Our own cap refused a page the catalog priced lower than the server does: that is the budget."""
+        if capped and err.code == "max_price_exceeded":
+            self.stop_reason = "max_spend"
+            return True
+        return False
+
+    def after(self, result: Result) -> bool:
+        """Counts a page; True when there is a next one to fetch."""
+        if not isinstance(result, Page):
+            raise TypeError(f"{self.endpoint_id} answered with one object, not a page")
+        self.calls += 1
+        self.spent += Decimal(result.cost or "0")
+        if not result.next_cursor or not result.has_more:
+            self.stop_reason = "end"
+            return False
+        if result.meta.get("billing", {}).get("covers_next") is False:
+            self.stop_reason = "balance"
+            return False
+        self.params = {**self.params, "cursor": result.next_cursor}
+        return True
+
+
+class _Stats:
+    _budget: _Budget
+
+    @property
+    def spent(self) -> str:
+        """US dollars charged by the pages fetched so far."""
+        return text(self._budget.spent)
+
+    @property
+    def calls(self) -> int:
+        return self._budget.calls
+
+
+class Pager(_Stats, Generic[T]):
+    """Pages of one listing. Iterate it once; spent, calls and stop_reason tell how it went."""
+
+    def __init__(self, budget: _Budget, call: Callable[[Dict[str, Any]], Result]) -> None:
+        self._budget = budget
+        self._call = call
+
+    @property
+    def stop_reason(self) -> Optional[StopReason]:
+        return self._budget.stop_reason
+
+    def __iter__(self) -> Iterator[Page[T]]:
+        self._budget.start()
+        while True:
+            step = self._budget.next_call()
+            if step is None:
+                return
+            params, capped = step
+            try:
+                result = self._call(params)
+            except OkDataError as err:
+                if self._budget.refused(err, capped):
+                    return
+                raise
+            more = self._budget.after(result)
+            yield result  # type: ignore[misc]
+            if not more:
+                return
+
+
+class ItemPager(_Stats, Generic[T]):
+    """The items of one listing, page after page, up to max_items."""
+
+    def __init__(self, pager: Pager[T], max_items: Optional[int]) -> None:
+        self._pager = pager
+        self._budget = pager._budget
+        self._max_items = _positive(max_items, "max_items")
+        self._items = 0
+        self._hit = False
+
+    @property
+    def items(self) -> int:
+        return self._items
+
+    @property
+    def stop_reason(self) -> Optional[StopReason]:
+        return "max_items" if self._hit else self._pager.stop_reason
+
+    def __iter__(self) -> Iterator[T]:
+        for page in self._pager:
+            for item in page.items:
+                yield item
+                self._items += 1
+                if self._max_items is not None and self._items >= self._max_items:
+                    self._hit = True
+                    return
+
+
+class AsyncPager(_Stats, Generic[T]):
+    """The async twin of Pager: ``async for page in ok.pages(...)``."""
+
+    def __init__(self, budget: _Budget, call: Callable[[Dict[str, Any]], Awaitable[Result]]) -> None:
+        self._budget = budget
+        self._call = call
+
+    @property
+    def stop_reason(self) -> Optional[StopReason]:
+        return self._budget.stop_reason
+
+    async def __aiter__(self) -> AsyncIterator[Page[T]]:
+        self._budget.start()
+        while True:
+            step = self._budget.next_call()
+            if step is None:
+                return
+            params, capped = step
+            try:
+                result = await self._call(params)
+            except OkDataError as err:
+                if self._budget.refused(err, capped):
+                    return
+                raise
+            more = self._budget.after(result)
+            yield result  # type: ignore[misc]
+            if not more:
+                return
+
+
+class AsyncItemPager(_Stats, Generic[T]):
+    """The async twin of ItemPager."""
+
+    def __init__(self, pager: AsyncPager[T], max_items: Optional[int]) -> None:
+        self._pager = pager
+        self._budget = pager._budget
+        self._max_items = _positive(max_items, "max_items")
+        self._items = 0
+        self._hit = False
+
+    @property
+    def items(self) -> int:
+        return self._items
+
+    @property
+    def stop_reason(self) -> Optional[StopReason]:
+        return "max_items" if self._hit else self._pager.stop_reason
+
+    async def __aiter__(self) -> AsyncIterator[T]:
+        async for page in self._pager:
+            for item in page.items:
+                yield item
+                self._items += 1
+                if self._max_items is not None and self._items >= self._max_items:
+                    self._hit = True
+                    return

okdata/_request.py

@@ -0,0 +1,74 @@
+"""Turns an endpoint id and flat params into the HTTP request the contract wants: GET with query
+parameters, or POST with a JSON body when a list parameter (ids, keywords) is given to an endpoint
+that takes one. view, fields and max_price ride along; max_price becomes X-Max-Price."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple, Union
+
+from ._money import max_price_header
+from ._types import EndpointInfo
+
+_ID = re.compile(r"[a-z0-9_]+(\.[a-z0-9_]+)+")
+_FIELD = re.compile(r"[A-Za-z0-9_]+(\.[A-Za-z0-9_]+)*")
+VIEWS = ("compact", "standard", "full")
+
+
+@dataclass(frozen=True)
+class HttpRequest:
+    method: str
+    path: str
+    query: List[Tuple[str, str]] = field(default_factory=list)
+    body: Optional[Dict[str, Any]] = None
+    max_price: Optional[str] = None
+
+
+def path_of_id(endpoint_id: str) -> str:
+    """/v1/douyin/videos/search for douyin.videos.search."""
+    if not _ID.fullmatch(endpoint_id):
+        raise ValueError(f"not an endpoint id: {endpoint_id!r} (ids look like douyin.videos.search)")
+    return "/v1/" + endpoint_id.replace(".", "/")
+
+
+def field_list(fields: Union[str, Sequence[str]]) -> List[str]:
+    parts = [f.strip() for f in (fields.split(",") if isinstance(fields, str) else list(fields))]
+    parts = [p for p in parts if p]
+    if not parts:
+        raise ValueError("fields is empty; leave it out to get every field")
+    bad = [p for p in parts if not _FIELD.fullmatch(p)]
+    if bad:
+        raise ValueError(f"fields are dotted names like metrics.likes, not {bad!r}")
+    return parts
+
+
+def _query_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (list, tuple)):
+        return ",".join(str(v) for v in value)
+    return str(value)
+
+
+def _is_list(value: Any) -> bool:
+    return isinstance(value, (list, tuple))
+
+
+def build_request(endpoint_id: str, info: Optional[EndpointInfo], params: Mapping[str, Any]) -> HttpRequest:
+    values: Dict[str, Any] = {k: v for k, v in params.items() if v is not None}
+    cap = values.pop("max_price", None)
+    view = values.pop("view", None)
+    fields = values.pop("fields", None)
+    if view is not None:
+        if view not in VIEWS:
+            raise ValueError(f"view must be one of {', '.join(VIEWS)}")
+        values["view"] = view
+    if fields is not None:
+        values["fields"] = field_list(fields)
+    path = info.path if info is not None else path_of_id(endpoint_id)
+    max_price = max_price_header(cap) if cap is not None else None
+    batch = info is not None and info.post and any(info.params.get(k) == "string[]" and _is_list(v) for k, v in values.items())
+    if batch:
+        body = {k: list(v) if _is_list(v) else v for k, v in values.items()}
+        return HttpRequest("POST", path, [], body, max_price)
+    return HttpRequest("GET", path, [(k, _query_value(v)) for k, v in values.items()], None, max_price)

okdata/_result.py

@@ -0,0 +1,119 @@
+"""Success envelopes as Page / Item / Batch, error bodies as OkDataError, and when to retry."""
+from __future__ import annotations
+
+import json
+import random
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Mapping, Optional, cast
+
+from ._errors import RETRY_ADVICE, OkDataError, RetryAdvice
+from ._types import Batch, Item, Meta, Page, Result
+
+_RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})
+_IN_PROGRESS_MIN_S = 1.0
+
+
+def seconds(value: Any) -> Optional[float]:
+    """A non-negative number of seconds, or None."""
+    if isinstance(value, bool):
+        return None
+    try:
+        n = float(value)
+    except (TypeError, ValueError):
+        return None
+    return n if n >= 0 and n == n and n != float("inf") else None
+
+
+def to_result(body: Mapping[str, Any], idempotency_key: Optional[str]) -> Result:
+    meta = cast(Meta, body.get("meta") or {})
+    billing = meta.get("billing") or {}
+    data = body.get("data") or {}
+    base: Dict[str, Any] = dict(
+        request_id=str(body.get("request_id", "")),
+        capability=str(meta.get("capability", "")),
+        result_status=str(meta.get("result_status", "complete")),
+        cost=str(billing.get("amount", "0")),
+        balance_after=billing.get("balance_after") or None,
+        replayed=meta.get("replayed") is True,
+        cached=meta.get("cached") is True,
+        unavailable=dict(meta.get("unavailable") or {}),
+        warnings=list(body.get("warnings") or []),
+        meta=meta,
+        idempotency_key=idempotency_key,
+        raw=dict(body),
+    )
+    items = data.get("items")
+    page = body.get("page")
+    if isinstance(items, list) and isinstance(page, dict):
+        cursor = page.get("next_cursor")
+        return Page(
+            **base, items=items, next_cursor=cursor, cursor_expires_at=page.get("cursor_expires_at"),
+            has_more=page.get("has_more") is True and cursor is not None, returned=int(page.get("returned", len(items))),
+        )
+    if isinstance(items, list):
+        return Batch(**base, items=items, missing=list(data.get("missing") or []))
+    return Item(**base, item=cast(Dict[str, Any], data.get("item")))
+
+
+def parse_answer(status: int, headers: Mapping[str, str], text: str, idempotency_key: Optional[str]) -> Dict[str, Any]:
+    """The success envelope of an answer, or raises the OkDataError it carries."""
+    try:
+        parsed = json.loads(text) if text else None
+    except ValueError:
+        parsed = None
+    body = parsed if isinstance(parsed, dict) else None
+    if body is not None and body.get("code") == "ok" and status < 400:
+        return body
+    retry_after_header = seconds(headers.get("retry-after"))
+    if body is not None and isinstance(body.get("code"), str):
+        advice = body.get("retry")
+        raise OkDataError(
+            body["code"],
+            body["message"] if isinstance(body.get("message"), str) else body["code"],
+            status=status,
+            request_id=body["request_id"] if isinstance(body.get("request_id"), str) else headers.get("x-request-id"),
+            charged=body.get("charged", False),
+            retry=cast(RetryAdvice, advice) if advice in RETRY_ADVICE else "no",
+            retry_after_seconds=seconds(body.get("retry_after_seconds")) if body.get("retry_after_seconds") is not None else retry_after_header,
+            idempotency_key=idempotency_key,
+            body=body,
+        )
+    raise OkDataError(
+        "bad_response",
+        f"HTTP {status} without an okdata answer",
+        status=status,
+        request_id=headers.get("x-request-id"),
+        charged=None if status >= 500 or status < 300 else False,
+        retry="same_key" if status < 300 else "yes" if status in _RETRY_STATUSES else "no",
+        retry_after_seconds=retry_after_header,
+        idempotency_key=idempotency_key,
+    )
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    max_retries: int
+    base_delay: float
+    """First backoff step, seconds, when the server names no wait."""
+    max_delay: float
+    """A server-named wait longer than this is not slept through: the error is raised."""
+
+
+def retry_delay(err: OkDataError, attempt: int, policy: RetryPolicy, rand: Callable[[], float] = random.random) -> Optional[float]:
+    """Seconds to wait before the next attempt, or None to stop. ``attempt`` counts retries made so far.
+
+    yes / same_key: retry (same Idempotency-Key); once: one more try at most; no / after_fix: never.
+    """
+    if attempt >= policy.max_retries or err.retry in ("no", "after_fix"):
+        return None
+    if err.retry == "once" and attempt > 0:
+        return None
+    if err.retry_after_seconds is not None:
+        return err.retry_after_seconds if err.retry_after_seconds <= policy.max_delay else None
+    backoff = min(policy.max_delay, policy.base_delay * 2.0 ** attempt) * (0.5 + rand() / 2)
+    return max(_IN_PROGRESS_MIN_S, backoff) if err.code == "call_in_progress" else backoff
+
+
+def leaves_outcome_open(err: OkDataError) -> bool:
+    """Errors after which an earlier attempt with the same key may still have run (and been charged)."""
+    return err.charged is None or err.code == "call_in_progress"

okdata/_transport.py

@@ -0,0 +1,103 @@
+"""One logical request, sync or async: the same Idempotency-Key on every attempt, retries as the
+error body says, a per-attempt timeout, and the charge marked unknown when an earlier attempt's fate is."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable, Dict, Optional, Sequence, Tuple
+
+import httpx
+
+from ._errors import OkDataConnectionError, OkDataError
+from ._result import RetryPolicy, leaves_outcome_open, parse_answer, retry_delay
+
+
+@dataclass(frozen=True)
+class Config:
+    base_url: str
+    api_key: Optional[str] = field(repr=False)  # never in a repr, a log line or a traceback
+    timeout: float = field(default=65.0)
+    policy: RetryPolicy = field(default_factory=lambda: RetryPolicy(2, 0.5, 20.0))
+    headers: Dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Send:
+    method: str
+    path: str
+    query: Sequence[Tuple[str, str]] = ()
+    body: Optional[Dict[str, Any]] = None
+    idempotency_key: Optional[str] = None
+    max_price: Optional[str] = None
+    auth: bool = True
+    """False: send no Authorization header (the free catalog routes, the CLI link)."""
+    timeout: Optional[float] = None
+
+
+def _headers(cfg: Config, req: Send) -> Dict[str, str]:
+    headers = {"Accept": "application/json", **cfg.headers}
+    if req.auth and cfg.api_key:
+        headers["Authorization"] = f"Bearer {cfg.api_key}"
+    if req.idempotency_key:
+        headers["Idempotency-Key"] = req.idempotency_key
+    if req.max_price is not None:
+        headers["X-Max-Price"] = req.max_price
+    return headers
+
+
+def _lost(cfg: Config, req: Send, err: Exception) -> OkDataConnectionError:
+    if isinstance(err, httpx.TimeoutException):
+        limit = req.timeout if req.timeout is not None else cfg.timeout
+        return OkDataConnectionError(f"no answer from {cfg.base_url} within {limit} s", "client_timeout", req.idempotency_key)
+    return OkDataConnectionError(f"could not reach {cfg.base_url}: {err}", "connection_error", req.idempotency_key)
+
+
+def _give_up(err: OkDataError, open_outcome: bool) -> OkDataError:
+    return err.with_charged(None) if open_outcome and err.charged is False else err
+
+
+def send_sync(cfg: Config, http: httpx.Client, sleep: Callable[[float], None], req: Send) -> Dict[str, Any]:
+    """Sends one request (with its retries); returns the success envelope or raises OkDataError."""
+    open_outcome = False
+    retries = 0
+    while True:
+        try:
+            try:
+                res = http.request(req.method, cfg.base_url + req.path, params=list(req.query), json=req.body,
+                                   headers=_headers(cfg, req), timeout=req.timeout if req.timeout is not None else cfg.timeout)
+            except httpx.TransportError as err:
+                raise _lost(cfg, req, err) from err
+            return parse_answer(res.status_code, res.headers, res.text, req.idempotency_key)
+        except OkDataError as err:
+            open_outcome = open_outcome or leaves_outcome_open(err)
+            delay = retry_delay(err, retries, cfg.policy)
+            if delay is None:
+                final = _give_up(err, open_outcome)
+                if final is err:
+                    raise
+                raise final from err
+            sleep(delay)
+            retries += 1
+
+
+async def send_async(cfg: Config, http: httpx.AsyncClient, sleep: Callable[[float], Awaitable[None]], req: Send) -> Dict[str, Any]:
+    """The async twin of send_sync."""
+    open_outcome = False
+    retries = 0
+    while True:
+        try:
+            try:
+                res = await http.request(req.method, cfg.base_url + req.path, params=list(req.query), json=req.body,
+                                         headers=_headers(cfg, req), timeout=req.timeout if req.timeout is not None else cfg.timeout)
+            except httpx.TransportError as err:
+                raise _lost(cfg, req, err) from err
+            return parse_answer(res.status_code, res.headers, res.text, req.idempotency_key)
+        except OkDataError as err:
+            open_outcome = open_outcome or leaves_outcome_open(err)
+            delay = retry_delay(err, retries, cfg.policy)
+            if delay is None:
+                final = _give_up(err, open_outcome)
+                if final is err:
+                    raise
+                raise final from err
+            await sleep(delay)
+            retries += 1

okdata/_types.py

@@ -0,0 +1,123 @@
+"""What a call returns (Page, Item, Batch) and the shapes shared with the generated methods."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import Any, Dict, Generic, List, Literal, Mapping, Optional, Sequence, TypedDict, TypeVar, Union
+
+T = TypeVar("T")
+
+View = Literal["compact", "standard", "full"]
+"""compact (shortest; long text cut at 500 characters), standard (default) or full (adds ``ext``)."""
+
+Fields = Union[str, Sequence[str]]
+"""Dotted paths to keep: ``["id", "metrics.likes"]`` or ``"id,metrics.likes"``."""
+
+Price = Union[str, Decimal, int, float]
+"""US dollars. Text (``"0.05"``) or Decimal is exact; floats are rounded to 6 places."""
+
+ResultStatus = Literal["complete", "partial", "empty"]
+
+
+class Billing(TypedDict, total=False):
+    amount: str
+    """What this call cost, US dollars as a decimal string ("0" for a free replay)."""
+    currency: str
+    balance_after: str
+    covers_next: bool
+    """Sent (as false) only when what is left does not cover another call like this one."""
+    top_up_url: str
+
+
+class Meta(TypedDict, total=False):
+    capability: str
+    result_status: ResultStatus
+    billing: Billing
+    unavailable: Dict[str, str]
+    """Fields this endpoint cannot give, and why ("platform" or "capability")."""
+    cached: bool
+    replayed: bool
+    fetched_at: str
+
+
+class CallWarning(TypedDict, total=False):
+    code: str
+    """items_dropped, text_truncated, items_capped_by_balance or note."""
+    message: str
+    count: int
+    item: int
+    fields: List[str]
+
+
+class Missing(TypedDict):
+    id: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class EndpointInfo:
+    """One endpoint as the SDK needs it at run time (generated from the catalog)."""
+
+    id: str
+    path: str
+    list: bool
+    post: bool
+    """True: a list parameter (ids, keywords) sends the call as POST with a JSON body."""
+    batch_max: Optional[int]
+    unit: Literal["call", "item"]
+    price: str
+    max_charge: str
+    page_size: Optional[int]
+    params: Mapping[str, str]
+    object: str
+    title: str
+    paused: bool
+
+
+@dataclass(frozen=True)
+class _Result:
+    request_id: str
+    capability: str
+    result_status: str
+    cost: str
+    """What this call cost, US dollars as a decimal string."""
+    balance_after: Optional[str]
+    replayed: bool
+    """True when an Idempotency-Key replayed a stored result at no charge."""
+    cached: bool
+    unavailable: Dict[str, str]
+    warnings: List[CallWarning]
+    meta: Meta
+    idempotency_key: Optional[str]
+    """The key this call was sent with; resending with it never charges twice."""
+    raw: Dict[str, Any]
+    """The success envelope exactly as the API sent it."""
+
+
+@dataclass(frozen=True)
+class Page(_Result, Generic[T]):
+    """One page of a list endpoint. The next page is a new call, charged on its own."""
+
+    items: List[T]
+    next_cursor: Optional[str]
+    cursor_expires_at: Optional[str]
+    has_more: bool
+    returned: int
+
+
+@dataclass(frozen=True)
+class Item(_Result, Generic[T]):
+    """The answer of a single-object endpoint."""
+
+    item: T
+
+
+@dataclass(frozen=True)
+class Batch(_Result, Generic[T]):
+    """The batch form of a single-object endpoint (ids given): found objects and what was missing."""
+
+    items: List[T]
+    missing: List[Missing]
+
+
+Result = Union[Page[Dict[str, Any]], Item[Dict[str, Any]], Batch[Dict[str, Any]]]

okdata/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"