status302 1.5.0__py3-none-any.whl

status302/__init__.py

@@ -0,0 +1,69 @@
+"""Official Python SDK for the Status302 API."""
+
+from . import types
+from ._base import APIResponse, CachedResponse, ETagCache, MemoryETagCache, NotModified
+from ._client import AsyncStatus302, Status302
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    NotFoundError,
+    PermissionDeniedError,
+    PlanRequiredError,
+    RateLimitError,
+    ServerError,
+    Status302Error,
+)
+from ._ratelimit import RateLimitInfo, RateLimitPolicy, parse_rate_limit, parse_retry_after
+from ._version import __version__
+from .stream import (
+    DataMessage,
+    ErrorMessage,
+    ResyncMessage,
+    StreamClosedError,
+    Subscription,
+    SubscriptionError,
+    Status302Stream,
+    stream_url,
+)
+from .webhooks import WebhookVerificationError, sign_webhook, verify_webhook
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APIResponse",
+    "AsyncStatus302",
+    "AuthenticationError",
+    "BadRequestError",
+    "CachedResponse",
+    "ConflictError",
+    "DataMessage",
+    "ETagCache",
+    "ErrorMessage",
+    "MemoryETagCache",
+    "NotFoundError",
+    "NotModified",
+    "PermissionDeniedError",
+    "PlanRequiredError",
+    "RateLimitError",
+    "RateLimitInfo",
+    "RateLimitPolicy",
+    "ResyncMessage",
+    "ServerError",
+    "StreamClosedError",
+    "Subscription",
+    "SubscriptionError",
+    "Status302",
+    "Status302Error",
+    "Status302Stream",
+    "WebhookVerificationError",
+    "__version__",
+    "parse_rate_limit",
+    "parse_retry_after",
+    "sign_webhook",
+    "stream_url",
+    "types",
+    "verify_webhook",
+]

status302/_base.py

@@ -0,0 +1,444 @@
+"""HTTP transport shared by the sync and async clients: auth, retries, errors."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import random
+import threading
+import time
+from collections import OrderedDict
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, Generic, Protocol, TypeVar
+from urllib.parse import quote
+
+import httpx
+
+from ._errors import APIConnectionError, error_for
+from ._ratelimit import RateLimitInfo, parse_rate_limit, parse_retry_after
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.status302.com"
+IDEMPOTENT = frozenset({"GET", "HEAD", "PUT", "DELETE", "OPTIONS"})
+BASE_DELAY = 0.5
+MAX_DELAY = 30.0
+
+T_co = TypeVar("T_co", covariant=True)
+
+
+@dataclass(frozen=True)
+class APIResponse(Generic[T_co]):
+    """A decoded response with its status, headers and rate limit state."""
+
+    data: T_co
+    status: int
+    """HTTP status; 304 when the body was revalidated from the client's ``etag_cache`` or is ``NotModified``."""
+    headers: httpx.Headers
+    rate_limit: RateLimitInfo | None
+
+    @property
+    def etag(self) -> str | None:
+        """The ``ETag`` response header: pass it as ``if_none_match`` to revalidate."""
+        etag: str | None = self.headers.get("etag")
+        return etag
+
+
+@dataclass(frozen=True)
+class NotModified:
+    """The answer to a conditional request (``if_none_match``) while the copy with that ETag is still current (HTTP 304)."""
+
+    etag: str | None
+    """The current ETag, equal to (one of) the ETags sent."""
+    headers: httpx.Headers
+    rate_limit: RateLimitInfo | None
+
+    @property
+    def status(self) -> int:
+        return 304
+
+
+@dataclass(frozen=True)
+class CachedResponse:
+    """A response body stored by an ``ETagCache``, keyed by request URL."""
+
+    etag: str
+    content: bytes
+    content_type: str
+
+
+class ETagCache(Protocol):
+    """Store of the client's ``etag_cache`` option.
+
+    Entries never go stale: an ETag hashes its body, so a 304 proves the stored body is current.
+    """
+
+    def get(self, key: str) -> CachedResponse | None: ...
+
+    def set(self, key: str, value: CachedResponse) -> None: ...
+
+
+class MemoryETagCache:
+    """Thread-safe in-memory ``ETagCache`` keeping the ``max_entries`` most recently used responses."""
+
+    def __init__(self, max_entries: int = 1000) -> None:
+        if max_entries < 1:
+            raise ValueError("max_entries must be positive")
+        self._max_entries = max_entries
+        self._entries: OrderedDict[str, CachedResponse] = OrderedDict()
+        self._lock = threading.Lock()
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def get(self, key: str) -> CachedResponse | None:
+        with self._lock:
+            entry = self._entries.get(key)
+            if entry is not None:
+                self._entries.move_to_end(key)
+            return entry
+
+    def set(self, key: str, value: CachedResponse) -> None:
+        with self._lock:
+            self._entries[key] = value
+            self._entries.move_to_end(key)
+            if len(self._entries) > self._max_entries:
+                self._entries.popitem(last=False)
+
+
+def backoff(attempt: int) -> float:
+    """Exponential backoff with full jitter: random in [0, min(30 s, 0.5 s * 2**attempt)]."""
+    return random.uniform(0, min(MAX_DELAY, BASE_DELAY * 2**attempt))
+
+
+QueryItems = list[tuple[str, str | int | float | bool | None]]
+
+
+def _query_items(query: Mapping[str, Any] | None, exploded: Sequence[str]) -> QueryItems:
+    """Encodes query parameters: arrays are comma-separated unless the spec explodes them."""
+    items: QueryItems = []
+    for key, value in (query or {}).items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            items.append((key, "true" if value else "false"))
+        elif isinstance(value, (list, tuple)):
+            if key in exploded:
+                items.extend((key, _scalar(v)) for v in value)
+            elif value:
+                items.append((key, ",".join(_scalar(v) for v in value)))
+        else:
+            items.append((key, _scalar(value)))
+    return items
+
+
+def _scalar(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def _problem(response: httpx.Response) -> dict[str, Any]:
+    try:
+        body = response.json()
+    except (ValueError, json.JSONDecodeError):
+        body = None
+    if isinstance(body, dict) and isinstance(body.get("title"), str):
+        return {"type": "about:blank", "status": response.status_code, **body}
+    problem: dict[str, Any] = {"type": "about:blank", "title": response.reason_phrase or f"HTTP {response.status_code}", "status": response.status_code}
+    if response.text:
+        problem["detail"] = response.text[:500]
+    return problem
+
+
+def _decode(content: bytes, content_type: str, kind: str) -> Any:
+    if kind == "none":
+        return None
+    if kind == "bytes":
+        return content
+    if kind == "text" or "json" not in content_type:
+        return content.decode()
+    return json.loads(content)
+
+
+class _Attempt:
+    """Request state shared by the sync and async send loops: headers and the ETag cache entry."""
+
+    def __init__(self, core: _Core, method: str, url: str, params: QueryItems, headers: dict[str, str], if_none_match: str | None) -> None:
+        if if_none_match is not None:
+            headers["If-None-Match"] = if_none_match
+        # The cache revalidates only requests without a caller-chosen condition.
+        explicit = any(h.lower() == "if-none-match" for h in headers)
+        self.cache = core.etag_cache if method == "GET" and not explicit else None
+        self.key = str(httpx.URL(url, params=params or None))
+        self.cached = self.cache.get(self.key) if self.cache is not None else None
+        if self.cached is not None:
+            headers["If-None-Match"] = self.cached.etag
+        self.headers = headers
+
+    def result(self, response: httpx.Response, kind: str, rate_limit: RateLimitInfo | None) -> APIResponse[Any]:
+        """The response of a 304 or a 2xx answer."""
+        status = response.status_code
+        if status == 304:
+            if self.cached is not None:
+                data: Any = _decode(self.cached.content, self.cached.content_type, kind)
+            else:
+                data = NotModified(response.headers.get("etag"), response.headers, rate_limit)
+            return APIResponse(data, status, response.headers, rate_limit)
+        content_type = response.headers.get("content-type", "")
+        etag = response.headers.get("etag")
+        if self.cache is not None and etag and status == 200:
+            self.cache.set(self.key, CachedResponse(etag, response.content, content_type))
+        data = None if status == 204 else _decode(response.content, content_type, kind)
+        return APIResponse(data, status, response.headers, rate_limit)
+
+
+class _Core:
+    def __init__(
+        self,
+        api_key: str | None,
+        base_url: str,
+        max_retries: int,
+        max_retry_after: float,
+        etag_cache: ETagCache | None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self.max_retries = max_retries
+        self.max_retry_after = max_retry_after
+        self.etag_cache = etag_cache
+
+    def _headers(self, has_body: bool, extra: Mapping[str, str] | None) -> dict[str, str]:
+        headers = {"Accept": "application/json, application/problem+json", "User-Agent": f"status302-python/{__version__}"}
+        if self._api_key:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+        if has_body:
+            headers["Content-Type"] = "application/json"
+        if extra:
+            headers.update(extra)
+        return headers
+
+    def _url(self, path: str, path_params: Mapping[str, Any] | None) -> str:
+        for name, value in (path_params or {}).items():
+            path = path.replace("{" + name + "}", quote(str(value), safe=""))
+        if "{" in path:
+            raise TypeError(f"missing path parameter in {path}")
+        return self.base_url + path
+
+    def _retry_delay(self, status: int, idempotent: bool, attempt: int, retry_after: int | None) -> float | None:
+        """Seconds to wait before retrying, or None when the error is final."""
+        if attempt >= self.max_retries:
+            return None
+        # 429 means the request was refused before it ran, so any method may retry it.
+        retryable = status == 429 or (status >= 500 and idempotent) or (status == 503 and retry_after is not None)
+        if not retryable:
+            return None
+        if retry_after is not None:
+            return float(retry_after) if retry_after <= self.max_retry_after else None
+        return backoff(attempt)
+
+
+class SyncTransport(_Core):
+    """Blocking transport over ``httpx.Client``."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        max_retries: int = 3,
+        max_retry_after: float = 60,
+        timeout: float = 30.0,
+        http_client: httpx.Client | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+        etag_cache: ETagCache | None = None,
+    ) -> None:
+        super().__init__(api_key, base_url, max_retries, max_retry_after, etag_cache)
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self._sleep = sleep
+
+    def close(self) -> None:
+        self._http.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        path_params: Mapping[str, Any] | None = None,
+        query: Mapping[str, Any] | None = None,
+        body: Any = None,
+        headers: Mapping[str, str] | None = None,
+        kind: str = "json",
+        exploded: Sequence[str] = (),
+        if_none_match: str | None = None,
+    ) -> APIResponse[Any]:
+        """Sends a request and returns the decoded body with status, headers, ETag and rate limit state.
+
+        With ``if_none_match`` the data is ``NotModified`` while the representation still has that ETag.
+        """
+        return self._send(method.upper(), self._url(path, path_params), _query_items(query, exploded), body, headers, kind, if_none_match)
+
+    def get_path(self, path_and_query: str) -> Any:
+        """GETs a REST path returned by the API itself (a stream ``snapshot``), including its query string."""
+        if not path_and_query.startswith("/"):
+            raise ValueError("get_path expects a path starting with /")
+        return self._send("GET", self.base_url + path_and_query, [], None, None, "json", None).data
+
+    def _respond(
+        self,
+        method: str,
+        path: str,
+        path_params: Mapping[str, Any] | None,
+        query: Mapping[str, Any] | None,
+        body: Any,
+        kind: str,
+        exploded: Sequence[str],
+        if_none_match: str | None = None,
+    ) -> APIResponse[Any]:
+        return self.request(
+            method, path, path_params=path_params, query=query, body=body, kind=kind, exploded=exploded, if_none_match=if_none_match
+        )
+
+    def _call(
+        self,
+        method: str,
+        path: str,
+        path_params: Mapping[str, Any] | None,
+        query: Mapping[str, Any] | None,
+        body: Any,
+        kind: str,
+        exploded: Sequence[str],
+        if_none_match: str | None = None,
+    ) -> Any:
+        return self._respond(method, path, path_params, query, body, kind, exploded, if_none_match).data
+
+    def _send(
+        self, method: str, url: str, params: QueryItems, body: Any, extra: Mapping[str, str] | None, kind: str, if_none_match: str | None
+    ) -> APIResponse[Any]:
+        state = _Attempt(self, method, url, params, self._headers(body is not None, extra), if_none_match)
+        content = None if body is None else json.dumps(body).encode()
+        idempotent = method in IDEMPOTENT
+        attempt = 0
+        while True:
+            try:
+                response = self._http.request(method, url, params=params or None, headers=state.headers, content=content)
+            except httpx.TransportError as exc:
+                if idempotent and attempt < self.max_retries:
+                    self._sleep(backoff(attempt))
+                    attempt += 1
+                    continue
+                raise APIConnectionError(f"{method} {url}: {exc}") from exc
+            rate_limit = parse_rate_limit(response.headers)
+            if response.is_success or response.status_code == 304:
+                return state.result(response, kind, rate_limit)
+            retry_after = parse_retry_after(response.headers.get("retry-after"))
+            error = error_for(response.status_code, _problem(response), response.headers, rate_limit, retry_after)
+            delay = self._retry_delay(response.status_code, idempotent, attempt, retry_after)
+            if delay is None:
+                raise error
+            self._sleep(delay)
+            attempt += 1
+
+
+class AsyncTransport(_Core):
+    """Asyncio transport over ``httpx.AsyncClient``."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        max_retries: int = 3,
+        max_retry_after: float = 60,
+        timeout: float = 30.0,
+        http_client: httpx.AsyncClient | None = None,
+        sleep: Callable[[float], Any] = asyncio.sleep,
+        etag_cache: ETagCache | None = None,
+    ) -> None:
+        super().__init__(api_key, base_url, max_retries, max_retry_after, etag_cache)
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+        self._sleep = sleep
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        path_params: Mapping[str, Any] | None = None,
+        query: Mapping[str, Any] | None = None,
+        body: Any = None,
+        headers: Mapping[str, str] | None = None,
+        kind: str = "json",
+        exploded: Sequence[str] = (),
+        if_none_match: str | None = None,
+    ) -> APIResponse[Any]:
+        """Sends a request and returns the decoded body with status, headers, ETag and rate limit state.
+
+        With ``if_none_match`` the data is ``NotModified`` while the representation still has that ETag.
+        """
+        return await self._send(method.upper(), self._url(path, path_params), _query_items(query, exploded), body, headers, kind, if_none_match)
+
+    async def get_path(self, path_and_query: str) -> Any:
+        """GETs a REST path returned by the API itself (a stream ``snapshot``), including its query string."""
+        if not path_and_query.startswith("/"):
+            raise ValueError("get_path expects a path starting with /")
+        return (await self._send("GET", self.base_url + path_and_query, [], None, None, "json", None)).data
+
+    async def _arespond(
+        self,
+        method: str,
+        path: str,
+        path_params: Mapping[str, Any] | None,
+        query: Mapping[str, Any] | None,
+        body: Any,
+        kind: str,
+        exploded: Sequence[str],
+        if_none_match: str | None = None,
+    ) -> APIResponse[Any]:
+        return await self.request(
+            method, path, path_params=path_params, query=query, body=body, kind=kind, exploded=exploded, if_none_match=if_none_match
+        )
+
+    async def _acall(
+        self,
+        method: str,
+        path: str,
+        path_params: Mapping[str, Any] | None,
+        query: Mapping[str, Any] | None,
+        body: Any,
+        kind: str,
+        exploded: Sequence[str],
+        if_none_match: str | None = None,
+    ) -> Any:
+        return (await self._arespond(method, path, path_params, query, body, kind, exploded, if_none_match)).data
+
+    async def _send(
+        self, method: str, url: str, params: QueryItems, body: Any, extra: Mapping[str, str] | None, kind: str, if_none_match: str | None
+    ) -> APIResponse[Any]:
+        state = _Attempt(self, method, url, params, self._headers(body is not None, extra), if_none_match)
+        content = None if body is None else json.dumps(body).encode()
+        idempotent = method in IDEMPOTENT
+        attempt = 0
+        while True:
+            try:
+                response = await self._http.request(method, url, params=params or None, headers=state.headers, content=content)
+            except httpx.TransportError as exc:
+                if idempotent and attempt < self.max_retries:
+                    await self._sleep(backoff(attempt))
+                    attempt += 1
+                    continue
+                raise APIConnectionError(f"{method} {url}: {exc}") from exc
+            rate_limit = parse_rate_limit(response.headers)
+            if response.is_success or response.status_code == 304:
+                return state.result(response, kind, rate_limit)
+            retry_after = parse_retry_after(response.headers.get("retry-after"))
+            error = error_for(response.status_code, _problem(response), response.headers, rate_limit, retry_after)
+            delay = self._retry_delay(response.status_code, idempotent, attempt, retry_after)
+            if delay is None:
+                raise error
+            await self._sleep(delay)
+            attempt += 1

status302/_client.py

@@ -0,0 +1,100 @@
+"""The public clients: ``Status302`` (blocking) and ``AsyncStatus302`` (asyncio)."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
+from typing import Any
+
+from ._operations import AsyncOperations, SyncOperations
+from .stream import Status302Stream
+
+
+def _advance(page: Any, kwargs: dict[str, Any]) -> bool:
+    """Sets the next page's ``cursor`` or ``before`` argument; False on the last page."""
+    cursor = page.get("nextCursor")
+    if cursor:
+        kwargs["cursor"] = cursor
+        return True
+    before = page.get("nextBefore")
+    if before is not None:
+        kwargs["before"] = before
+        return True
+    return False
+
+
+class Status302(SyncOperations):
+    """Blocking Status302 API client.
+
+    >>> status302 = Status302(api_key=os.environ["STATUS302_API_KEY"])
+    >>> page = status302.list_events(country="US", limit=10)
+
+    ``etag_cache`` (e.g. ``MemoryETagCache()``) revalidates GET responses that carried an ``ETag``:
+    the next GET of the same URL sends ``If-None-Match`` and a 304 returns the stored body.
+    """
+
+    def __enter__(self) -> Status302:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def pages(self, operation: Callable[..., Any], *args: Any, **kwargs: Any) -> Iterator[Any]:
+        """Yields every page of a paginated operation.
+
+        Follows ``nextCursor`` as ``cursor``, or ``nextBefore`` as ``before`` for the collections
+        paged by id (``list_alert_rules``, ``list_alert_events``). ``operation`` is a bound list
+        method of this client, e.g. ``status302.list_events``.
+        """
+        while True:
+            page = operation(*args, **kwargs)
+            yield page
+            if not _advance(page, kwargs):
+                return
+
+    def paginate(self, operation: Callable[..., Any], *args: Any, **kwargs: Any) -> Iterator[Any]:
+        """Yields every item of a cursor-paginated operation across pages.
+
+        >>> for event in status302.paginate(status302.list_events, country="US"):
+        ...     print(event["name"])
+        """
+        for page in self.pages(operation, *args, **kwargs):
+            yield from page["items"]
+
+
+class AsyncStatus302(AsyncOperations):
+    """Asyncio Status302 API client; also creates stream connections.
+
+    >>> async with AsyncStatus302(api_key=os.environ["STATUS302_API_KEY"]) as status302:
+    ...     page = await status302.list_events(limit=10)
+
+    ``etag_cache`` works as on ``Status302``.
+    """
+
+    async def __aenter__(self) -> AsyncStatus302:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def pages(self, operation: Callable[..., Awaitable[Any]], *args: Any, **kwargs: Any) -> AsyncIterator[Any]:
+        """Yields every page of a paginated operation, following ``nextCursor`` or ``nextBefore``."""
+        while True:
+            page = await operation(*args, **kwargs)
+            yield page
+            if not _advance(page, kwargs):
+                return
+
+    async def paginate(self, operation: Callable[..., Awaitable[Any]], *args: Any, **kwargs: Any) -> AsyncIterator[Any]:
+        """Yields every item of a cursor-paginated operation across pages."""
+        async for page in self.pages(operation, *args, **kwargs):
+            for item in page["items"]:
+                yield item
+
+    async def stream_ticket(self) -> str:
+        """A single-use stream ticket (60 s) for a browser connection."""
+        return (await self.create_stream_ticket())["ticket"]
+
+    def stream(self, **options: Any) -> Status302Stream:
+        """A realtime stream authenticated with this client's API key (see ``Status302Stream``)."""
+        options.setdefault("api_key", self._api_key)
+        return Status302Stream(client=self, **options)