Initial Python SDK implementation: client, models, resources, and tests

[ntner]

Summary

First-party Python SDK for the Convox API. Enables customers to interact with Convox racks programmatically from Python without shelling out to the CLI binary. Supports both direct rack connections and console-managed racks via RBAC routing.

Motivation

The Convox CLI is the primary interface for rack management, but CI/CD pipelines, automation scripts, and custom tooling benefit from a native SDK with type safety, structured error handling, and programmatic access without shelling out to a binary. Python is widely used in DevOps and infrastructure automation, making it a natural fit for a first-party SDK.

What's included

Client

• ConvoxClient with three initialization paths: explicit (host + api_key), environment variables (CONVOX_HOST + CONVOX_PASSWORD + optional CONVOX_RACK), or CLI config (~/.convox/auth)
• Console-managed rack support with proper RBAC routing headers (User-Agent, Rack, Version)
• Low-level escape hatch (client.api.get(), client.api.post(), etc.) for endpoints not yet covered by resource modules
• Context manager support for connection cleanup

Resource modules (11)

Module	Operations
apps	list, get, create, delete, update
builds	list, get, create, update, import
releases	list, get, promote, rollback
environment	get, set (with client-side merge), unset, auto-promote
services	list, update, restart
processes	list, get, stop, run
resources	list, get (app-scoped and system-scoped), create, update, delete, link, unlink, types
instances	list, terminate, keyroll
registries	list, add, remove
certificates	list, create, generate, delete, renew, apply
system	get, update, capacity, processes, releases, metrics, jwt, letsencrypt config

All passing. ruff and mypy clean with zero warnings/errors.

Notable design decisions

• Environment set/unset auto-promotes by default (matching CLI behavior). Pass promote=False to opt out. The server does full env replacement, not merge, so the SDK handles client-side merge (read current, merge changes, send full env).
• stream() does not raise exceptions on error status codes. This is intentional for streaming endpoints (logs, build output) where partial data may already have been sent. Documented in README and docstring. The caller must check response.status_code and close the response.
• Console connections use User-Agent: convox.go/<version> to route through console RBAC. Verified against console3 routing code as the intended integration pattern (same mechanism the Go CLI uses).
• Version string lives in src/convox/_version.py as single source of truth, imported by __init__.py and _http.py. pyproject.toml version must be kept in sync manually at release time.

Not included (future work)

• Async client (AsyncConvoxClient) -- httpx supports async but the transport layer would need rework
• WebSocket endpoints (logs, exec, shell) -- requires different protocol handling
• Pagination wrapper -- the API uses limit params, not cursor-based pagination, so no SDK-level abstraction needed currently

Related

• Update/router stdapi#8 (update/router) -- adds JSON content negotiation that this SDK depends on
• Fix/api error handling convox#965 (fix/api-error-handling) -- fixes API status codes that this SDK's exception mapping depends on. The SDK includes backward-compatible heuristics for racks without this fix.