slothbox (Python SDK)

Official Python SDK for the Slothbox API — typed, sync and async, with retries, cursor pagination, lifecycle waiters, and a webhook verification toolkit. Feature parity with @slothbox/sdk is tracked in PARITY_CHECKLIST.md.

pip install slothbox

Requires Python 3.10+ and an org service-account API key (sk_…, API plan) from the Slothbox dashboard — the SDK identifies itself on every request and the API rejects SDK traffic on other credentials (see SDK identification).

Quickstart

from slothbox import Slothbox

client = Slothbox()  # reads SLOTHBOX_API_KEY; or Slothbox(api_key="sk_…")

orgs = client.organizations.list()
envs = client.environments.list(org_id)

# Safe launch: always sends an Idempotency-Key, then polls until `running`.
box = client.environments.launch_and_wait(org_id, {"templateId": template_id})
print(box.env_id, box.status)

Async is the same surface with await:

from slothbox import AsyncSlothbox

async with AsyncSlothbox() as client:
    box = await client.environments.launch_and_wait(org_id, {"templateId": template_id})

Request bodies accept either the typed models (slothbox.models) or plain dicts keyed by the wire (JSON) names, as above.

SDK identification

Every request carries an always-on identification header:

x-slothbox-sdk: slothbox-sdk-python/<version>

The API uses it to identify SDK traffic, which must authenticate with an org service-account key (API plan). SDK-identified requests on any other credential are rejected 403 with code sdk_requires_service_key, raised as PermissionDeniedError. Identification wins: the header is set as a client-level default (so it also covers direct calls through the client.generated escape hatch) and re-asserted on every request the wrapper sends, so it cannot be removed or overridden — not via RequestOptions(headers=…), not via httpx_args, and not via the generated with_headers().

Errors

Every non-2xx response raises a typed exception with the API's machine-readable code, the gateway request id, and validation issues:

from slothbox import ConflictError, RateLimitError

try:
    client.environments.launch(org_id, {"templateId": template_id})
except ConflictError as err:
    if err.code == "template_not_baked":
        client.templates.wait_until_baked(org_id, template_id)
except RateLimitError as err:
    print("retry after", err.retry_after, "s — request", err.request_id)

Retries

GET/HEAD/PUT/DELETE are retried on 429/5xx/network errors (3 retries by default) with capped full-jitter backoff; Retry-After is honored. POST and PATCH are never blind-retried — a duplicated launch provisions a second EC2 box — unless the request carries an Idempotency-Key (environments.launch(..., idempotency_key=…); launch_and_wait always sends one). Tune with Slothbox(max_retries=…) or per request via RequestOptions(max_retries=…).

Pagination

The audit and webhook-delivery lists are cursor-paginated; iterating a page walks every page:

for event in client.audit.list_org_events(org_id, limit=100):
    ...

page = client.webhooks.list_deliveries(org_id, endpoint_id)
while page.has_next_page():
    page = page.get_next_page()

(async for on the async client.)

Webhooks

Verify deliveries with the exact raw bytes you received:

from slothbox import parse_webhook_event, WebhookVerificationError

try:
    event = parse_webhook_event(raw_body, request_headers, endpoint_secret)
except WebhookVerificationError as err:
    return 400, err.code

if event["type"] == "environment.stopped":
    ...

The verifier implements Standard Webhooks v1 (HMAC-SHA256, secret rotation, ±300s replay window) and is tested against the same vector file as the API's signer and the TS SDK.

Architecture

Per ADR 0001: a pinned openapi-python-client generates the typed core (slothbox._generated — committed, httpx + attrs, regenerated deterministically by scripts/generate.sh and diff-checked in CI), and the hand-written slothbox package on top is the public compatibility surface. client.generated exposes the generated AuthenticatedClient as an escape hatch — note that the generated set_httpx_client() bypasses auth; pass transports via Slothbox(httpx_args=…) instead.

Development

python -m venv .venv && .venv/bin/pip install -e '.[dev]'
ruff check . && ruff format --check .   # lint
mypy                                     # strict on the wrapper
pytest                                   # 3.10+ supported
scripts/generate.sh                      # regen the core from openapi.json

Releases are automated — see RELEASING.md.