feat: add Capawesome Cloud Python SDK#1
Merged
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
This PR introduces an initial, typed, synchronous Python SDK for the Capawesome Cloud API, centered around a CapawesomeCloud client that exposes app-scoped resources under client.apps.* and organization-scoped jobs under client.jobs.
Changes:
- Added core SDK client, HTTP transport (auth, retries, error mapping), resource clients, and Pydantic v2 response models.
- Implemented offset/limit pagination via a lazy
Paginator, plus helpers like job polling and binary downloads/multipart uploads. - Added project tooling (pyproject, CI workflow), documentation (README), examples, and a pytest/respx-based test suite.
Reviewed changes
Copilot reviewed 33 out of 35 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/test_resources.py | Adds resource-level tests for request bodies, null-vs-omit semantics, no-content endpoints, downloads, and multipart uploads. |
| tests/test_pagination.py | Adds pagination behavior tests for multi-page iteration and single-page fetching. |
| tests/test_errors_and_retries.py | Adds tests for error mapping and retry behavior on 429/5xx. |
| tests/test_client.py | Adds tests for env-var token resolution, missing token error, headers, and context manager close behavior. |
| tests/conftest.py | Provides a reusable CapawesomeCloud pytest fixture with retries disabled for determinism. |
| src/capawesome_cloud/resources/webhooks.py | Implements CRUD + pagination for app webhooks. |
| src/capawesome_cloud/resources/jobs.py | Implements job listing/get/logs and a polling wait() helper. |
| src/capawesome_cloud/resources/environments.py | Implements environments and nested variables/secrets resources. |
| src/capawesome_cloud/resources/devices.py | Implements device listing/get/update/delete with explicit null semantics. |
| src/capawesome_cloud/resources/destinations.py | Implements destinations CRUD + pagination and snake_case→API field mapping for writes. |
| src/capawesome_cloud/resources/deployments.py | Implements deployments CRUD + pagination and deployment targeting fields. |
| src/capawesome_cloud/resources/channels.py | Implements channels CRUD + pause/resume and datetime serialization for expires_at. |
| src/capawesome_cloud/resources/certificates.py | Implements certificate CRUD + pagination and multipart upload with flexible file sources. |
| src/capawesome_cloud/resources/builds.py | Implements builds CRUD + pagination and nested artifact operations (download, signed URL). |
| src/capawesome_cloud/resources/build_sources.py | Implements build source creation and binary download. |
| src/capawesome_cloud/resources/automations.py | Implements automations CRUD + pagination and snake_case→API field mapping for writes. |
| src/capawesome_cloud/resources/apps.py | Implements apps CRUD + pagination and wires app-scoped sub-resources. |
| src/capawesome_cloud/resources/_base.py | Adds shared request/list/paginate/download helpers and param/body builders. |
| src/capawesome_cloud/resources/init.py | Exports resource client classes. |
| src/capawesome_cloud/py.typed | Marks the package as typed for type checkers. |
| src/capawesome_cloud/pagination.py | Adds the lazy offset/limit paginator used by list methods. |
| src/capawesome_cloud/models.py | Adds Pydantic v2 models with camelCase aliasing and extra="allow". |
| src/capawesome_cloud/exceptions.py | Adds SDK exception hierarchy and response→exception mapping. |
| src/capawesome_cloud/client.py | Adds the main CapawesomeCloud client wiring HTTP + resources. |
| src/capawesome_cloud/_version.py | Introduces the initial SDK version constant. |
| src/capawesome_cloud/_types.py | Adds the NOT_GIVEN sentinel for omit-vs-null semantics. |
| src/capawesome_cloud/_http.py | Adds httpx transport wrapper with auth, retries/backoff, and error mapping. |
| src/capawesome_cloud/init.py | Exposes public client/models/exceptions in the package API. |
| README.md | Adds full SDK documentation, quickstart, resources list, and development guidance. |
| pyproject.toml | Adds packaging metadata, dependencies, lint/type/test tooling configuration. |
| LICENSE | Adds MIT license text. |
| examples/trigger_native_build.py | Adds an example for triggering a native build, waiting for completion, and downloading artifacts. |
| examples/manage_live_updates.py | Adds an example for managing channels and listing devices. |
| .gitignore | Adds standard Python/tooling/editor ignores. |
| .github/workflows/ci.yml | Adds CI for build, test (3.9–3.13), lint/format, and mypy checks. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Replace the per-status exception subclasses with a single `CapawesomeCloudError` (status, status_text, message, body), matching the Node SDK; keep `APIConnectionError`/`APITimeoutError` for transport failures. - Extract messages from validation (`error[]` / `error.issues`) and plain-text error bodies. - Retry network and `5xx` failures only for idempotent methods; retry `429` for any method. - Trim the API token and accept `CAPAWESOME_TOKEN` as a fallback env var.
- Add `examples/README.md`, `examples/list_apps.py` and `examples/error_handling.py`. - Fix `examples/trigger_native_build.py` to pass `git_ref` so the build request isn't rejected.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Initial implementation of the Python SDK for the Capawesome Cloud API.
Overview
A typed, synchronous client built on
httpxand Pydantic v2, mirroring the structure and naming of the official Node SDK (cloud-node).Features
CapawesomeCloudwith bearer-token auth (arg orCAPAWESOME_CLOUD_TOKENenv var), configurablebase_url/timeout, and automatic retries with exponential backoff on429/5xx.client.apps.*(channels, builds + artifacts, build sources, deployments, destinations, devices, environments + variables/secrets, certificates, webhooks, automations); organization-scopedclient.jobsat the top level. Each app-scoped method takesapp_idas its first argument.extra="allow") exposing only the most relevant, stable fields; app-scoped models areApp-prefixed (AppChannel,AppWebhook, ...).camelCaseAPI keys map tosnake_caseattributes.list_page()for single-page control.CapawesomeCloudErrorhierarchy mapping HTTP status codes to specific exceptions.jobs.wait()polling, multipart certificate upload, binary artifact downloads, and explicit null-vs-omit semantics on updates.Tooling
pyproject.toml(hatchling),ruff(lint + format),mypy(strict),pytest+respx.Docs
examples/.Tests
19 tests covering the client, error mapping, retries, pagination, and resource request/response handling. HTTP is mocked with
respx(no network calls).