reflectapi-runtime 0.20.0__tar.gz → 0.21.0__tar.gz

{reflectapi_runtime-0.20.0 → reflectapi_runtime-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: reflectapi-runtime
-Version: 0.20.0
+Version: 0.21.0
 Summary: Runtime library for ReflectAPI Python clients
 Project-URL: Homepage, https://github.com/thepartly/reflectapi
 Project-URL: Repository, https://github.com/thepartly/reflectapi
@@ -60,14 +60,22 @@ directly.
 - `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`.
+- `ReflectapiPartialModel` — base class for generated models with omittable
+  fields. Unset fields stay absent during direct serialization; explicit null
+  and values remain set, tracked via Pydantic's `model_fields_set`.
 - Authentication helpers (`BearerTokenAuth`, `APIKeyAuth`, `BasicAuth`,
   `OAuth2ClientCredentialsAuth`, `OAuth2AuthorizationCodeAuth`).
 - Middleware, batching, and testing utilities (`MockClient`,
   `CassetteMiddleware`).
 
+## Request field presence
+
+Requests serialize Pydantic models with wire aliases and `exclude_unset=True`,
+recursively. A field omitted during construction is absent from JSON; a field
+explicitly set to `None` is sent as `null`. This also applies to nested models
+and models inside list or dictionary bodies. Unset non-null defaults are
+omitted too: pass the default value explicitly if the server should receive it.
+
 ## Streaming endpoints
 
 Endpoints declared with `Builder::stream_route` on the server are exposed on
@@ -93,7 +101,7 @@ 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.
+Python 3.12+. SDKs generated with ReflectAPI 0.21 require the 0.21 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.

{reflectapi_runtime-0.20.0 → reflectapi_runtime-0.21.0}/README.md

@@ -19,14 +19,22 @@ directly.
 - `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`.
+- `ReflectapiPartialModel` — base class for generated models with omittable
+  fields. Unset fields stay absent during direct serialization; explicit null
+  and values remain set, tracked via Pydantic's `model_fields_set`.
 - Authentication helpers (`BearerTokenAuth`, `APIKeyAuth`, `BasicAuth`,
   `OAuth2ClientCredentialsAuth`, `OAuth2AuthorizationCodeAuth`).
 - Middleware, batching, and testing utilities (`MockClient`,
   `CassetteMiddleware`).
 
+## Request field presence
+
+Requests serialize Pydantic models with wire aliases and `exclude_unset=True`,
+recursively. A field omitted during construction is absent from JSON; a field
+explicitly set to `None` is sent as `null`. This also applies to nested models
+and models inside list or dictionary bodies. Unset non-null defaults are
+omitted too: pass the default value explicitly if the server should receive it.
+
 ## Streaming endpoints
 
 Endpoints declared with `Builder::stream_route` on the server are exposed on
@@ -52,7 +60,7 @@ 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.
+Python 3.12+. SDKs generated with ReflectAPI 0.21 require the 0.21 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.

{reflectapi_runtime-0.20.0 → reflectapi_runtime-0.21.0}/pyproject.toml

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

{reflectapi_runtime-0.20.0 → reflectapi_runtime-0.21.0}/src/reflectapi_runtime/__init__.py

@@ -55,7 +55,7 @@ from .testing import (
 )
 from .types import BatchResult, ReflectapiEmpty, ReflectapiInfallible
 
-__version__ = "0.20.0"
+__version__ = "0.21.0"
 
 __all__ = [
     # Authentication

{reflectapi_runtime-0.20.0 → reflectapi_runtime-0.21.0}/src/reflectapi_runtime/client.py

@@ -47,7 +47,7 @@ def _json_serializer(obj: Any) -> Any:
     elif isinstance(obj, datetime.date):
         return obj.isoformat()
     elif hasattr(obj, "model_dump"):
-        return obj.model_dump(exclude_none=True)
+        return obj.model_dump(mode="json", by_alias=True, exclude_unset=True)
     raise TypeError(f"Object of type {type(obj)} is not JSON serializable")
 
 
@@ -153,13 +153,29 @@ def _parse_response_headers(headers: Any, model: type[Any] | None) -> Any | None
         return None
     items = headers.items() if headers is not None else ()
     lowered = {str(name).lower(): str(value) for name, value in items}
+    # HTTP headers are independently optional, even when the same model has
+    # required nullable fields when used as a JSON body. Supply absent headers
+    # here rather than weakening the model's body-validation contract.
+    field_keys = {
+        name: (
+            field.validation_alias
+            if isinstance(field.validation_alias, str)
+            else field.alias or name
+        )
+        for name, field in model.model_fields.items()
+    }
+    defaults = dict.fromkeys(field_keys.values())
     try:
-        return model.model_validate(lowered)
+        return model.model_validate(defaults | 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))
+        # Pydantic can report locations using field names or validation aliases.
+        invalid.update(
+            field_keys[name] for name in tuple(invalid) if name in field_keys
+        )
         valid = {name: value for name, value in lowered.items() if name not in invalid}
-        return model.model_validate(valid)
+        return model.model_validate(defaults | valid)
 
 
 def _validate_body(
@@ -422,15 +438,11 @@ class ClientBase(ABC):
     ) -> tuple[bytes, dict[str, str]]:
         """Serialize the request body.
 
-        ``ReflectapiPartialModel`` subclasses carry their own
-        ``@model_serializer`` that omits keys not in
-        ``model_fields_set``, so explicit ``None`` values must reach
-        the wire (they encode the protocol's "explicit null" state).
-
-        Plain Pydantic models use ``exclude_none=True`` so an unset
-        optional field renders as an absent key, matching the wire
-        shape produced by serde with
-        ``#[serde(skip_serializing_if = "Option::is_none")]``.
+        Only fields supplied by the caller are sent, recursively through
+        nested models. This lets the server apply defaults for omitted
+        fields, while explicitly supplied defaults and ``None`` values
+        reach the wire. In particular, required nullable fields and
+        explicit nulls in partial models must serialize as JSON ``null``.
         """
         # Handle primitive types (for untagged unions)
         if not hasattr(json_model, "model_dump_json"):
@@ -439,14 +451,9 @@ class ClientBase(ABC):
             ).encode("utf-8")
             return content, {"Content-Type": "application/json"}
 
-        from .partial import ReflectapiPartialModel
-
-        if isinstance(json_model, ReflectapiPartialModel):
-            content = json_model.model_dump_json(by_alias=True).encode("utf-8")
-        else:
-            content = json_model.model_dump_json(
-                by_alias=True, exclude_none=True
-            ).encode("utf-8")
+        content = json_model.model_dump_json(
+            by_alias=True, exclude_unset=True
+        ).encode("utf-8")
         return content, {"Content-Type": "application/json"}
 
     def _build_headers(
@@ -947,15 +954,11 @@ class AsyncClientBase(ABC):
     ) -> tuple[bytes, dict[str, str]]:
         """Serialize the request body.
 
-        ``ReflectapiPartialModel`` subclasses carry their own
-        ``@model_serializer`` that omits keys not in
-        ``model_fields_set``, so explicit ``None`` values must reach
-        the wire (they encode the protocol's "explicit null" state).
-
-        Plain Pydantic models use ``exclude_none=True`` so an unset
-        optional field renders as an absent key, matching the wire
-        shape produced by serde with
-        ``#[serde(skip_serializing_if = "Option::is_none")]``.
+        Only fields supplied by the caller are sent, recursively through
+        nested models. This lets the server apply defaults for omitted
+        fields, while explicitly supplied defaults and ``None`` values
+        reach the wire. In particular, required nullable fields and
+        explicit nulls in partial models must serialize as JSON ``null``.
         """
         # Handle primitive types (for untagged unions)
         if not hasattr(json_model, "model_dump_json"):
@@ -964,14 +967,9 @@ class AsyncClientBase(ABC):
             ).encode("utf-8")
             return content, {"Content-Type": "application/json"}
 
-        from .partial import ReflectapiPartialModel
-
-        if isinstance(json_model, ReflectapiPartialModel):
-            content = json_model.model_dump_json(by_alias=True).encode("utf-8")
-        else:
-            content = json_model.model_dump_json(
-                by_alias=True, exclude_none=True
-            ).encode("utf-8")
+        content = json_model.model_dump_json(
+            by_alias=True, exclude_unset=True
+        ).encode("utf-8")
         return content, {"Content-Type": "application/json"}
 
     def _build_headers(

{reflectapi_runtime-0.20.0 → reflectapi_runtime-0.21.0}/src/reflectapi_runtime/partial.py

@@ -15,9 +15,9 @@ the ``reflectapi::Option<T>`` enum. The Python equivalent uses
 - emits a wire payload that omits keys not in ``model_fields_set``,
   preserving the absent-vs-null distinction round-trip.
 
-Codegen makes every generated class with at least one
-``reflectapi::Option<T>`` field inherit from this class instead of
-``pydantic.BaseModel``.
+Codegen also uses this base for models with other omittable fields, so their
+unset defaults stay absent during direct model serialization as well as client
+requests.
 """
 
 from __future__ import annotations
@@ -28,7 +28,7 @@ from pydantic import BaseModel, model_serializer
 
 
 class ReflectapiPartialModel(BaseModel):
-    """Base class for reflectapi models with partial (three-state) fields.
+    """Base class for reflectapi models with omittable fields.
 
     Wire-format guarantee: a field that was never explicitly set on the
     instance is omitted from the serialised output entirely. A field set
@@ -70,7 +70,9 @@ class ReflectapiPartialModel(BaseModel):
     # ``m.snapshot = None`` after construction and have it land on the
     # wire.
 
-    @model_serializer(mode="wrap")
+    # Pydantic 2.10 can resolve an inherited serializer's postponed return
+    # annotation in the subclass's module, which need not import ``Any``.
+    @model_serializer(mode="wrap", return_type=dict[str, Any])
     def _serialize_partial(
         self, handler: Any, info: Any | None = None
     ) -> dict[str, Any]:

{reflectapi_runtime-0.20.0 → reflectapi_runtime-0.21.0}/tests/test_codegen_regressions.py

@@ -83,11 +83,10 @@ class TestDurationRoundTrip:
 
 
 class TestRequestSerializationOmitsUnsetOptional:
-    """Plain ``BaseModel`` request types must omit unset optional fields
-    from the wire, matching what ``#[serde(skip_serializing_if =
-    "Option::is_none")]`` produces on the server side. Partial models,
-    by contrast, must keep explicit ``None`` to preserve the
-    absent-vs-null distinction.
+    """Request models omit unset fields so the server can apply defaults.
+
+    Both plain and partial models preserve explicitly supplied ``None``
+    as JSON null, independently of whether a field has a default.
     """
 
     def _client(self):

{reflectapi_runtime-0.20.0 → reflectapi_runtime-0.21.0}/tests/test_partial.py

@@ -12,6 +12,8 @@ Contract:
 from __future__ import annotations
 
 import json
+import sys
+from types import ModuleType
 
 import pytest
 from pydantic import BaseModel, ValidationError
@@ -229,3 +231,23 @@ class TestEdgeCases:
         """`model_dump()` (Python dict) must also drop unset keys."""
         item = Item(identity="x")
         assert item.model_dump() == {"identity": "x"}
+
+
+def test_partial_subclass_does_not_require_any_in_callers_module(monkeypatch):
+    """Inherited serializers resolve their return type in the runtime module."""
+    caller = ModuleType("_reflectapi_partial_caller_without_any")
+    caller.ReflectapiPartialModel = ReflectapiPartialModel
+    monkeypatch.setitem(sys.modules, caller.__name__, caller)
+    exec(
+        "class Request(ReflectapiPartialModel):\n"
+        "    required: str | None\n"
+        "    optional: str | None = None\n",
+        caller.__dict__,
+    )
+
+    assert "Any" not in caller.__dict__
+    request = caller.Request(required=None)
+    assert request.model_dump_json() == '{"required":null}'
+    assert caller.Request(required=None, optional=None).model_dump_json() == (
+        '{"required":null,"optional":null}'
+    )

{reflectapi_runtime-0.20.0 → reflectapi_runtime-0.21.0}/tests/test_pydantic_serialization.py

@@ -198,7 +198,7 @@ class TestClientBasePydanticSerialization:
         assert call_args[1]["params"] == {"source": "api", "version": "v1"}
 
         expected_json = (
-            '{"name":"Param User","age":40,"email":"param@example.com","active":true}'
+            '{"name":"Param User","age":40,"email":"param@example.com"}'
         )
         assert call_args[1]["content"] == expected_json.encode("utf-8")
         assert call_args[1]["headers"] == {"Content-Type": "application/json"}
@@ -336,7 +336,9 @@ class TestPydanticSerializationEdgeCases:
         assert parsed_data["user"]["name"] == "Complex User"
         assert parsed_data["user"]["age"] == 45
         assert parsed_data["address"]["street"] == "123 Main St"
-        assert parsed_data["address"]["country"] == "USA"  # Default value
+        # Unset defaults are left for the server to apply, including nested models.
+        assert "country" not in parsed_data["address"]
+        assert "active" not in parsed_data["user"]
         assert parsed_data["tags"] == ["premium", "verified"]
         assert parsed_data["metadata"]["source"] == "test"
 

reflectapi_runtime-0.21.0/tests/test_request_field_presence.py

@@ -0,0 +1,136 @@
+"""Request bytes preserve supplied fields and leave omitted defaults to the server."""
+
+from typing import Any
+
+import httpx
+import pytest
+from pydantic import BaseModel, Field
+
+from reflectapi_runtime import AsyncClientBase, ClientBase, ReflectapiPartialModel
+
+
+class NullableRequest(BaseModel):
+    required_nullable: str | None
+    optional_nullable: str | None = None
+    defaulted: int = 7
+
+
+class AliasedRequest(BaseModel):
+    required_nullable: str | None = Field(alias="requiredAlias")
+    optional_nullable: str | None = Field(default=None, alias="optionalAlias")
+
+
+class PartialRequest(ReflectapiPartialModel):
+    required_nullable: str | None
+    optional_nullable: str | None = None
+    ordinary: AliasedRequest | None = None
+
+
+class NestedRequest(BaseModel):
+    ordinary: AliasedRequest
+    items: list[AliasedRequest]
+    union: AliasedRequest | str
+    partial: PartialRequest
+
+
+def request_cases() -> list[Any]:
+    aliased = AliasedRequest(requiredAlias=None, optionalAlias=None)
+    return [
+        pytest.param(
+            NullableRequest(required_nullable=None),
+            b'{"required_nullable":null}',
+            id="required-null-and-unset-optionals",
+        ),
+        pytest.param(
+            NullableRequest(required_nullable=None, optional_nullable=None),
+            b'{"required_nullable":null,"optional_nullable":null}',
+            id="explicit-optional-null",
+        ),
+        pytest.param(
+            NullableRequest(required_nullable="value", defaulted=7),
+            b'{"required_nullable":"value","defaulted":7}',
+            id="explicit-default-is-sent",
+        ),
+        pytest.param(
+            AliasedRequest(requiredAlias=None),
+            b'{"requiredAlias":null}',
+            id="required-null-alias",
+        ),
+        pytest.param(
+            aliased,
+            b'{"requiredAlias":null,"optionalAlias":null}',
+            id="explicit-null-alias",
+        ),
+        pytest.param(
+            PartialRequest(required_nullable=None),
+            b'{"required_nullable":null}',
+            id="partial-unset-optionals",
+        ),
+        pytest.param(
+            PartialRequest(
+                required_nullable=None,
+                optional_nullable=None,
+                ordinary=AliasedRequest(requiredAlias=None),
+            ),
+            b'{"required_nullable":null,"optional_nullable":null,'
+            b'"ordinary":{"requiredAlias":null}}',
+            id="partial-with-ordinary-model",
+        ),
+        pytest.param(
+            NestedRequest(
+                ordinary=aliased,
+                items=[AliasedRequest(requiredAlias=None), aliased],
+                union=aliased,
+                partial=PartialRequest(required_nullable=None, optional_nullable=None),
+            ),
+            b'{"ordinary":{"requiredAlias":null,"optionalAlias":null},'
+            b'"items":[{"requiredAlias":null},'
+            b'{"requiredAlias":null,"optionalAlias":null}],'
+            b'"union":{"requiredAlias":null,"optionalAlias":null},'
+            b'"partial":{"required_nullable":null,"optional_nullable":null}}',
+            id="ordinary-nesting-list-union-and-partial",
+        ),
+        pytest.param(
+            [AliasedRequest(requiredAlias=None), aliased],
+            b'[{"requiredAlias":null},{"requiredAlias":null,"optionalAlias":null}]',
+            id="list-root-with-models",
+        ),
+        pytest.param(
+            {"ordinary": AliasedRequest(requiredAlias=None), "explicit": None},
+            b'{"ordinary":{"requiredAlias":null},"explicit":null}',
+            id="dictionary-root-with-model",
+        ),
+    ]
+
+
+@pytest.mark.parametrize("payload, expected", request_cases())
+@pytest.mark.parametrize("body_argument", ["json_model", "json_data"])
+def test_sync_request_field_presence(payload, expected, body_argument):
+    captured = []
+
+    def respond(request):
+        captured.append(request.content)
+        return httpx.Response(200, json={})
+
+    with httpx.Client(transport=httpx.MockTransport(respond)) as transport:
+        client = ClientBase("https://example.test", client=transport)
+        client._make_request("/presence", **{body_argument: payload})
+
+    assert captured == [expected]
+
+
+@pytest.mark.parametrize("payload, expected", request_cases())
+@pytest.mark.parametrize("body_argument", ["json_model", "json_data"])
+@pytest.mark.asyncio
+async def test_async_request_field_presence(payload, expected, body_argument):
+    captured = []
+
+    def respond(request):
+        captured.append(request.content)
+        return httpx.Response(200, json={})
+
+    async with httpx.AsyncClient(transport=httpx.MockTransport(respond)) as transport:
+        client = AsyncClientBase("https://example.test", client=transport)
+        await client._make_request("/presence", **{body_argument: payload})
+
+    assert captured == [expected]

reflectapi_runtime-0.21.0/tests/test_response_header_presence.py

@@ -0,0 +1,90 @@
+"""Header absence does not weaken the same model's required JSON body fields."""
+
+from datetime import datetime
+
+import httpx
+import pytest
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic import ValidationError as PydanticValidationError
+
+from reflectapi_runtime import ApplicationError, AsyncClientBase, ClientBase
+
+
+class RequiredNullableHeaders(BaseModel):
+    # Exercise errors reported by Python field name as well as aliased input.
+    model_config = ConfigDict(loc_by_alias=False)
+
+    expires_at: datetime | None = Field(validation_alias="x-expires-at")
+    request_id: str | None = Field(alias="x-request-id")
+    retry_after: str | None = Field(validation_alias="retry-after")
+
+
+def assert_headers(headers):
+    assert isinstance(headers, RequiredNullableHeaders)
+    assert headers.expires_at is None
+    assert headers.request_id == "req-1"
+    assert headers.retry_after is None
+
+
+@pytest.mark.parametrize("status", [200, 503])
+@pytest.mark.parametrize("malformed", [False, True])
+def test_sync_required_nullable_response_headers(status, malformed):
+    wire_headers = {"X-Request-ID": "req-1"}
+    if malformed:
+        wire_headers["X-Expires-At"] = "invalid-datetime"
+
+    def respond(request):
+        return httpx.Response(status, headers=wire_headers, json={})
+
+    # Body validation still requires nullable keys when headers share the model.
+    with pytest.raises(PydanticValidationError):
+        RequiredNullableHeaders.model_validate({"x-request-id": "req-1"})
+
+    with httpx.Client(transport=httpx.MockTransport(respond)) as transport:
+        client = ClientBase("https://example.test", client=transport)
+        if status == 503:
+            with pytest.raises(ApplicationError) as exc:
+                client._make_request(
+                    "/headers", response_headers_model=RequiredNullableHeaders
+                )
+            result = exc.value
+            assert result.status_code == 503
+        else:
+            result = client._make_request(
+                "/headers", response_headers_model=RequiredNullableHeaders
+            )
+        assert_headers(result.headers)
+        if malformed:
+            assert result.metadata.headers["x-expires-at"] == "invalid-datetime"
+
+
+@pytest.mark.parametrize("status", [200, 503])
+@pytest.mark.parametrize("malformed", [False, True])
+@pytest.mark.asyncio
+async def test_async_required_nullable_response_headers(status, malformed):
+    wire_headers = {"X-Request-ID": "req-1"}
+    if malformed:
+        wire_headers["X-Expires-At"] = "invalid-datetime"
+
+    def respond(request):
+        return httpx.Response(status, headers=wire_headers, json={})
+
+    with pytest.raises(PydanticValidationError):
+        RequiredNullableHeaders.model_validate({"x-request-id": "req-1"})
+
+    async with httpx.AsyncClient(transport=httpx.MockTransport(respond)) as transport:
+        client = AsyncClientBase("https://example.test", client=transport)
+        if status == 503:
+            with pytest.raises(ApplicationError) as exc:
+                await client._make_request(
+                    "/headers", response_headers_model=RequiredNullableHeaders
+                )
+            result = exc.value
+            assert result.status_code == 503
+        else:
+            result = await client._make_request(
+                "/headers", response_headers_model=RequiredNullableHeaders
+            )
+        assert_headers(result.headers)
+        if malformed:
+            assert result.metadata.headers["x-expires-at"] == "invalid-datetime"