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.

Validation is strict: an event whose payload doesn't match the item model (for example, an unknown discriminated-union variant added by a newer server) raises ValidationError mid-stream and the iterator terminates. Items received before the bad event are still delivered.

Compatibility

Python 3.12+. The package targets the same reflectapi minor version as the schema you generate from; mismatches will surface at import time.