Python SDK
Relevant source files
The following files were used as context for generating this wiki page:
The Python SDK is a generated package containing typed models and HTTPX-based clients for interacting with services defined in the Crucible project. It provides both synchronous and asynchronous client implementations to accommodate different Python concurrency models.
The SDK generator maps Crucible IR (Intermediate Representation) shapes to native Python constructs such as dataclasses, type aliases, and enums. It also includes a specialized runtime for handling serialization, retries, and service-specific error types.
Sources: crates/crucible-codegen-python/src/lib.rs:1-5, crates/crucible-codegen-python/src/lib.rs:55-60
Architecture and Components
The Python SDK architecture consists of several generated modules that work together to provide a type-safe interface to the service.
Component Overview
| Component | Description |
|---|---|
models.py | Contains generated Python dataclasses for structures and unions, type aliases for simple shapes, and open enums. |
client.py | Defines the Client (sync) and AsyncClient (async) classes with methods for every service operation. |
runtime.py | Provides the base logic for serialization, model representation, and the base ServiceError exception. |
auth.py | Handles authentication logic, such as bearer token injection. |
telemetry.py | Defines hooks for monitoring operation lifecycle events. |
Sources: crates/crucible-codegen-python/src/lib.rs:165-200, crates/crucible-codegen-python/src/lib.rs:373-400
Logic Flow of Operation Calls
The following diagram illustrates the internal flow when a user calls an operation through the Python SDK client.
The client handles the conversion between Python dataclasses and the wire format (JSON) using a shared schema defined in models.py.
Sources: crates/crucible-codegen-python/src/lib.rs:405-430, crates/crucible-codegen-python/src/snippet.rs:245-270
Data Model Mapping
Crucible shapes are mapped to Python-native types to ensure type safety and IDE support.
Shape Mapping Table
| Crucible Shape | Python Representation | Notes |
|---|---|---|
String | str | Standard string. |
Long / Integer | int | Maps to Python's arbitrary-precision integers. |
BigDecimal | Decimal | Imported from the decimal module. |
Timestamp | datetime | Uses aware datetimes in UTC. |
Blob | bytes | Binary data. |
Structure | @dataclass | Uses kw_only=True and custom __repr__. |
Enum | OpenEnum | Allows preserving unknown values from the server. |
Sources: crates/crucible-codegen-python/src/lib.rs:215-260, crates/crucible-codegen-python/src/snippet.rs:135-150
Handling Optional Members
The SDK uses a sentinel value UNSET to distinguish between a member that is explicitly None (JSON null) and a member that is absent from the payload.
from .runtime import UNSET, Unset
@dataclass(kw_only=True, repr=False)
class MyStructure:
optional_field: str | None | Unset = field(default=UNSET)
Sources: crates/crucible-codegen-python/src/lib.rs:290-305, crates/crucible-codegen-python/src/snippet.rs:105-115
Client Implementation
The SDK generates two primary client classes:
- Sync Client: Named
<ServiceName>Client, based onSyncClient. - Async Client: Named
Async<ServiceName>Client, based onAsyncClientBase.
Operation Methods
Each operation in the service model is generated as a method on the client. If an operation is marked as @paginated, an additional _pages method is generated which returns an Iterator (sync) or AsyncIterator (async) of response pages.
Sources: crates/crucible-codegen-python/src/lib.rs:410-435, crates/crucible-codegen-python/src/snippet.rs:340-355
Error Handling
Modelled errors are generated as Python exception classes. These classes subclass ServiceError and contain fields corresponding to the error's data members in the Crucible model.
Configuration and Installation
The SDK is packaged as a standard Python project with a pyproject.toml file. It requires Python 3.11 or later and depends on the httpx library.
Client Construction
Clients are typically constructed by providing an endpoint. If no endpoint is provided in code, the SDK can be configured to read from environment variables.
import os
from weather_client import WeatherClient
client = WeatherClient(
endpoint=os.environ["WEATHER_ENDPOINT"],
token=os.environ["WEATHER_TOKEN"]
)
Sources: crates/crucible-codegen-python/src/snippet.rs:200-220, crates/crucible-codegen-python/src/lib.rs:440-450
Generation Capabilities
The Python SDK generator supports a specific set of Crucible features:
GreedyLabelsIntEnumBigIntegerBigDecimalSparseNonBlobPayloadErrorPayload
Sources: crates/crucible-codegen-python/src/lib.rs:45-55
Summary
The Python SDK provides a high-level, type-safe interface for Crucible services. By utilizing Python's dataclasses and httpx, it offers a modern developer experience with support for both synchronous and asynchronous programming. Its use of specialized sentinel values like UNSET ensures accurate representation of service payloads, while the automatic generation of paginators and error types reduces boilerplate for consumers.
Sources: crates/crucible-codegen-python/src/lib.rs:1-10, crates/crucible-codegen-common/src/guide.rs:310-330