Cadenya Python SDK

The official Python client for the Cadenya API. Generated by redwood. Built on httpx; typed with dataclass models, TypedDict request shapes, and a py.typed marker.

Install

pip install cadenya

Getting started

from cadenya import Cadenya

# Reads CADENYA_API_KEY (and CADENYA_WORKSPACE_ID) from the environment when
# arguments are omitted. Explicit blank values raise ValueError and never
# fall back to the environment.
with Cadenya() as client:
    result = client.accounts.retrieve()

Cadenya is a context manager; close() releases the internally owned httpx client (a caller-supplied http_client is never closed).

Requests are snake_case throughout

Nested request objects take snake_case keys and are translated to wire names at the HTTP boundary. Wire-format keys also pass through for raw payloads; your own data inside JSON/map fields is never rewritten.

client.api_keys.create(
    metadata={"name": "sample"},
    spec={},
)

Errors

Non-2xx responses raise APIError (google.rpc Status: status_code, code, message, details). Protocol surprises (unfollowed redirects, non-JSON success bodies) raise APIResponseError; connection failures raise APIConnectionError.

Retries

Automatic retries apply only to idempotent methods (GET/HEAD/PUT/DELETE) and default to 0; counts normalize to a bounded 0–10 integer. Streaming requests never auto-retry and their read timeout is unlimited (connect/ write/pool stay bounded).

Pagination

for item in client.api_keys.list():
    ...  # iterating a page auto-fetches every page

Streaming (SSE)

Streams are context managers — early exits close the response deterministically:

with client.objectives.stream_events(objective_id) as stream:
    for event in stream:
        ...

# Resume after a disconnect: the checkpoint persists per the SSE spec.
with client.objectives.stream_events(objective_id, last_event_id=stream.last_event_id) as resumed:
    for event in resumed:
        ...

Webhooks (no API key required)

import os

from cadenya import unwrap_webhook

event = unwrap_webhook(payload, headers, secret=os.environ["CADENYA_WEBHOOK_SECRET"])

Verification follows Standard Webhooks (24–64 byte decoded secrets, integer timestamps, bounded tolerance).

Reference

The full method reference ships with the package as cadenya/api.md (importlib.resources reads it; it is also in the repository).