reflectapi-runtime 0.17.2a2__tar.gz → 0.17.2a3__tar.gz

reflectapi_runtime-0.17.2a3/.gitignore

@@ -0,0 +1 @@
+uv.lock

{reflectapi_runtime-0.17.2a2 → reflectapi_runtime-0.17.2a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reflectapi-runtime
-Version: 0.17.2a2
+Version: 0.17.2a3
 Summary: Runtime library for ReflectAPI Python clients
 Project-URL: Homepage, https://github.com/thepartly/reflectapi
 Project-URL: Repository, https://github.com/thepartly/reflectapi

{reflectapi_runtime-0.17.2a2 → reflectapi_runtime-0.17.2a3}/pyproject.toml

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

{reflectapi_runtime-0.17.2a2 → reflectapi_runtime-0.17.2a3}/src/reflectapi_runtime/__init__.py

@@ -20,6 +20,7 @@ from .auth import (
 )
 from .batch import BatchClient
 from .client import AsyncClientBase, ClientBase
+from .transport import AsyncClient, Client, Request, Response
 from .exceptions import (
     ApiError,
     ApplicationError,
@@ -55,7 +56,7 @@ from .testing import (
 )
 from .types import BatchResult, ReflectapiEmpty, ReflectapiInfallible
 
-__version__ = "0.17.2a2"
+__version__ = "0.17.2a3"
 
 __all__ = [
     # Authentication
@@ -78,12 +79,16 @@ __all__ = [
     "ApplicationError",
     "AsyncCassetteMiddleware",
     "AsyncClientBase",
+    "AsyncClient",
     "AsyncStreamingClient",
     "BatchClient",
     "BatchResult",
     "CassetteClient",
     "CassetteMiddleware",
+    "Client",
     "ClientBase",
+    "Request",
+    "Response",
     "HAS_HYPOTHESIS",
     "AsyncMiddleware",
     "MockClient",

{reflectapi_runtime-0.17.2a2 → reflectapi_runtime-0.17.2a3}/src/reflectapi_runtime/client.py

@@ -6,7 +6,7 @@ import datetime
 import json
 import time
 from abc import ABC
-from collections.abc import AsyncIterator, Iterator
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
 from typing import Any, TypeVar, overload
 
 import httpx
@@ -24,6 +24,7 @@ from .middleware import (
 from .option import serialize_option_dict
 from .response import ApiResponse, TransportMetadata
 from .sse import aparse_sse, parse_sse
+from .transport import AsyncClient, Client, Request, Response
 
 
 # Sentinel object to represent "no validation needed"
@@ -61,7 +62,7 @@ class ClientBase(ABC):
         headers: dict[str, str] | None = None,
         middleware: list[SyncMiddleware] | None = None,
         auth: AuthHandler | httpx.Auth | None = None,
-        client: httpx.Client | None = None,
+        client: Client | httpx.Client | None = None,
     ) -> None:
         self.base_url = base_url.rstrip("/")
         self.middleware_chain = SyncMiddlewareChain(middleware or [])
@@ -165,7 +166,7 @@ class ClientBase(ABC):
     @overload
     def _make_request(
         self,
-        method: str,
+
         path: str,
         *,
         params: dict[str, Any] | None = None,
@@ -178,7 +179,7 @@ class ClientBase(ABC):
     @overload
     def _make_request(
         self,
-        method: str,
+
         path: str,
         *,
         params: dict[str, Any] | None = None,
@@ -191,7 +192,7 @@ class ClientBase(ABC):
     @overload
     def _make_request(
         self,
-        method: str,
+
         path: str,
         *,
         params: dict[str, Any] | None = None,
@@ -204,7 +205,7 @@ class ClientBase(ABC):
     @overload
     def _make_request(
         self,
-        method: str,
+
         path: str,
         *,
         params: dict[str, Any] | None = None,
@@ -216,7 +217,7 @@ class ClientBase(ABC):
     @overload
     def _make_request(
         self,
-        method: str,
+
         path: str,
         *,
         params: dict[str, Any] | None = None,
@@ -229,7 +230,7 @@ class ClientBase(ABC):
     @overload
     def _make_request(
         self,
-        method: str,
+
         path: str,
         *,
         params: dict[str, Any] | None = None,
@@ -241,7 +242,7 @@ class ClientBase(ABC):
 
     def _validate_request_params(
         self,
-        json_data: dict[str, Any] | None,
+        json_data: Any | None,
         json_model: BaseModel | None,
     ) -> None:
         """Validate request parameters for conflicts."""
@@ -321,58 +322,103 @@ class ClientBase(ABC):
 
         return headers
 
-    def _build_request(
+    def _build_client_request(
         self,
-        method: str,
-        url: str,
-        params: dict[str, Any] | None,
-        json_data: dict[str, Any] | None,
+        path: str,
+        json_data: Any | None,
         json_model: BaseModel | None,
         headers_model: BaseModel | None,
-    ) -> httpx.Request:
-        """Build HTTP request object."""
+    ) -> Request:
+        """Build ReflectAPI transport request object."""
         if json_model is not None:
-            # Serialize Pydantic model
             content, base_headers = self._serialize_request_body(json_model)
             headers = self._build_headers(base_headers, headers_model)
-
-            return self._client.build_request(
-                method=method,
-                url=url,
-                params=params,
-                content=content,
-                headers=headers,
-            )
-        else:
-            # Handle JSON data with Option types
-            if json_data is not None:
-                # Only serialize Option types for dictionaries (complex types)
-                # Primitive types (int, str, bool, etc.) should be passed directly
-                if isinstance(json_data, dict):
-                    processed_json_data = serialize_option_dict(json_data)
-                else:
-                    # Primitive types - pass through directly
-                    processed_json_data = json_data
+        elif json_data is not None:
+            if isinstance(json_data, dict):
+                processed_json_data = serialize_option_dict(json_data)
             else:
                 processed_json_data = json_data
-
-            # Build headers for requests without json_model
+            content = json.dumps(
+                processed_json_data,
+                default=_json_serializer,
+                separators=(",", ":"),
+            ).encode("utf-8")
+            headers = self._build_headers(
+                {"Content-Type": "application/json"}, headers_model
+            )
+        else:
+            content = b""
             headers = self._build_headers({}, headers_model)
 
-            return self._client.build_request(
-                method=method,
-                url=url,
-                params=params,
-                json=processed_json_data,
-                headers=headers if headers else None,
-            )
+        return Request(path=path, headers=headers, body=content)
 
-    def _execute_request(self, request: httpx.Request) -> httpx.Response:
-        """Execute HTTP request through middleware chain."""
-        if self.middleware_chain.middleware:
-            return self.middleware_chain.execute(request, self._client)
-        else:
-            return self._client.send(request)
+    def _build_httpx_request(
+        self,
+        request: Request,
+        url: str,
+        params: dict[str, Any] | None,
+    ) -> httpx.Request:
+        """Materialise an httpx.Request from a transport Request.
+
+        Method is always POST by design.
+        """
+        request_kwargs: dict[str, Any] = {
+            "method": "POST",
+            "url": url,
+            "params": params,
+            "headers": request.headers if request.headers else None,
+        }
+        if request.body:
+            request_kwargs["content"] = request.body
+        return self._client.build_request(**request_kwargs)
+
+    def _make_terminal(
+        self,
+        params: dict[str, Any] | None,
+    ) -> Callable[[Request], Response]:
+        """Return the chain-terminal handler for the active transport.
+
+        For an ``httpx.Client``, the terminal lifts the Request into an
+        ``httpx.Request``, sends it, and surfaces the real
+        ``httpx.Response`` via ``Response.raw`` so callers can read its
+        ``request`` / ``extensions`` / ``history`` from
+        :class:`TransportMetadata`.
+
+        For a custom :class:`Client`, the terminal accepts either a
+        :class:`Response` (the Protocol contract) or an ``httpx.Response``;
+        the latter is adapted at the boundary for transports that wrap
+        httpx directly. *Transitional:* the httpx-shaped path is a
+        backward-compat shim for adapters written against the previous
+        runtime; new code should return a :class:`Response`.
+        """
+        if isinstance(self._client, httpx.Client):
+            base_url = self.base_url
+
+            def terminal(req: Request) -> Response:
+                url = f"{base_url}/{req.path.lstrip('/')}"
+                httpx_req = self._build_httpx_request(req, url, params)
+                httpx_resp = self._client.send(httpx_req)
+                return Response(
+                    status=httpx_resp.status_code,
+                    headers=httpx_resp.headers,
+                    body=httpx_resp.content,
+                    raw=httpx_resp,
+                )
+
+            return terminal
+
+        def terminal(req: Request) -> Response:
+            response = self._client.request(req)
+            if isinstance(response, httpx.Response):
+                return Response(
+                    status=response.status_code,
+                    headers=response.headers,
+                    body=response.content,
+                    raw=response,
+                )
+            return response
+
+        return terminal
 
     def _handle_error_response(
         self,
@@ -455,7 +501,7 @@ class ClientBase(ABC):
 
     def _make_request(
         self,
-        method: str,
+
         path: str,
         *,
         params: dict[str, Any] | None = None,
@@ -469,28 +515,49 @@ class ClientBase(ABC):
         # Validate request parameters
         self._validate_request_params(json_data, json_model)
 
-        # Build URL and request
-        url = f"{self.base_url}/{path.lstrip('/')}"
-        request = self._build_request(
-            method, url, params, json_data, json_model, headers_model
+        # Build the transport request once and drive it through the
+        # middleware chain. The chain's terminal handler is transport-
+        # specific; middleware itself is transport-agnostic.
+        request = self._build_client_request(
+            path, json_data, json_model, headers_model
         )
+        terminal = self._make_terminal(params)
 
         # Execute request with timing
         start_time = time.time()
 
         try:
-            response = self._execute_request(request)
-            metadata = TransportMetadata.from_response(response, start_time)
+            client_response = self.middleware_chain.execute(request, terminal)
+            # Body / status / headers are read from the structural
+            # response so any middleware transforms apply; `raw` is used
+            # only as the metadata sidecar (preserves `.request` /
+            # `.extensions` / `.history` from the real wire response when
+            # available, fallback to the synthetic for custom transports).
+            parsed_response = httpx.Response(
+                status_code=client_response.status,
+                headers=client_response.headers,
+                content=client_response.body,
+            )
+            metadata = TransportMetadata(
+                status_code=client_response.status,
+                headers=client_response.headers,
+                timing=time.time() - start_time,
+                raw_response=client_response.raw or parsed_response,
+            )
 
             # Handle error responses
-            self._handle_error_response(response, metadata, error_model=error_model)
+            self._handle_error_response(
+                parsed_response, metadata, error_model=error_model
+            )
 
             # Validate and return response
             if response_model is not None:
-                return self._validate_response_model(response, response_model, metadata)
+                return self._validate_response_model(
+                    parsed_response, response_model, metadata
+                )
             else:
                 # No response_model provided - parse JSON into dict
-                json_response = self._parse_json_response(response)
+                json_response = self._parse_json_response(parsed_response)
                 return ApiResponse(json_response, metadata)
 
         except httpx.TimeoutException as e:
@@ -500,7 +567,7 @@ class ClientBase(ABC):
 
     def _make_sse_request(
         self,
-        method: str,
+
         path: str,
         *,
         params: dict[str, Any] | None = None,
@@ -526,9 +593,10 @@ class ClientBase(ABC):
         self._validate_request_params(json_data, json_model)
 
         url = f"{self.base_url}/{path.lstrip('/')}"
-        request = self._build_request(
-            method, url, params, json_data, json_model, headers_model
+        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()
@@ -587,7 +655,7 @@ class AsyncClientBase(ABC):
         headers: dict[str, str] | None = None,
         middleware: list[AsyncMiddleware] | None = None,
         auth: AuthHandler | httpx.Auth | None = None,
-        client: httpx.AsyncClient | None = None,
+        client: AsyncClient | httpx.AsyncClient | None = None,
     ) -> None:
         self.base_url = base_url.rstrip("/")
         self.middleware_chain = AsyncMiddlewareChain(middleware or [])
@@ -691,7 +759,7 @@ class AsyncClientBase(ABC):
     @overload
     async def _make_request(
         self,
-        method: str,
+
         path: str,
         *,
         params: dict[str, Any] | None = None,
@@ -703,7 +771,7 @@ class AsyncClientBase(ABC):
     @overload
     async def _make_request(
         self,
-        method: str,
+
         path: str,
         *,
         params: dict[str, Any] | None = None,
@@ -716,7 +784,7 @@ class AsyncClientBase(ABC):
     @overload
     async def _make_request(
         self,
-        method: str,
+
         path: str,
         *,
         params: dict[str, Any] | None = None,
@@ -729,7 +797,7 @@ class AsyncClientBase(ABC):
     @overload
     async def _make_request(
         self,
-        method: str,
+
         path: str,
         *,
         params: dict[str, Any] | None = None,
@@ -741,7 +809,7 @@ class AsyncClientBase(ABC):
     @overload
     async def _make_request(
         self,
-        method: str,
+
         path: str,
         *,
         params: dict[str, Any] | None = None,
@@ -754,7 +822,7 @@ class AsyncClientBase(ABC):
     @overload
     async def _make_request(
         self,
-        method: str,
+
         path: str,
         *,
         params: dict[str, Any] | None = None,
@@ -766,7 +834,7 @@ class AsyncClientBase(ABC):
 
     def _validate_request_params(
         self,
-        json_data: dict[str, Any] | None,
+        json_data: Any | None,
         json_model: BaseModel | None,
     ) -> None:
         """Validate request parameters for conflicts."""
@@ -847,58 +915,99 @@ class AsyncClientBase(ABC):
 
         return headers
 
-    def _build_request(
+    def _build_client_request(
         self,
-        method: str,
-        url: str,
-        params: dict[str, Any] | None,
-        json_data: dict[str, Any] | None,
+        path: str,
+        json_data: Any | None,
         json_model: BaseModel | None,
         headers_model: BaseModel | None,
-    ) -> httpx.Request:
-        """Build HTTP request object."""
+    ) -> Request:
+        """Build ReflectAPI transport request object."""
         if json_model is not None:
-            # Serialize Pydantic model
             content, base_headers = self._serialize_request_body(json_model)
             headers = self._build_headers(base_headers, headers_model)
-
-            return self._client.build_request(
-                method=method,
-                url=url,
-                params=params,
-                content=content,
-                headers=headers,
-            )
-        else:
-            # Handle JSON data with Option types
-            if json_data is not None:
-                # Only serialize Option types for dictionaries (complex types)
-                # Primitive types (int, str, bool, etc.) should be passed directly
-                if isinstance(json_data, dict):
-                    processed_json_data = serialize_option_dict(json_data)
-                else:
-                    # Primitive types - pass through directly
-                    processed_json_data = json_data
+        elif json_data is not None:
+            if isinstance(json_data, dict):
+                processed_json_data = serialize_option_dict(json_data)
             else:
                 processed_json_data = json_data
-
-            # Build headers for requests without json_model
+            content = json.dumps(
+                processed_json_data,
+                default=_json_serializer,
+                separators=(",", ":"),
+            ).encode("utf-8")
+            headers = self._build_headers(
+                {"Content-Type": "application/json"}, headers_model
+            )
+        else:
+            content = b""
             headers = self._build_headers({}, headers_model)
 
-            return self._client.build_request(
-                method=method,
-                url=url,
-                params=params,
-                json=processed_json_data,
-                headers=headers if headers else None,
-            )
+        return Request(path=path, headers=headers, body=content)
 
-    async def _execute_request(self, request: httpx.Request) -> httpx.Response:
-        """Execute HTTP request through middleware chain."""
-        if self.middleware_chain.middleware:
-            return await self.middleware_chain.execute(request, self._client)
-        else:
-            return await self._client.send(request)
+    def _build_httpx_request(
+        self,
+        request: Request,
+        url: str,
+        params: dict[str, Any] | None,
+    ) -> httpx.Request:
+        """Materialise an httpx.Request from a transport Request.
+
+        Method is always POST by design.
+        """
+        request_kwargs: dict[str, Any] = {
+            "method": "POST",
+            "url": url,
+            "params": params,
+            "headers": request.headers if request.headers else None,
+        }
+        if request.body:
+            request_kwargs["content"] = request.body
+        return self._client.build_request(**request_kwargs)
+
+    def _make_terminal(
+        self,
+        params: dict[str, Any] | None,
+    ) -> Callable[[Request], Awaitable[Response]]:
+        """Return the chain-terminal handler for the active transport.
+
+        For an ``httpx.AsyncClient``, the terminal lifts the Request into
+        an ``httpx.Request``, sends it, and surfaces the real
+        ``httpx.Response`` via ``Response.raw``.
+
+        For a custom :class:`AsyncClient`, the terminal accepts either a
+        :class:`Response` or an ``httpx.Response``; the latter is a
+        *transitional* backward-compat shim for adapters written against
+        the previous runtime.
+        """
+        if isinstance(self._client, httpx.AsyncClient):
+            base_url = self.base_url
+
+            async def terminal(req: Request) -> Response:
+                url = f"{base_url}/{req.path.lstrip('/')}"
+                httpx_req = self._build_httpx_request(req, url, params)
+                httpx_resp = await self._client.send(httpx_req)
+                return Response(
+                    status=httpx_resp.status_code,
+                    headers=httpx_resp.headers,
+                    body=httpx_resp.content,
+                    raw=httpx_resp,
+                )
+
+            return terminal
+
+        async def terminal(req: Request) -> Response:
+            response = await self._client.request(req)
+            if isinstance(response, httpx.Response):
+                return Response(
+                    status=response.status_code,
+                    headers=response.headers,
+                    body=response.content,
+                    raw=response,
+                )
+            return response
+
+        return terminal
 
     def _handle_error_response(
         self,
@@ -969,7 +1078,7 @@ class AsyncClientBase(ABC):
 
     async def _make_request(
         self,
-        method: str,
+
         path: str,
         *,
         params: dict[str, Any] | None = None,
@@ -983,27 +1092,48 @@ class AsyncClientBase(ABC):
         # Validate request parameters
         self._validate_request_params(json_data, json_model)
 
-        # Build URL and request
-        url = f"{self.base_url}/{path.lstrip('/')}"
-        request = self._build_request(
-            method, url, params, json_data, json_model, headers_model
+        # Build the transport request once and drive it through the
+        # middleware chain. The chain's terminal handler is transport-
+        # specific; middleware itself is transport-agnostic.
+        request = self._build_client_request(
+            path, json_data, json_model, headers_model
         )
+        terminal = self._make_terminal(params)
 
         # Execute request with timing
         start_time = time.time()
 
         try:
-            response = await self._execute_request(request)
-            metadata = TransportMetadata.from_response(response, start_time)
+            client_response = await self.middleware_chain.execute(request, terminal)
+            # Body / status / headers are read from the structural
+            # response so any middleware transforms apply; `raw` is used
+            # only as the metadata sidecar (preserves `.request` /
+            # `.extensions` / `.history` from the real wire response when
+            # available, fallback to the synthetic for custom transports).
+            parsed_response = httpx.Response(
+                status_code=client_response.status,
+                headers=client_response.headers,
+                content=client_response.body,
+            )
+            metadata = TransportMetadata(
+                status_code=client_response.status,
+                headers=client_response.headers,
+                timing=time.time() - start_time,
+                raw_response=client_response.raw or parsed_response,
+            )
 
             # Handle error responses
-            self._handle_error_response(response, metadata, error_model=error_model)
+            self._handle_error_response(
+                parsed_response, metadata, error_model=error_model
+            )
 
             # Validate and return response
             if response_model is not None:
-                return self._validate_response_model(response, response_model, metadata)
+                return self._validate_response_model(
+                    parsed_response, response_model, metadata
+                )
             else:
-                json_response = self._parse_json_response(response)
+                json_response = self._parse_json_response(parsed_response)
                 return ApiResponse(json_response, metadata)
 
         except httpx.TimeoutException as e:
@@ -1013,7 +1143,7 @@ class AsyncClientBase(ABC):
 
     async def _make_sse_request(
         self,
-        method: str,
+
         path: str,
         *,
         params: dict[str, Any] | None = None,
@@ -1039,9 +1169,10 @@ class AsyncClientBase(ABC):
         self._validate_request_params(json_data, json_model)
 
         url = f"{self.base_url}/{path.lstrip('/')}"
-        request = self._build_request(
-            method, url, params, json_data, json_model, headers_model
+        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()