messagebird-sdk 0.1.0__py3-none-any.whl

bird/__init__.py

@@ -0,0 +1,65 @@
+"""The official Python SDK for the Bird email platform (ADR-0045).
+
+The wire models are generated from the OpenAPI spec into ``bird._generated`` and
+never hand-edited; this package is the hand-written, idiomatic layer on top — a
+synchronous ``Bird`` client and an asynchronous ``AsyncBird`` client, a typed
+exception hierarchy, safe retries, pagination, and webhook verification.
+"""
+
+from __future__ import annotations
+
+from bird._client import AsyncBird, Bird
+from bird._response import APIResponse
+from bird._types import (
+    Attachment,
+    EmailDefaults,
+    EmailListParams,
+    EmailSendParams,
+    RequestOptions,
+)
+from bird._generated import (
+    EmailMessage,
+    WebhookEvent,
+    WebhookEventType,
+)
+from bird._exceptions import (
+    APIConnectionError,
+    APIError,
+    APIStatusError,
+    APITimeoutError,
+    BirdError,
+    ErrorDetail,
+    ErrorType,
+    RateLimitError,
+    ValidationError,
+    WebhookVerificationError,
+)
+from bird.pagination import AsyncPage, SyncPage
+from bird._version import __version__
+
+__all__ = [
+    "Bird",
+    "AsyncBird",
+    "RequestOptions",
+    "EmailDefaults",
+    "Attachment",
+    "EmailSendParams",
+    "EmailListParams",
+    "APIResponse",
+    "SyncPage",
+    "AsyncPage",
+    "EmailMessage",
+    "WebhookEvent",
+    "WebhookEventType",
+    "BirdError",
+    "APIError",
+    "APIStatusError",
+    "RateLimitError",
+    "ValidationError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "WebhookVerificationError",
+    "ErrorDetail",
+    "ErrorType",
+    "__version__",
+]

bird/_base_client.py

@@ -0,0 +1,256 @@
+"""The request lifecycle shared by the sync and async clients.
+
+``BaseClient`` owns header assembly (SDK-owned headers always win), retries with
+jittered backoff that honors ``Retry-After``, a per-attempt timeout, and the
+once-and-reuse idempotency key for mutations — generated once per logical call so
+a retried write never double-applies (ADR-0045). ``SyncAPIClient`` and
+``AsyncAPIClient`` add the transport loop; a resource method calls ``request()``
+and never implements retries itself.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import platform
+import random
+import time
+import uuid
+from typing import Any, Mapping, TypeVar
+from urllib.parse import urlsplit
+
+import httpx
+
+from bird._constants import DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, INITIAL_RETRY_DELAY, MAX_RETRY_DELAY
+from bird._exceptions import APIConnectionError, APITimeoutError, from_response, parse_retry_after
+from bird._types import NOT_GIVEN, NotGiven
+from bird._version import __version__
+
+USER_AGENT = f"bird-sdk-python/{__version__} ({platform.python_implementation().lower()}/{platform.python_version()})"
+
+_MUTATING_METHODS = {"POST", "PUT", "PATCH", "DELETE"}
+# SDK-owned headers a caller's extra_headers must never override.
+_RESERVED_HEADERS = {"authorization", "user-agent", "x-bird-api-version", "idempotency-key"}
+
+# Bound to the concrete client so `with`/`async with` preserve the subclass type
+# (e.g. `with Bird(...) as c` keeps `c` typed as Bird, not SyncAPIClient).
+_SyncClientT = TypeVar("_SyncClientT", bound="SyncAPIClient")
+_AsyncClientT = TypeVar("_AsyncClientT", bound="AsyncAPIClient")
+
+
+def _validate_request_path(base_url: str, path: str) -> None:
+    """Reject a caller path that would move the API key off the configured origin.
+
+    The verb-method escape hatch joins ``path`` onto ``base_url`` and then attaches
+    the bearer token, so an unvalidated path can redirect the key to another host —
+    ``//host``, ``user@host``, an absolute URL, or a bare-relative segment. Require a
+    single leading slash and assert the resolved origin equals the base-URL origin.
+    """
+    if not path.startswith("/") or path.startswith("//"):
+        raise ValueError(f"request path must be an absolute path starting with a single '/': got {path!r}")
+    base = urlsplit(base_url)
+    full = urlsplit(base_url + path)
+    if (full.scheme, full.netloc) != (base.scheme, base.netloc):
+        raise ValueError(
+            f"request path {path!r} must stay on the configured Bird API origin {base.scheme}://{base.netloc}"
+        )
+
+
+class BaseClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        api_version: str | None = None,
+        timeout: httpx.Timeout | float | None | NotGiven = NOT_GIVEN,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Mapping[str, str] | None = None,
+        default_query: Mapping[str, Any] | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.api_version = api_version
+        self.max_retries = max_retries
+        self.timeout: httpx.Timeout | float | None = DEFAULT_TIMEOUT if isinstance(timeout, NotGiven) else timeout
+        self._default_headers = dict(default_headers or {})
+        self._default_query = dict(default_query or {})
+
+    def _headers(self, extra_headers: Mapping[str, str] | None, idempotency_key: str | None) -> dict[str, str]:
+        headers: dict[str, str] = {"Accept": "application/json"}
+        headers.update(self._default_headers)
+        for key, value in (extra_headers or {}).items():
+            if key.lower() not in _RESERVED_HEADERS:
+                headers[key] = value
+        headers["Authorization"] = f"Bearer {self.api_key}"
+        headers["User-Agent"] = USER_AGENT
+        if self.api_version:
+            headers["X-Bird-API-Version"] = self.api_version
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        return headers
+
+    def _build_request(
+        self,
+        client: httpx.Client | httpx.AsyncClient,
+        method: str,
+        path: str,
+        *,
+        body: Any,
+        extra_headers: Mapping[str, str] | None,
+        extra_query: Mapping[str, Any] | None,
+        extra_body: Mapping[str, Any] | None,
+        timeout: httpx.Timeout | float | None | NotGiven,
+        idempotency_key: str | None,
+    ) -> httpx.Request:
+        _validate_request_path(self.base_url, path)
+        if extra_body:
+            body = {**(body or {}), **extra_body}
+        query = {**self._default_query, **(extra_query or {})}
+        return client.build_request(
+            method,
+            self.base_url + path,
+            json=body,
+            params=query or None,
+            headers=self._headers(extra_headers, idempotency_key),
+            timeout=self.timeout if isinstance(timeout, NotGiven) else timeout,
+        )
+
+    @staticmethod
+    def _should_retry(response: httpx.Response) -> bool:
+        # 409 is a semantic conflict a retry cannot resolve; 501 is not implemented.
+        code = response.status_code
+        return code == 429 or (500 <= code < 600 and code != 501)
+
+    def _retry_delay(self, attempt: int, response: httpx.Response | None) -> float:
+        if response is not None:
+            advised = parse_retry_after(response.headers)
+            if advised is not None:
+                return min(advised, MAX_RETRY_DELAY)
+        delay = min(INITIAL_RETRY_DELAY * 2**attempt, MAX_RETRY_DELAY)
+        return delay * (1.0 + random.random() * 0.25)
+
+    @staticmethod
+    def _idempotency_key(method: str, given: str | None) -> str | None:
+        if given is not None:
+            return given
+        return str(uuid.uuid4()) if method.upper() in _MUTATING_METHODS else None
+
+
+class SyncAPIClient(BaseClient):
+    def __init__(self, *, http_client: httpx.Client | None = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        # Own (and close) the client only when we created it. A client shared in via
+        # with_options() or injected by the caller is theirs to close.
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        extra_headers: Mapping[str, str] | None = None,
+        extra_query: Mapping[str, Any] | None = None,
+        extra_body: Mapping[str, Any] | None = None,
+        timeout: httpx.Timeout | float | None | NotGiven = NOT_GIVEN,
+        idempotency_key: str | None = None,
+        max_retries: int | None = None,
+    ) -> httpx.Response:
+        request = self._build_request(
+            self._client, method, path,
+            body=body, extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body,
+            timeout=timeout, idempotency_key=self._idempotency_key(method, idempotency_key),
+        )
+        retries_left = self.max_retries if max_retries is None else max_retries
+        attempt = 0
+        while True:
+            last: httpx.Response | None = None
+            try:
+                response = self._client.send(request)
+            except httpx.TimeoutException as exc:
+                if retries_left <= 0:
+                    raise APITimeoutError() from exc
+            except httpx.HTTPError as exc:
+                if retries_left <= 0:
+                    raise APIConnectionError() from exc
+            else:
+                if response.is_success:
+                    return response
+                if retries_left <= 0 or not self._should_retry(response):
+                    raise from_response(response.status_code, response.content, response.headers)
+                response.close()
+                last = response
+            time.sleep(self._retry_delay(attempt, last))
+            retries_left -= 1
+            attempt += 1
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self: _SyncClientT) -> _SyncClientT:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class AsyncAPIClient(BaseClient):
+    def __init__(self, *, http_client: httpx.AsyncClient | None = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        # Own (and close) the client only when we created it. A client shared in via
+        # with_options() or injected by the caller is theirs to close.
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        extra_headers: Mapping[str, str] | None = None,
+        extra_query: Mapping[str, Any] | None = None,
+        extra_body: Mapping[str, Any] | None = None,
+        timeout: httpx.Timeout | float | None | NotGiven = NOT_GIVEN,
+        idempotency_key: str | None = None,
+        max_retries: int | None = None,
+    ) -> httpx.Response:
+        request = self._build_request(
+            self._client, method, path,
+            body=body, extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body,
+            timeout=timeout, idempotency_key=self._idempotency_key(method, idempotency_key),
+        )
+        retries_left = self.max_retries if max_retries is None else max_retries
+        attempt = 0
+        while True:
+            last: httpx.Response | None = None
+            try:
+                response = await self._client.send(request)
+            except httpx.TimeoutException as exc:
+                if retries_left <= 0:
+                    raise APITimeoutError() from exc
+            except httpx.HTTPError as exc:
+                if retries_left <= 0:
+                    raise APIConnectionError() from exc
+            else:
+                if response.is_success:
+                    return response
+                if retries_left <= 0 or not self._should_retry(response):
+                    raise from_response(response.status_code, response.content, response.headers)
+                await response.aclose()
+                last = response
+            await asyncio.sleep(self._retry_delay(attempt, last))
+            retries_left -= 1
+            attempt += 1
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self: _AsyncClientT) -> _AsyncClientT:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()

bird/_client.py

@@ -0,0 +1,278 @@
+"""The public clients: ``Bird`` (synchronous) and ``AsyncBird`` (asynchronous).
+
+Both resolve configuration the same way — the API key from the ``api_key``
+argument or ``BIRD_API_KEY``; the base URL from ``base_url``, ``BIRD_BASE_URL``,
+or the region (explicit ``region`` or inferred from the ``bk_{region}_…`` key
+prefix, ADR-0036). They add the escape-hatch verb methods over the request
+lifecycle in ``_base_client``; resource namespaces attach on top.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Any, Mapping
+
+import httpx
+import pydantic
+
+from bird._base_client import AsyncAPIClient, SyncAPIClient
+from bird._constants import DEFAULT_MAX_RETRIES
+from bird._exceptions import BirdError
+from bird._types import NOT_GIVEN, EmailDefaults, NotGiven
+from bird.resources.email import AsyncEmail, Email
+from bird.resources.webhooks import AsyncWebhooks, Webhooks
+
+_REGION_PREFIX = re.compile(r"^bk_([a-z]{2}[0-9]+)_")
+
+
+def _infer_region(api_key: str) -> str | None:
+    match = _REGION_PREFIX.match(api_key)
+    return match.group(1) if match else None
+
+
+def _resolve(api_key: str | None, base_url: str | None, region: str | None) -> tuple[str, str]:
+    api_key = api_key or os.environ.get("BIRD_API_KEY")
+    if not api_key:
+        raise BirdError("missing API key: pass api_key= or set BIRD_API_KEY")
+    base_url = base_url or os.environ.get("BIRD_BASE_URL")
+    if not base_url:
+        region = region or _infer_region(api_key)
+        if not region:
+            raise BirdError(
+                "could not determine region: pass region= or base_url=, "
+                "or use a bk_{region}_{token} API key"
+            )
+        base_url = f"https://{region}.platform.bird.com"
+    return api_key, base_url
+
+
+def _decode(response: httpx.Response, cast_to: type[pydantic.BaseModel] | None) -> Any:
+    if response.status_code == 204 or not response.content:
+        return None
+    data = response.json()
+    return cast_to.model_validate(data) if cast_to is not None else data
+
+
+def _with_overrides(
+    config: dict[str, Any], live_client: httpx.Client | httpx.AsyncClient, overrides: dict[str, Any]
+) -> dict[str, Any]:
+    """Build constructor kwargs for a client derived via ``with_options``: start from
+    the parent's resolved config, reuse the live HTTP client (so the derived client
+    shares the pool and doesn't own it), then apply the caller's non-default
+    overrides. Overriding ``api_key`` or ``region`` re-derives the base URL from the
+    new key's region prefix (ADR-0036) unless an explicit ``base_url`` — or the
+    ``BIRD_BASE_URL`` env var, the deployment-wide override _resolve honors above
+    region — is set, matching the constructor's precedence."""
+    merged: dict[str, Any] = {**config, "http_client": live_client}
+    given = {key: value for key, value in overrides.items() if not isinstance(value, NotGiven)}
+    # api_key drives the region (ADR-0036): a new key (or region) without an explicit
+    # base_url must re-resolve the endpoint, not inherit the parent's resolved one.
+    if ("api_key" in given or "region" in given) and "base_url" not in given:
+        merged.pop("base_url", None)
+    merged.update(given)
+    return merged
+
+
+class Bird(SyncAPIClient):
+    """The synchronous Bird client.
+
+    ```python
+    import os
+    from bird import Bird, APIStatusError, RateLimitError
+
+    client = Bird(api_key=os.environ["BIRD_API_KEY"])  # region inferred from the key prefix
+    try:
+        msg = client.email.send(from_="hello@acme.com", to=["c@x.com"], subject="Hi", html="<p>hi</p>")
+    except RateLimitError as err:
+        wait = err.retry_after
+    except APIStatusError as err:
+        print(err.status_code, err.code, err.request_id)
+    ```
+
+    Reach `client.email` and `client.webhooks`, or any other endpoint via the
+    verb methods (`client.get` / `post` / …). Use it as a context manager
+    (`with Bird(...) as client`) to close the underlying HTTP client.
+
+    ```python
+    # bird:snippet:start client.verbs
+    from bird import EmailMessage
+
+    message = client.get("/v1/email/messages/em_01krd...", cast_to=EmailMessage)
+    client.post("/v1/some/new/endpoint", body={"key": "value"})
+    # bird:snippet:end client.verbs
+    ```
+
+    A single `Bird` instance is safe to share across threads — the `httpx` client
+    pools connections and every call builds its own request state — so create one
+    client and reuse it rather than one per request.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        region: str | None = None,
+        base_url: str | None = None,
+        api_version: str | None = None,
+        webhook_secret: str | None = None,
+        email_defaults: EmailDefaults | None = None,
+        timeout: httpx.Timeout | float | None | NotGiven = NOT_GIVEN,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Mapping[str, str] | None = None,
+        default_query: Mapping[str, Any] | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        api_key, base_url = _resolve(api_key, base_url, region)
+        self._config: dict[str, Any] = {
+            "api_key": api_key,
+            "region": region,
+            "base_url": base_url,
+            "api_version": api_version,
+            "webhook_secret": webhook_secret,
+            "email_defaults": email_defaults,
+            "timeout": timeout,
+            "max_retries": max_retries,
+            "default_headers": default_headers,
+            "default_query": default_query,
+            "http_client": http_client,
+        }
+        # region is kept so with_options() can re-resolve correctly, but it isn't a base-client arg.
+        super().__init__(**{k: v for k, v in self._config.items() if k not in ("webhook_secret", "email_defaults", "region")})
+        self.webhook_secret = webhook_secret
+        self.email = Email(self, email_defaults)
+        self.webhooks = Webhooks(webhook_secret)
+
+    def with_options(
+        self,
+        *,
+        api_key: str | None | NotGiven = NOT_GIVEN,
+        region: str | None | NotGiven = NOT_GIVEN,
+        base_url: str | None | NotGiven = NOT_GIVEN,
+        api_version: str | None | NotGiven = NOT_GIVEN,
+        webhook_secret: str | None | NotGiven = NOT_GIVEN,
+        email_defaults: EmailDefaults | None | NotGiven = NOT_GIVEN,
+        timeout: httpx.Timeout | float | None | NotGiven = NOT_GIVEN,
+        max_retries: int | NotGiven = NOT_GIVEN,
+        default_headers: Mapping[str, str] | None | NotGiven = NOT_GIVEN,
+        default_query: Mapping[str, Any] | None | NotGiven = NOT_GIVEN,
+        http_client: httpx.Client | None | NotGiven = NOT_GIVEN,
+    ) -> "Bird":
+        """Return a new client with some options overridden, reusing this client's
+        HTTP connection pool (the derived client never closes it) unless you pass
+        your own ``http_client``. Overriding ``api_key`` or ``region`` re-resolves the
+        base URL from the new key's region prefix — unless an explicit ``base_url`` or
+        the ``BIRD_BASE_URL`` env var is set, which win as the deployment-wide endpoint
+        (the same precedence the constructor uses)."""
+        return Bird(**_with_overrides(self._config, self._client, {
+            "api_key": api_key, "region": region, "base_url": base_url, "api_version": api_version,
+            "webhook_secret": webhook_secret, "email_defaults": email_defaults, "timeout": timeout,
+            "max_retries": max_retries, "default_headers": default_headers, "default_query": default_query,
+            "http_client": http_client,
+        }))
+
+    def get(self, path: str, *, cast_to: type[pydantic.BaseModel] | None = None, **options: Any) -> Any:
+        return _decode(self.request("GET", path, **options), cast_to)
+
+    def post(self, path: str, *, body: Any = None, cast_to: type[pydantic.BaseModel] | None = None, **options: Any) -> Any:
+        return _decode(self.request("POST", path, body=body, **options), cast_to)
+
+    def put(self, path: str, *, body: Any = None, cast_to: type[pydantic.BaseModel] | None = None, **options: Any) -> Any:
+        return _decode(self.request("PUT", path, body=body, **options), cast_to)
+
+    def patch(self, path: str, *, body: Any = None, cast_to: type[pydantic.BaseModel] | None = None, **options: Any) -> Any:
+        return _decode(self.request("PATCH", path, body=body, **options), cast_to)
+
+    def delete(self, path: str, *, cast_to: type[pydantic.BaseModel] | None = None, **options: Any) -> Any:
+        return _decode(self.request("DELETE", path, **options), cast_to)
+
+
+class AsyncBird(AsyncAPIClient):
+    """The asynchronous Bird client — the async mirror of `Bird`.
+
+    ```python
+    async with AsyncBird(api_key="bk_eu1_...") as client:
+        msg = await client.email.send(from_="hello@acme.com", to=["c@x.com"], subject="Hi", text="hi")
+    ```
+
+    A single `AsyncBird` instance is safe to share across concurrent tasks (e.g.
+    `asyncio.gather`) — reuse one client rather than creating one per request.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        region: str | None = None,
+        base_url: str | None = None,
+        api_version: str | None = None,
+        webhook_secret: str | None = None,
+        email_defaults: EmailDefaults | None = None,
+        timeout: httpx.Timeout | float | None | NotGiven = NOT_GIVEN,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Mapping[str, str] | None = None,
+        default_query: Mapping[str, Any] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        api_key, base_url = _resolve(api_key, base_url, region)
+        self._config: dict[str, Any] = {
+            "api_key": api_key,
+            "region": region,
+            "base_url": base_url,
+            "api_version": api_version,
+            "webhook_secret": webhook_secret,
+            "email_defaults": email_defaults,
+            "timeout": timeout,
+            "max_retries": max_retries,
+            "default_headers": default_headers,
+            "default_query": default_query,
+            "http_client": http_client,
+        }
+        # region is kept so with_options() can re-resolve correctly, but it isn't a base-client arg.
+        super().__init__(**{k: v for k, v in self._config.items() if k not in ("webhook_secret", "email_defaults", "region")})
+        self.webhook_secret = webhook_secret
+        self.email = AsyncEmail(self, email_defaults)
+        self.webhooks = AsyncWebhooks(webhook_secret)
+
+    def with_options(
+        self,
+        *,
+        api_key: str | None | NotGiven = NOT_GIVEN,
+        region: str | None | NotGiven = NOT_GIVEN,
+        base_url: str | None | NotGiven = NOT_GIVEN,
+        api_version: str | None | NotGiven = NOT_GIVEN,
+        webhook_secret: str | None | NotGiven = NOT_GIVEN,
+        email_defaults: EmailDefaults | None | NotGiven = NOT_GIVEN,
+        timeout: httpx.Timeout | float | None | NotGiven = NOT_GIVEN,
+        max_retries: int | NotGiven = NOT_GIVEN,
+        default_headers: Mapping[str, str] | None | NotGiven = NOT_GIVEN,
+        default_query: Mapping[str, Any] | None | NotGiven = NOT_GIVEN,
+        http_client: httpx.AsyncClient | None | NotGiven = NOT_GIVEN,
+    ) -> "AsyncBird":
+        """Return a new client with some options overridden, reusing this client's
+        HTTP connection pool (the derived client never closes it) unless you pass
+        your own ``http_client``. Overriding ``api_key`` or ``region`` re-resolves the
+        base URL from the new key's region prefix — unless an explicit ``base_url`` or
+        the ``BIRD_BASE_URL`` env var is set, which win as the deployment-wide endpoint
+        (the same precedence the constructor uses)."""
+        return AsyncBird(**_with_overrides(self._config, self._client, {
+            "api_key": api_key, "region": region, "base_url": base_url, "api_version": api_version,
+            "webhook_secret": webhook_secret, "email_defaults": email_defaults, "timeout": timeout,
+            "max_retries": max_retries, "default_headers": default_headers, "default_query": default_query,
+            "http_client": http_client,
+        }))
+
+    async def get(self, path: str, *, cast_to: type[pydantic.BaseModel] | None = None, **options: Any) -> Any:
+        return _decode(await self.request("GET", path, **options), cast_to)
+
+    async def post(self, path: str, *, body: Any = None, cast_to: type[pydantic.BaseModel] | None = None, **options: Any) -> Any:
+        return _decode(await self.request("POST", path, body=body, **options), cast_to)
+
+    async def put(self, path: str, *, body: Any = None, cast_to: type[pydantic.BaseModel] | None = None, **options: Any) -> Any:
+        return _decode(await self.request("PUT", path, body=body, **options), cast_to)
+
+    async def patch(self, path: str, *, body: Any = None, cast_to: type[pydantic.BaseModel] | None = None, **options: Any) -> Any:
+        return _decode(await self.request("PATCH", path, body=body, **options), cast_to)
+
+    async def delete(self, path: str, *, cast_to: type[pydantic.BaseModel] | None = None, **options: Any) -> Any:
+        return _decode(await self.request("DELETE", path, **options), cast_to)

bird/_constants.py

@@ -0,0 +1,8 @@
+import httpx
+
+DEFAULT_MAX_RETRIES = 2
+DEFAULT_TIMEOUT = httpx.Timeout(timeout=60.0, connect=5.0)
+
+# Jittered exponential backoff bounds, in seconds.
+INITIAL_RETRY_DELAY = 0.5
+MAX_RETRY_DELAY = 8.0