reflectapi-runtime 0.18.0__tar.gz → 0.19.0__tar.gz

{reflectapi_runtime-0.18.0 → reflectapi_runtime-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: reflectapi-runtime
-Version: 0.18.0
+Version: 0.19.0
 Summary: Runtime library for ReflectAPI Python clients
 Project-URL: Homepage, https://github.com/thepartly/reflectapi
 Project-URL: Repository, https://github.com/thepartly/reflectapi
@@ -47,8 +47,12 @@ directly.
 - `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]` — typed wrapper around the response value, transport
-  metadata, and the optional typed error.
+- `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.

{reflectapi_runtime-0.18.0 → reflectapi_runtime-0.19.0}/README.md

@@ -10,8 +10,12 @@ directly.
 - `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]` — typed wrapper around the response value, transport
-  metadata, and the optional typed error.
+- `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.

{reflectapi_runtime-0.18.0 → reflectapi_runtime-0.19.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "reflectapi-runtime"
-version = "0.18.0"
+version = "0.19.0"
 description = "Runtime library for ReflectAPI Python clients"
 readme = "README.md"
 requires-python = ">=3.12"

{reflectapi_runtime-0.18.0 → reflectapi_runtime-0.19.0}/src/reflectapi_runtime/__init__.py

@@ -38,7 +38,7 @@ from .hypothesis_strategies import (
 )
 from .middleware import AsyncMiddleware
 from .partial import ReflectapiPartialModel
-from .response import ApiResponse, TransportMetadata
+from .response import ApiResponse, ApiStream, AsyncApiStream, TransportMetadata
 from .serde import parse_externally_tagged, serialize_externally_tagged
 from .streaming import AsyncStreamingClient, StreamingResponse
 from .testing import (
@@ -50,7 +50,7 @@ from .testing import (
 )
 from .types import BatchResult, ReflectapiEmpty, ReflectapiInfallible
 
-__version__ = "0.18.0"
+__version__ = "0.19.0"
 
 __all__ = [
     # Authentication
@@ -94,6 +94,8 @@ __all__ = [
     "parse_externally_tagged",
     "serialize_externally_tagged",
     "StreamingResponse",
+    "ApiStream",
+    "AsyncApiStream",
     "TestClientMixin",
     "TimeoutError",
     "TransportMetadata",

{reflectapi_runtime-0.18.0 → reflectapi_runtime-0.19.0}/src/reflectapi_runtime/client.py

@@ -5,9 +5,10 @@ from __future__ import annotations
 import contextlib
 import datetime
 import json
+import logging
 import time
 from abc import ABC
-from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
+from collections.abc import AsyncGenerator, Awaitable, Callable, Generator
 from typing import Any, TypeVar, overload
 
 import httpx
@@ -22,7 +23,7 @@ from .middleware import (
     SyncMiddleware,
     SyncMiddlewareChain,
 )
-from .response import ApiResponse, TransportMetadata
+from .response import ApiResponse, ApiStream, AsyncApiStream, TransportMetadata
 from .sse import aparse_sse, parse_sse
 from .transport import AsyncClient, Client, Request, Response
 
@@ -34,6 +35,8 @@ class _NoValidation:
 
 NO_VALIDATION = _NoValidation()
 
+logger = logging.getLogger(__name__)
+
 T = TypeVar("T", bound=BaseModel)
 
 
@@ -82,7 +85,11 @@ def _synthesize_raw_response(
     )
 
 
-def _parse_json_body(body: bytes | str | None) -> Any:
+def _parse_json_body(
+    body: bytes | str | None,
+    metadata: TransportMetadata | None = None,
+    response_headers: Any | None = None,
+) -> Any:
     """Parse a response body as JSON, raising ``ValidationError`` on failure."""
     try:
         return json.loads(body if body is not None else b"")
@@ -90,6 +97,8 @@ def _parse_json_body(body: bytes | str | None) -> Any:
         raise ValidationError(
             f"Failed to parse JSON response: {e}",
             cause=e,
+            metadata=metadata,
+            headers=response_headers,
         )
 
 
@@ -98,6 +107,7 @@ def _raise_for_error_status(
     body: bytes | str | None,
     metadata: TransportMetadata,
     error_model: type | None = None,
+    response_headers: Any | None = None,
 ) -> None:
     """Raise ``ApplicationError`` for HTTP error responses (4xx, 5xx).
 
@@ -126,13 +136,37 @@ def _raise_for_error_status(
         metadata=metadata,
         error_data=error_data,
         typed_error=typed_error,
+        headers=response_headers,
     )
 
 
+def _parse_response_headers(headers: Any, model: type[Any] | None) -> Any | None:
+    """Validate the API's declared response headers into ``model``.
+
+    Header names are case-insensitive, so they're lowercased to match the
+    model's (lowercase) aliases; undeclared headers are ignored. A value that
+    doesn't validate reads as absent rather than failing the call, which
+    would hide the response's real outcome (e.g. a 503 from a proxy); the raw
+    value stays in ``metadata.headers``.
+    """
+    if model is None:
+        return None
+    items = headers.items() if headers is not None else ()
+    lowered = {str(name).lower(): str(value) for name, value in items}
+    try:
+        return model.model_validate(lowered)
+    except PydanticValidationError as e:
+        invalid = {error["loc"][0] for error in e.errors() if error["loc"]}
+        logger.debug("ignoring malformed response headers: %s", sorted(invalid))
+        valid = {name: value for name, value in lowered.items() if name not in invalid}
+        return model.model_validate(valid)
+
+
 def _validate_body(
     body: bytes | str | None,
     response_model: type[T] | type[Any] | str | _NoValidation,
     metadata: TransportMetadata,
+    response_headers: Any | None = None,
 ) -> ApiResponse[T] | ApiResponse[dict[str, Any]]:
     """Validate a response body using Pydantic via TypeAdapter.
 
@@ -147,20 +181,28 @@ def _validate_body(
         or response_model is NO_VALIDATION
         or response_model is Any
     ):
-        return ApiResponse(_parse_json_body(body), metadata)
+        return ApiResponse(
+            _parse_json_body(body, metadata, response_headers),
+            metadata,
+            response_headers,
+        )
 
     try:
         ta = TypeAdapter(response_model)
         if isinstance(body, (bytes, bytearray, str)):
             validated_data = ta.validate_json(body)
         else:
-            validated_data = ta.validate_python(_parse_json_body(body))
-        return ApiResponse(validated_data, metadata)
+            validated_data = ta.validate_python(
+                _parse_json_body(body, metadata, response_headers)
+            )
+        return ApiResponse(validated_data, metadata, response_headers)
     except PydanticValidationError as e:
         raise ValidationError(
             f"Response validation failed: {e}",
             validation_errors=e.errors(),
             cause=e,
+            metadata=metadata,
+            headers=response_headers,
         )
 
 
@@ -288,6 +330,7 @@ class ClientBase(ABC):
         headers_model: BaseModel | None = None,
         response_model: type[T],
         error_model: type[Any] | None = None,
+        response_headers_model: type[Any] | None = None,
     ) -> ApiResponse[T]: ...
 
     @overload
@@ -302,6 +345,7 @@ class ClientBase(ABC):
         headers_model: BaseModel | None = None,
         response_model: None = None,
         error_model: type[Any] | None = None,
+        response_headers_model: type[Any] | None = None,
     ) -> ApiResponse[dict[str, Any]]: ...
 
     @overload
@@ -316,6 +360,7 @@ class ClientBase(ABC):
         headers_model: BaseModel | None = None,
         response_model: type[Any],
         error_model: type[Any] | None = None,
+        response_headers_model: type[Any] | None = None,
     ) -> ApiResponse[Any]: ...
 
     @overload
@@ -330,6 +375,7 @@ class ClientBase(ABC):
         headers_model: BaseModel | None = None,
         response_model: str,
         error_model: type[Any] | None = None,
+        response_headers_model: type[Any] | None = None,
     ) -> ApiResponse[dict[str, Any]]: ...
 
     @overload
@@ -344,6 +390,7 @@ class ClientBase(ABC):
         headers_model: BaseModel | None = None,
         response_model: type[T],
         error_model: type[Any] | None = None,
+        response_headers_model: type[Any] | None = None,
     ) -> ApiResponse[T]: ...
 
     @overload
@@ -358,6 +405,7 @@ class ClientBase(ABC):
         headers_model: BaseModel | None = None,
         response_model: None = None,
         error_model: type[Any] | None = None,
+        response_headers_model: type[Any] | None = None,
     ) -> ApiResponse[dict[str, Any]]: ...
 
     def _validate_request_params(
@@ -521,6 +569,7 @@ class ClientBase(ABC):
         headers_model: BaseModel | None = None,
         response_model: type[T] | type[Any] | str | _NoValidation | None = None,
         error_model: type | None = None,
+        response_headers_model: type | None = None,
     ) -> ApiResponse[T] | ApiResponse[dict[str, Any]]:
         """Make an HTTP request and return an ApiResponse."""
         # Validate request parameters
@@ -556,20 +605,31 @@ class ClientBase(ABC):
                 ),
             )
 
+            response_headers = _parse_response_headers(
+                client_response.headers, response_headers_model
+            )
+
             # Handle error responses
             _raise_for_error_status(
                 client_response.status,
                 client_response.body,
                 metadata,
                 error_model=error_model,
+                response_headers=response_headers,
             )
 
             # Validate and return response
             if response_model is not None:
-                return _validate_body(client_response.body, response_model, metadata)
+                return _validate_body(
+                    client_response.body, response_model, metadata, response_headers
+                )
             else:
                 # No response_model provided - parse JSON as-is
-                return ApiResponse(_parse_json_body(client_response.body), metadata)
+                return ApiResponse(
+                    _parse_json_body(client_response.body, metadata, response_headers),
+                    metadata,
+                    response_headers,
+                )
 
         except httpx.TimeoutException as e:
             raise TimeoutError.from_httpx_timeout(e)
@@ -587,7 +647,8 @@ class ClientBase(ABC):
         headers_model: BaseModel | None = None,
         item_model: type[T] | type[Any] | str | _NoValidation | None = None,
         error_model: type | None = None,
-    ) -> Iterator[T] | Iterator[Any]:
+        response_headers_model: type | None = None,
+    ) -> ApiStream[Any]:
         """Open an SSE stream and yield items validated against ``item_model``.
 
         Errors raised when the server returns a non-2xx response are
@@ -595,69 +656,79 @@ class ClientBase(ABC):
         problems raise ``NetworkError`` / ``TimeoutError``. Per-event
         validation failures raise ``ValidationError``.
 
-        The HTTP connection is released when the generator is exhausted,
+        The request is sent when iteration starts; the returned stream's
+        ``metadata`` and ``headers`` are set once the response arrives. The
+        HTTP connection is released when the stream is exhausted,
         ``close()``-d, or garbage-collected, so consumers can ``break`` out
         of the loop without leaking sockets. Middleware is intentionally
         bypassed because typical middleware buffers the response body.
         """
 
-        self._validate_request_params(json_data, json_model)
+        def open_items(stream: ApiStream[Any]) -> Generator[Any, None, None]:
+            self._validate_request_params(json_data, json_model)
 
-        url = f"{self.base_url}/{path.lstrip('/')}"
-        client_request = self._build_client_request(
-            path, json_data, json_model, headers_model
-        )
-        request = self._build_httpx_request(client_request, url, params)
-        request.headers["accept"] = "text/event-stream"
-
-        start_time = time.time()
-        try:
-            response = self._client.send(request, stream=True)
-        except httpx.TimeoutException as e:
-            raise TimeoutError.from_httpx_timeout(e)
-        except httpx.RequestError as e:
-            raise NetworkError.from_httpx_error(e)
-
-        try:
-            metadata = TransportMetadata.from_response(response, start_time)
-            if response.status_code >= 400:
-                # read_full body so error parsing can see it
-                response.read()
-                _raise_for_error_status(
-                    response.status_code,
-                    response.content,
-                    metadata,
-                    error_model=error_model,
-                )
-
-            adapter: TypeAdapter[Any] | None = None
-            if (
-                item_model is not None
-                and item_model is not NO_VALIDATION
-                and item_model != "Any"
-                and item_model is not Any
-            ):
-                adapter = TypeAdapter(item_model)
+            url = f"{self.base_url}/{path.lstrip('/')}"
+            client_request = self._build_client_request(
+                path, json_data, json_model, headers_model
+            )
+            request = self._build_httpx_request(client_request, url, params)
+            request.headers["accept"] = "text/event-stream"
 
+            start_time = time.time()
             try:
-                for event in parse_sse(response.iter_lines()):
-                    if adapter is None:
-                        yield json.loads(event.data)
-                    else:
-                        try:
-                            yield adapter.validate_json(event.data)
-                        except PydanticValidationError as e:
-                            raise ValidationError(
-                                f"SSE event validation failed: {e}",
-                                validation_errors=e.errors(),
-                                cause=e,
-                            )
+                response = self._client.send(request, stream=True)
             except httpx.TimeoutException as e:
                 raise TimeoutError.from_httpx_timeout(e)
             except httpx.RequestError as e:
                 raise NetworkError.from_httpx_error(e)
-        finally:
-            response.close()
+
+            try:
+                metadata = TransportMetadata.from_response(response, start_time)
+                response_headers = _parse_response_headers(
+                    response.headers, response_headers_model
+                )
+                stream._set_response(metadata, response_headers)
+                if response.status_code >= 400:
+                    # read_full body so error parsing can see it
+                    response.read()
+                    _raise_for_error_status(
+                        response.status_code,
+                        response.content,
+                        metadata,
+                        error_model=error_model,
+                        response_headers=response_headers,
+                    )
+
+                adapter: TypeAdapter[Any] | None = None
+                if (
+                    item_model is not None
+                    and item_model is not NO_VALIDATION
+                    and item_model != "Any"
+                    and item_model is not Any
+                ):
+                    adapter = TypeAdapter(item_model)
+
+                try:
+                    for event in parse_sse(response.iter_lines()):
+                        if adapter is None:
+                            yield json.loads(event.data)
+                        else:
+                            try:
+                                yield adapter.validate_json(event.data)
+                            except PydanticValidationError as e:
+                                raise ValidationError(
+                                    f"SSE event validation failed: {e}",
+                                    validation_errors=e.errors(),
+                                    cause=e,
+                                )
+                except httpx.TimeoutException as e:
+                    raise TimeoutError.from_httpx_timeout(e)
+                except httpx.RequestError as e:
+                    raise NetworkError.from_httpx_error(e)
+            finally:
+                response.close()
+
+        return ApiStream(open_items)
 
 
 class AsyncClientBase(ABC):
@@ -784,6 +855,7 @@ class AsyncClientBase(ABC):
         headers_model: BaseModel | None = None,
         response_model: type[T],
         error_model: type[Any] | None = None,
+        response_headers_model: type[Any] | None = None,
     ) -> ApiResponse[T]: ...
 
     @overload
@@ -798,6 +870,7 @@ class AsyncClientBase(ABC):
         headers_model: BaseModel | None = None,
         response_model: None = None,
         error_model: type[Any] | None = None,
+        response_headers_model: type[Any] | None = None,
     ) -> ApiResponse[dict[str, Any]]: ...
 
     @overload
@@ -812,6 +885,7 @@ class AsyncClientBase(ABC):
         headers_model: BaseModel | None = None,
         response_model: type[Any],
         error_model: type[Any] | None = None,
+        response_headers_model: type[Any] | None = None,
     ) -> ApiResponse[Any]: ...
 
     @overload
@@ -826,6 +900,7 @@ class AsyncClientBase(ABC):
         headers_model: BaseModel | None = None,
         response_model: str,
         error_model: type[Any] | None = None,
+        response_headers_model: type[Any] | None = None,
     ) -> ApiResponse[dict[str, Any]]: ...
 
     @overload
@@ -840,6 +915,7 @@ class AsyncClientBase(ABC):
         headers_model: BaseModel | None = None,
         response_model: type[T],
         error_model: type[Any] | None = None,
+        response_headers_model: type[Any] | None = None,
     ) -> ApiResponse[T]: ...
 
     @overload
@@ -854,6 +930,7 @@ class AsyncClientBase(ABC):
         headers_model: BaseModel | None = None,
         response_model: None = None,
         error_model: type[Any] | None = None,
+        response_headers_model: type[Any] | None = None,
     ) -> ApiResponse[dict[str, Any]]: ...
 
     def _validate_request_params(
@@ -1013,6 +1090,7 @@ class AsyncClientBase(ABC):
         headers_model: BaseModel | None = None,
         response_model: type[T] | type[Any] | str | _NoValidation | None = None,
         error_model: type | None = None,
+        response_headers_model: type | None = None,
     ) -> ApiResponse[T] | ApiResponse[dict[str, Any]]:
         """Make an HTTP request and return an ApiResponse."""
         # Validate request parameters
@@ -1048,26 +1126,37 @@ class AsyncClientBase(ABC):
                 ),
             )
 
+            response_headers = _parse_response_headers(
+                client_response.headers, response_headers_model
+            )
+
             # Handle error responses
             _raise_for_error_status(
                 client_response.status,
                 client_response.body,
                 metadata,
                 error_model=error_model,
+                response_headers=response_headers,
             )
 
             # Validate and return response
             if response_model is not None:
-                return _validate_body(client_response.body, response_model, metadata)
+                return _validate_body(
+                    client_response.body, response_model, metadata, response_headers
+                )
             else:
-                return ApiResponse(_parse_json_body(client_response.body), metadata)
+                return ApiResponse(
+                    _parse_json_body(client_response.body, metadata, response_headers),
+                    metadata,
+                    response_headers,
+                )
 
         except httpx.TimeoutException as e:
             raise TimeoutError.from_httpx_timeout(e)
         except httpx.RequestError as e:
             raise NetworkError.from_httpx_error(e)
 
-    async def _make_sse_request(
+    def _make_sse_request(
         self,
 
         path: str,
@@ -1078,7 +1167,8 @@ class AsyncClientBase(ABC):
         headers_model: BaseModel | None = None,
         item_model: type[T] | type[Any] | str | _NoValidation | None = None,
         error_model: type | None = None,
-    ) -> AsyncIterator[Any]:
+        response_headers_model: type | None = None,
+    ) -> AsyncApiStream[Any]:
         """Open an SSE stream and yield items validated against ``item_model``.
 
         Errors raised when the server returns a non-2xx response are
@@ -1086,65 +1176,78 @@ class AsyncClientBase(ABC):
         problems raise ``NetworkError`` / ``TimeoutError``. Per-event
         validation failures raise ``ValidationError``.
 
-        The HTTP connection is released when the async generator is
-        exhausted or ``aclose()``-d, so consumers can ``break`` out of the
-        loop without leaking sockets. Middleware is intentionally
-        bypassed because typical middleware buffers the response body.
+        The request is sent when iteration starts; the returned stream's
+        ``metadata`` and ``headers`` are set once the response arrives. The
+        HTTP connection is released when the stream is exhausted or
+        ``aclose()``-d, so consumers can ``break`` out of the loop without
+        leaking sockets. Middleware is intentionally bypassed because
+        typical middleware buffers the response body.
         """
 
-        self._validate_request_params(json_data, json_model)
-
-        url = f"{self.base_url}/{path.lstrip('/')}"
-        client_request = self._build_client_request(
-            path, json_data, json_model, headers_model
-        )
-        request = self._build_httpx_request(client_request, url, params)
-        request.headers["accept"] = "text/event-stream"
-
-        start_time = time.time()
-        try:
-            response = await self._client.send(request, stream=True)
-        except httpx.TimeoutException as e:
-            raise TimeoutError.from_httpx_timeout(e)
-        except httpx.RequestError as e:
-            raise NetworkError.from_httpx_error(e)
+        async def open_items(
+            stream: AsyncApiStream[Any],
+        ) -> AsyncGenerator[Any, None]:
+            self._validate_request_params(json_data, json_model)
 
-        try:
-            metadata = TransportMetadata.from_response(response, start_time)
-            if response.status_code >= 400:
-                await response.aread()
-                _raise_for_error_status(
-                    response.status_code,
-                    response.content,
-                    metadata,
-                    error_model=error_model,
-                )
-
-            adapter: TypeAdapter[Any] | None = None
-            if (
-                item_model is not None
-                and item_model is not NO_VALIDATION
-                and item_model != "Any"
-                and item_model is not Any
-            ):
-                adapter = TypeAdapter(item_model)
+            url = f"{self.base_url}/{path.lstrip('/')}"
+            client_request = self._build_client_request(
+                path, json_data, json_model, headers_model
+            )
+            request = self._build_httpx_request(client_request, url, params)
+            request.headers["accept"] = "text/event-stream"
 
+            start_time = time.time()
             try:
-                async for event in aparse_sse(response.aiter_lines()):
-                    if adapter is None:
-                        yield json.loads(event.data)
-                    else:
-                        try:
-                            yield adapter.validate_json(event.data)
-                        except PydanticValidationError as e:
-                            raise ValidationError(
-                                f"SSE event validation failed: {e}",
-                                validation_errors=e.errors(),
-                                cause=e,
-                            )
+                response = await self._client.send(request, stream=True)
             except httpx.TimeoutException as e:
                 raise TimeoutError.from_httpx_timeout(e)
             except httpx.RequestError as e:
                 raise NetworkError.from_httpx_error(e)
-        finally:
-            await response.aclose()
+
+            try:
+                metadata = TransportMetadata.from_response(response, start_time)
+                response_headers = _parse_response_headers(
+                    response.headers, response_headers_model
+                )
+                stream._set_response(metadata, response_headers)
+                if response.status_code >= 400:
+                    await response.aread()
+                    _raise_for_error_status(
+                        response.status_code,
+                        response.content,
+                        metadata,
+                        error_model=error_model,
+                        response_headers=response_headers,
+                    )
+
+                adapter: TypeAdapter[Any] | None = None
+                if (
+                    item_model is not None
+                    and item_model is not NO_VALIDATION
+                    and item_model != "Any"
+                    and item_model is not Any
+                ):
+                    adapter = TypeAdapter(item_model)
+
+                try:
+                    async for event in aparse_sse(response.aiter_lines()):
+                        if adapter is None:
+                            yield json.loads(event.data)
+                        else:
+                            try:
+                                yield adapter.validate_json(event.data)
+                            except PydanticValidationError as e:
+                                raise ValidationError(
+                                    f"SSE event validation failed: {e}",
+                                    validation_errors=e.errors(),
+                                    cause=e,
+                                )
+                except httpx.TimeoutException as e:
+                    raise TimeoutError.from_httpx_timeout(e)
+                except httpx.RequestError as e:
+                    raise NetworkError.from_httpx_error(e)
+            finally:
+                await response.aclose()
+
+        return AsyncApiStream(open_items)
+

{reflectapi_runtime-0.18.0 → reflectapi_runtime-0.19.0}/src/reflectapi_runtime/exceptions.py

@@ -22,10 +22,15 @@ class ApiError(Exception):
         *,
         metadata: TransportMetadata | None = None,
         cause: Exception | None = None,
+        headers: Any | None = None,
     ) -> None:
         super().__init__(message)
         self.metadata = metadata
         self.cause = cause
+        # The API's declared response headers, validated into the generated
+        # headers model; None if the API declares none or no response arrived.
+        # All headers, untyped, are in ``metadata.headers``.
+        self.headers = headers
 
     @property
     def status_code(self) -> int | None:
@@ -79,8 +84,9 @@ class ApplicationError(ApiError):
         metadata: TransportMetadata,
         error_data: Any | None = None,
         typed_error: Any | None = None,
+        headers: Any | None = None,
     ) -> None:
-        super().__init__(message, metadata=metadata)
+        super().__init__(message, metadata=metadata, headers=headers)
         self.error_data = error_data
         self.typed_error = typed_error
 
@@ -124,6 +130,8 @@ class ValidationError(ApiError):
         *,
         validation_errors: list[Any] | None = None,
         cause: Exception | None = None,
+        metadata: TransportMetadata | None = None,
+        headers: Any | None = None,
     ) -> None:
-        super().__init__(message, cause=cause)
+        super().__init__(message, metadata=metadata, cause=cause, headers=headers)
         self.validation_errors = validation_errors or []

{reflectapi_runtime-0.18.0 → reflectapi_runtime-0.19.0}/src/reflectapi_runtime/response.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import time
+from collections.abc import AsyncGenerator, AsyncIterator, Callable, Generator, Iterator
 from dataclasses import dataclass
 from typing import Any, Generic
 
@@ -11,6 +12,11 @@ from typing_extensions import TypeVar
 
 T = TypeVar("T", covariant=True)
 E = TypeVar("E", covariant=True, default=Any)
+H = TypeVar("H", covariant=True, default=Any)
+# Streams record the response after construction, so their parameters
+# appear in setter arguments and can't be covariant.
+Item = TypeVar("Item")
+StreamH = TypeVar("StreamH", default=Any)
 
 
 @dataclass(frozen=True)
@@ -38,21 +44,25 @@ class TransportMetadata:
         )
 
 
-class ApiResponse(Generic[T, E]):
+class ApiResponse(Generic[T, E, H]):
     """Wrapper for API responses with typed success and error values.
 
     Type parameters:
         T: The success response type.
         E: The error response type (defaults to Any when not specified).
+        H: The API's declared response headers model (defaults to Any).
 
     Provides ergonomic access to both the deserialized value and transport metadata.
     Supports `ApiResponse[OutputType]` (backward compatible) and
     `ApiResponse[OutputType, ErrorType]` (with typed errors).
     """
 
-    def __init__(self, value: T, metadata: TransportMetadata) -> None:
+    def __init__(
+        self, value: T, metadata: TransportMetadata, headers: H | None = None
+    ) -> None:
         self._value = value
         self._metadata = metadata
+        self._headers = headers
 
     @property
     def value(self) -> T:
@@ -64,6 +74,15 @@ class ApiResponse(Generic[T, E]):
         """Transport metadata including timing, headers, and status."""
         return self._metadata
 
+    @property
+    def headers(self) -> H | None:
+        """The API's declared response headers, validated into its headers model.
+
+        ``None`` if the API declares no response headers. All headers,
+        untyped, are in ``metadata.headers``.
+        """
+        return self._headers
+
     @property
     def data(self) -> T:
         """Alias for value for ergonomic access (useful when the payload is a dict)."""
@@ -79,7 +98,7 @@ class ApiResponse(Generic[T, E]):
             List of available attributes from both wrapper and value.
         """
         # Get ApiResponse's own attributes
-        wrapper_attrs = ["value", "metadata", "data"]
+        wrapper_attrs = ["value", "metadata", "headers", "data"]
 
         # Get attributes from the wrapped value
         value_attrs = []
@@ -134,3 +153,77 @@ class ApiResponse(Generic[T, E]):
         return (
             f"ApiResponse(value={self._value!r}, status={self._metadata.status_code})"
         )
+
+
+class ApiStream(Iterator[Item], Generic[Item, StreamH]):
+    """Items of a streaming endpoint, with the HTTP response they came from.
+
+    The request is sent when iteration starts, so ``metadata`` and
+    ``headers`` are ``None`` until the first item is requested. ``headers``
+    holds the API's declared response headers, validated into its headers
+    model; all headers, untyped, are in ``metadata.headers``.
+    """
+
+    def __init__(
+        self,
+        open_items: Callable[[ApiStream[Item, StreamH]], Generator[Item, None, None]],
+    ) -> None:
+        self._metadata: TransportMetadata | None = None
+        self._headers: StreamH | None = None
+        self._items = open_items(self)
+
+    @property
+    def metadata(self) -> TransportMetadata | None:
+        return self._metadata
+
+    @property
+    def headers(self) -> StreamH | None:
+        return self._headers
+
+    def _set_response(
+        self, metadata: TransportMetadata, headers: StreamH | None
+    ) -> None:
+        self._metadata = metadata
+        self._headers = headers
+
+    def __next__(self) -> Item:
+        return next(self._items)
+
+    def close(self) -> None:
+        """Release the connection without reading the rest of the stream."""
+        self._items.close()
+
+
+class AsyncApiStream(AsyncIterator[Item], Generic[Item, StreamH]):
+    """Async counterpart of :class:`ApiStream`."""
+
+    def __init__(
+        self,
+        open_items: Callable[
+            [AsyncApiStream[Item, StreamH]], AsyncGenerator[Item, None]
+        ],
+    ) -> None:
+        self._metadata: TransportMetadata | None = None
+        self._headers: StreamH | None = None
+        self._items = open_items(self)
+
+    @property
+    def metadata(self) -> TransportMetadata | None:
+        return self._metadata
+
+    @property
+    def headers(self) -> StreamH | None:
+        return self._headers
+
+    def _set_response(
+        self, metadata: TransportMetadata, headers: StreamH | None
+    ) -> None:
+        self._metadata = metadata
+        self._headers = headers
+
+    async def __anext__(self) -> Item:
+        return await self._items.__anext__()
+
+    async def aclose(self) -> None:
+        """Release the connection without reading the rest of the stream."""
+        await self._items.aclose()

{reflectapi_runtime-0.18.0 → reflectapi_runtime-0.19.0}/tests/test_client.py

@@ -1,10 +1,11 @@
 """Tests for the client base classes."""
 
+import datetime
 from unittest.mock import AsyncMock, Mock
 
 import httpx
 import pytest
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict, Field
 
 from reflectapi_runtime import (
     ApiResponse,
@@ -1173,3 +1174,137 @@ class TestParsingBypassesSyntheticHttpxResponse:
             len(body)
         )
         assert result.metadata.headers.get("content-length") == "9999"
+
+
+class SampleResponseHeaders(BaseModel):
+    """Shaped like a generated response headers model."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    retry_after: str | None = Field(default=None, validation_alias="retry-after")
+    request_id: str | None = Field(default=None, validation_alias="x-request-id")
+
+
+class FixedResponseClient:
+    def __init__(self, status: int, headers: dict[str, str], body: bytes) -> None:
+        self.response = Response(
+            status=status, headers=httpx.Headers(headers), body=body
+        )
+
+    def request(self, request: Request) -> Response:
+        return self.response
+
+
+class AsyncFixedResponseClient(FixedResponseClient):
+    async def request(self, request: Request) -> Response:  # type: ignore[override]
+        return self.response
+
+
+class TestResponseHeaders:
+    def test_declared_headers_on_success(self):
+        transport = FixedResponseClient(
+            200,
+            {"X-Request-ID": "req-1", "cf-ray": "abc"},
+            b'{"name":"test","age":25}',
+        )
+        client = ClientBase("http://example.com", client=transport)
+
+        result = client._make_request(
+            "/test",
+            response_model=SampleModel,
+            response_headers_model=SampleResponseHeaders,
+        )
+
+        assert result.headers == SampleResponseHeaders(request_id="req-1")
+        assert result.metadata.headers["cf-ray"] == "abc"
+
+    def test_declared_headers_on_application_error(self):
+        transport = FixedResponseClient(429, {"retry-after": "7"}, b"slow down")
+        client = ClientBase("http://example.com", client=transport)
+
+        with pytest.raises(ApplicationError) as exc_info:
+            client._make_request(
+                "/test",
+                response_model=SampleModel,
+                response_headers_model=SampleResponseHeaders,
+            )
+
+        assert exc_info.value.headers == SampleResponseHeaders(retry_after="7")
+
+    def test_declared_headers_on_invalid_success_body(self):
+        transport = FixedResponseClient(200, {"x-request-id": "req-2"}, b'{"name":1}')
+        client = ClientBase("http://example.com", client=transport)
+
+        with pytest.raises(ValidationError) as exc_info:
+            client._make_request(
+                "/test",
+                response_model=SampleModel,
+                response_headers_model=SampleResponseHeaders,
+            )
+
+        assert exc_info.value.status_code == 200
+        assert exc_info.value.headers == SampleResponseHeaders(request_id="req-2")
+
+    def test_malformed_typed_header_reads_as_absent(self):
+        class TypedHeaders(BaseModel):
+            model_config = ConfigDict(populate_by_name=True)
+
+            expires_at: datetime.datetime | None = Field(
+                default=None, validation_alias="x-expires-at"
+            )
+            request_id: str | None = Field(
+                default=None, validation_alias="x-request-id"
+            )
+
+        transport = FixedResponseClient(
+            503, {"x-expires-at": "garbage", "x-request-id": "req-3"}, b"unavailable"
+        )
+        client = ClientBase("http://example.com", client=transport)
+
+        with pytest.raises(ApplicationError) as exc_info:
+            client._make_request(
+                "/test",
+                response_model=SampleModel,
+                response_headers_model=TypedHeaders,
+            )
+
+        assert exc_info.value.status_code == 503
+        assert exc_info.value.headers == TypedHeaders(request_id="req-3")
+        assert exc_info.value.metadata.headers["x-expires-at"] == "garbage"
+
+    def test_no_declared_headers(self):
+        client = ClientBase("http://example.com", client=ShapeClient())
+
+        result = client._make_request("/test", response_model=SampleModel)
+
+        assert result.headers is None
+
+    @pytest.mark.asyncio
+    async def test_declared_headers_on_async_success(self):
+        transport = AsyncFixedResponseClient(
+            200, {"retry-after": "3"}, b'{"name":"test","age":25}'
+        )
+        client = AsyncClientBase("http://example.com", client=transport)
+
+        result = await client._make_request(
+            "/test",
+            response_model=SampleModel,
+            response_headers_model=SampleResponseHeaders,
+        )
+
+        assert result.headers == SampleResponseHeaders(retry_after="3")
+
+    @pytest.mark.asyncio
+    async def test_declared_headers_on_async_application_error(self):
+        transport = AsyncFixedResponseClient(503, {"retry-after": "30"}, b"unavailable")
+        client = AsyncClientBase("http://example.com", client=transport)
+
+        with pytest.raises(ApplicationError) as exc_info:
+            await client._make_request(
+                "/test",
+                response_model=SampleModel,
+                response_headers_model=SampleResponseHeaders,
+            )
+
+        assert exc_info.value.status_code == 503
+        assert exc_info.value.headers == SampleResponseHeaders(retry_after="30")

{reflectapi_runtime-0.18.0 → reflectapi_runtime-0.19.0}/tests/test_sse.py

@@ -10,7 +10,7 @@ from typing import Any
 
 import httpx
 import pytest
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict, Field
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
 
@@ -130,6 +130,12 @@ class _Pet(BaseModel):
     weight: float
 
 
+class _StreamHeaders(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    request_id: str | None = Field(default=None, validation_alias="x-request-id")
+
+
 class _SyncDemo(ClientBase):
     """Minimal concrete subclass — exposes _make_sse_request as a public method."""
 
@@ -138,6 +144,11 @@ class _SyncDemo(ClientBase):
             "pets", item_model=_Pet, error_model=None
         )
 
+    def stream_pets_with_headers(self) -> Any:
+        return self._make_sse_request(
+            "pets", item_model=_Pet, response_headers_model=_StreamHeaders
+        )
+
 
 class _AsyncDemo(AsyncClientBase):
     def stream_pets(self) -> Any:
@@ -145,6 +156,11 @@ class _AsyncDemo(AsyncClientBase):
             "pets", item_model=_Pet, error_model=None
         )
 
+    def stream_pets_with_headers(self) -> Any:
+        return self._make_sse_request(
+            "pets", item_model=_Pet, response_headers_model=_StreamHeaders
+        )
+
 
 def _sse_body(items: list[dict]) -> bytes:
     return ("".join(f"data: {json.dumps(it)}\n\n" for it in items)).encode()
@@ -349,3 +365,36 @@ def event_loop():  # pragma: no cover - pytest-asyncio compatibility shim
     loop = asyncio.new_event_loop()
     yield loop
     loop.close()
+
+
+def test_sync_stream_exposes_response_once_iteration_starts() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        body = _sse_body([{"name": "fido", "weight": 1.5}])
+        return httpx.Response(
+            200, content=body, headers={"X-Request-ID": "req-1"}
+        )
+
+    client = _make_sync_client(httpx.MockTransport(handler))
+    stream = client.stream_pets_with_headers()
+    assert stream.headers is None and stream.metadata is None
+    assert next(stream) == _Pet(name="fido", weight=1.5)
+    assert stream.metadata.status_code == 200
+    assert stream.headers == _StreamHeaders(request_id="req-1")
+    stream.close()
+    client.close()
+
+
+@pytest.mark.asyncio
+async def test_async_stream_init_error_carries_headers() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            429, text="slow down", headers={"x-request-id": "req-2"}
+        )
+
+    client = _make_async_client(httpx.MockTransport(handler))
+    stream = client.stream_pets_with_headers()
+    with pytest.raises(ApplicationError) as ei:
+        await stream.__anext__()
+    assert ei.value.headers == _StreamHeaders(request_id="req-2")
+    assert stream.headers == _StreamHeaders(request_id="req-2")
+    await client.aclose()