reflectapi-runtime

Runtime support library for Python clients generated by reflectapi. Generated code imports from reflectapi_runtime; you don't normally call this library directly.

What it provides

• ClientBase / AsyncClientBase — base classes used by the generated Client / AsyncClient. They wrap httpx and handle request build-up, Pydantic-based response validation, and middleware.
• ApiResponse[T, E, H] — typed wrapper around the response value, transport metadata, the optional typed error, and the API's declared response headers (.headers).
• ApiStream[T, H] / AsyncApiStream[T, H] — iterators returned by streaming methods, exposing the response's metadata and declared headers once iteration starts.
• ApplicationError, NetworkError, TimeoutError, ValidationError — exceptions raised by the generated methods on non-2xx, transport, and validation failures respectively.
• ReflectapiPartialModel — base class for generated models with three-state fields (value / explicit-null / absent) so absent and explicit-null can round-trip, tracked via Pydantic's model_fields_set.
• Authentication helpers (BearerTokenAuth, APIKeyAuth, BasicAuth, OAuth2ClientCredentialsAuth, OAuth2AuthorizationCodeAuth).
• Middleware, batching, and testing utilities (MockClient, CassetteMiddleware).

Streaming endpoints

Endpoints declared with Builder::stream_route on the server are exposed on the generated client as ordinary methods that return an iterator:

async with AsyncClient("http://localhost:3000") as client:
    async for event in client.pets.cdc_events(headers=headers):
        ...  # process each event

The sync client returns a regular Iterator; both validate each event against the declared item model. The wire format is Server-Sent Events (data: <json>\n\n); init failures (4xx/5xx) raise ApplicationError and do not enter the iterator. Breaking out of the loop or calling stream.aclose() releases the underlying HTTP connection.

Events are validated against the generated model. Closed response enums reject unfamiliar variants; enums declared with #[reflectapi(open)] retain them as an unknown case with the tag and parsed JSON, and #[serde(other)] uses the declared fallback. A malformed known variant raises ValidationError mid-stream and terminates the iterator. Earlier items remain delivered.

Compatibility

Python 3.12+. SDKs generated with ReflectAPI 0.20 require the 0.20 runtime. Pydantic 2.10 or newer supports the generated generic models; Python 3.14 requires Pydantic 2.12 or newer. Installing the runtime resolves these requirements and the supported HTTP dependencies automatically.