SDKs · Python
Python — Runtime support
Declarative runtime support matrix for matter-python. Verified runtimes run the full conformance corpus in CI; supported runtimes pass a smoke subset; experimental runtimes ship behind a feature flag.
Last updated
Runtime support matrix
Where matter-python runs, and what conformance guarantees come with each runtime.
TL;DR. CPython 3.11, 3.12, and 3.13 are verified — the full SDK conformance corpus runs against each on every commit. PyPy and AWS Lambda are supported. PyOdide (Python-in-the-browser) is experimental and requires a Web Crypto bridge.
Support tiers
Three tiers map directly onto the canonical contract published from @matter/sdk-conformance:
| Tier | What it means |
|---|---|
| verified | Full SDK conformance corpus runs in CI on every commit. Bugs treated as P0. |
| supported | A smoke subset of the corpus runs in CI. Bugs treated as P1. Users should pin a known-good version. |
| experimental | Best-effort. Signatures and behaviour may change between minor releases. No CI gate. |
The tier classification is data — sourced from RUNTIME_MATRICES.python in packages/sdk-conformance. When this table and the data drift, CI fails.
Matrix
| Runtime | Version | Tier | Notes |
|---|---|---|---|
| CPython | 3.11 | verified | Primary target. Full conformance corpus runs in CI. |
| CPython | 3.12 | verified | Active release. Full corpus runs in CI. |
| CPython | 3.13 | verified | Current release. Full corpus runs in CI. |
| PyPy | ≥ 3.11 | supported | Pure-Python paths only; httpx works out of the box. |
| AWS Lambda (Python runtime) | 3.11+ | supported | Cold-start budget verified; no native deps required. |
| PyOdide / browser | ≥ 0.25 | experimental | Async I/O via JS fetch; signing requires Web Crypto bridge. |
What the SDK guarantees per tier
verified — Every behaviour described in error handling, pagination, and webhooks works the same way it does in the type stubs. Streaming, retries, and idempotency replay are exercised against a fixture API on each commit.
supported — Authentication, request/response, error classes, and pagination work. Streaming may degrade on platforms without a native async runtime. Retries function but the exact backoff curve may be implementation-defined.
experimental — The package installs and authenticates. Beyond that, expect rough edges. Open an issue if something breaks; we will not block a release on it.
Async-first
matter-python is async-first. All client methods return awaitables; a sync façade is available for non-async contexts (e.g. Django request handlers prior to ASGI migration). The sync façade is a thin shim — both code paths share the same retry, idempotency, and pagination logic. Behaviour parity is asserted by the SDK conformance corpus on every commit.
CI matrix
The Python SDK's CI matrix runs the conformance corpus against the verified row set on every PR. The matrix is wired in .github/workflows/sdk-python.yml and pulls runtime versions directly from RUNTIME_MATRICES.python. Adding a runtime to the verified tier is a code change, not a doc change.
See also
- SDK conformance harness — the contracts every SDK satisfies
- Error handling — the cross-SDK error class hierarchy
- Webhooks — streaming + retry guarantees