reflectapi-runtime 0.17.2a4__tar.gz → 0.17.3__tar.gz

{reflectapi_runtime-0.17.2a4 → reflectapi_runtime-0.17.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reflectapi-runtime
-Version: 0.17.2a4
+Version: 0.17.3
 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.2a4 → reflectapi_runtime-0.17.3}/pyproject.toml

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

{reflectapi_runtime-0.17.2a4 → reflectapi_runtime-0.17.3}/src/reflectapi_runtime/__init__.py

@@ -20,6 +20,7 @@ from .auth import (
 )
 from .batch import BatchClient
 from .client import AsyncClientBase, ClientBase
+from .duration import ReflectapiDuration
 from .transport import AsyncClient, Client, Request, Response
 from .exceptions import (
     ApiError,
@@ -36,16 +37,9 @@ from .hypothesis_strategies import (
     strategy_for_type,
 )
 from .middleware import AsyncMiddleware
-from .option import (
-    Option,
-    ReflectapiOption,
-    Undefined,
-    none,
-    serialize_option_dict,
-    some,
-    undefined,
-)
+from .partial import ReflectapiPartialModel
 from .response import ApiResponse, TransportMetadata
+from .serde import parse_externally_tagged, serialize_externally_tagged
 from .streaming import AsyncStreamingClient, StreamingResponse
 from .testing import (
     AsyncCassetteMiddleware,
@@ -56,7 +50,7 @@ from .testing import (
 )
 from .types import BatchResult, ReflectapiEmpty, ReflectapiInfallible
 
-__version__ = "0.17.2a4"
+__version__ = "0.17.3"
 
 __all__ = [
     # Authentication
@@ -93,22 +87,19 @@ __all__ = [
     "AsyncMiddleware",
     "MockClient",
     "NetworkError",
-    "Option",
+    "ReflectapiDuration",
     "ReflectapiEmpty",
     "ReflectapiInfallible",
-    "ReflectapiOption",
+    "ReflectapiPartialModel",
+    "parse_externally_tagged",
+    "serialize_externally_tagged",
     "StreamingResponse",
     "TestClientMixin",
     "TimeoutError",
     "TransportMetadata",
-    "Undefined",
     "ValidationError",
     "api_model_strategy",
     "enhanced_strategy_for_type",
-    "none",
-    "serialize_option_dict",
-    "some",
     "strategy_for_pydantic_model",
     "strategy_for_type",
-    "undefined",
 ]

{reflectapi_runtime-0.17.2a4 → reflectapi_runtime-0.17.3}/src/reflectapi_runtime/client.py

@@ -21,7 +21,6 @@ from .middleware import (
     SyncMiddleware,
     SyncMiddlewareChain,
 )
-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
@@ -252,60 +251,34 @@ class ClientBase(ABC):
     def _serialize_request_body(
         self, json_model: BaseModel | int | float | str | bool | list | dict
     ) -> tuple[bytes, dict[str, str]]:
-        """Serialize request body from Pydantic model or primitive type."""
-        from .option import ReflectapiOption
+        """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")]``.
+        """
         # Handle primitive types (for untagged unions)
-        if not hasattr(json_model, "model_dump"):
+        if not hasattr(json_model, "model_dump_json"):
             content = json.dumps(
                 json_model, default=_json_serializer, separators=(",", ":")
             ).encode("utf-8")
-            headers = {"Content-Type": "application/json"}
-            return content, headers
-
-        # Check if model has any ReflectapiOption fields that need special handling
-        raw_data = json_model.model_dump(exclude_none=False)
-
-        # Handle case where RootModel serializes to primitive value (e.g., strings for unit variants)
-        if not isinstance(raw_data, dict):
-            # For primitive values, use Pydantic's built-in JSON serialization
-            content = json_model.model_dump_json(
-                exclude_none=True, by_alias=True
-            ).encode("utf-8")
-            headers = {"Content-Type": "application/json"}
-            return content, headers
+            return content, {"Content-Type": "application/json"}
 
-        has_reflectapi_options = any(
-            isinstance(field_value, ReflectapiOption)
-            for field_value in raw_data.values()
-        )
+        from .partial import ReflectapiPartialModel
 
-        if has_reflectapi_options:
-            # Process each field to handle ReflectapiOption properly
-            processed_fields = {}
-            for field_name, field_value in raw_data.items():
-                if isinstance(field_value, ReflectapiOption):
-                    if not field_value.is_undefined:
-                        # Include the unwrapped value (including None for explicit null)
-                        processed_fields[field_name] = field_value._value
-                    # Skip undefined fields entirely - don't include them at all
-                else:
-                    # Include all other fields that aren't None (unless they're meaningful None values)
-                    if field_value is not None:
-                        processed_fields[field_name] = field_value
-
-            # Use json serialization with datetime handler for proper serialization
-            content = json.dumps(
-                processed_fields, default=_json_serializer, separators=(",", ":")
-            ).encode("utf-8")
+        if isinstance(json_model, ReflectapiPartialModel):
+            content = json_model.model_dump_json(by_alias=True).encode("utf-8")
         else:
-            # Use Pydantic's built-in JSON serialization with exclude_none and by_alias for proper handling
             content = json_model.model_dump_json(
-                exclude_none=True, by_alias=True
+                by_alias=True, exclude_none=True
             ).encode("utf-8")
-
-        headers = {"Content-Type": "application/json"}
-        return content, headers
+        return content, {"Content-Type": "application/json"}
 
     def _build_headers(
         self, base_headers: dict[str, str], headers_model: BaseModel | None
@@ -334,12 +307,8 @@ class ClientBase(ABC):
             content, base_headers = self._serialize_request_body(json_model)
             headers = self._build_headers(base_headers, headers_model)
         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
             content = json.dumps(
-                processed_json_data,
+                json_data,
                 default=_json_serializer,
                 separators=(",", ":"),
             ).encode("utf-8")
@@ -844,61 +813,34 @@ class AsyncClientBase(ABC):
     def _serialize_request_body(
         self, json_model: BaseModel | int | float | str | bool | list | dict
     ) -> tuple[bytes, dict[str, str]]:
-        """Serialize request body from Pydantic model or primitive type."""
-        from .option import ReflectapiOption
+        """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")]``.
+        """
         # Handle primitive types (for untagged unions)
-        if not hasattr(json_model, "model_dump"):
+        if not hasattr(json_model, "model_dump_json"):
             content = json.dumps(
                 json_model, default=_json_serializer, separators=(",", ":")
             ).encode("utf-8")
-            headers = {"Content-Type": "application/json"}
-            return content, headers
-
-        # Check if model has any ReflectapiOption fields that need special handling
-        raw_data = json_model.model_dump(exclude_none=False)
-
-        # Handle case where RootModel serializes to primitive value (e.g., strings for unit variants)
-        if not isinstance(raw_data, dict):
-            # For primitive values, use Pydantic's built-in JSON serialization
-            content = json_model.model_dump_json(
-                exclude_none=True, by_alias=True
-            ).encode("utf-8")
-            headers = {"Content-Type": "application/json"}
-            return content, headers
+            return content, {"Content-Type": "application/json"}
 
-        has_reflectapi_options = any(
-            isinstance(field_value, ReflectapiOption)
-            for field_value in raw_data.values()
-        )
+        from .partial import ReflectapiPartialModel
 
-        if has_reflectapi_options:
-            # Process each field to handle ReflectapiOption properly
-            processed_fields = {}
-            for field_name, field_value in raw_data.items():
-                if isinstance(field_value, ReflectapiOption):
-                    if not field_value.is_undefined:
-                        # Include the unwrapped value (including None for explicit null)
-                        processed_fields[field_name] = field_value._value
-                    # Skip undefined fields entirely - don't include them at all
-                else:
-                    # Include all other fields that aren't None (unless they're meaningful None values)
-                    if field_value is not None:
-                        processed_fields[field_name] = field_value
-
-            # Use json serialization with datetime handler for proper serialization
-            content = json.dumps(
-                processed_fields, default=_json_serializer, separators=(",", ":")
-            ).encode("utf-8")
+        if isinstance(json_model, ReflectapiPartialModel):
+            content = json_model.model_dump_json(by_alias=True).encode("utf-8")
         else:
-            # Use Pydantic's built-in JSON serialization with exclude_none and by_alias for proper handling
             content = json_model.model_dump_json(
-                exclude_none=True, by_alias=True
+                by_alias=True, exclude_none=True
             ).encode("utf-8")
-
-        headers = {"Content-Type": "application/json"}
-
-        return content, headers
+        return content, {"Content-Type": "application/json"}
 
     def _build_headers(
         self, base_headers: dict[str, str], headers_model: BaseModel | None
@@ -927,12 +869,8 @@ class AsyncClientBase(ABC):
             content, base_headers = self._serialize_request_body(json_model)
             headers = self._build_headers(base_headers, headers_model)
         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
             content = json.dumps(
-                processed_json_data,
+                json_data,
                 default=_json_serializer,
                 separators=(",", ":"),
             ).encode("utf-8")

reflectapi_runtime-0.17.3/src/reflectapi_runtime/duration.py

@@ -0,0 +1,73 @@
+"""Wire-format adapter for Rust's ``std::time::Duration``.
+
+serde serialises ``Duration`` as ``{"secs": <u64>, "nanos": <u32>}``.
+Pydantic v2's built-in ``timedelta`` validator accepts ISO-8601 strings,
+ints, and floats — it does **not** accept the ``{secs, nanos}`` dict
+that the server actually sends. The bare ``timedelta`` annotation
+emitted by older codegen therefore failed validation on every response
+that carried a ``Duration`` field.
+
+``ReflectapiDuration`` is the type the generated client uses instead. It
+preserves the ergonomic Python ``timedelta`` API (``td.total_seconds()``,
+arithmetic, comparisons) and round-trips the serde shape:
+
+- **Validating** (server → client): a ``{"secs": …, "nanos": …}`` dict
+  is converted to a ``timedelta``; ints/floats and existing
+  ``timedelta`` instances pass through unchanged so users can construct
+  models from Python values directly.
+- **Serialising** (client → server): the ``timedelta`` is written back
+  as ``{"secs": <int>, "nanos": <int>}`` so the wire payload round-trips
+  cleanly through ``serde::Deserialize`` on the server.
+
+Precision caveat: ``timedelta`` stores microseconds, so the bottom three
+decimal digits of ``nanos`` are truncated on round-trip. If a server
+ever sends a ``nanos`` value not divisible by 1 000 (sub-microsecond),
+the recovered ``nanos`` will be the closest microsecond-aligned value.
+For the durations reflectapi APIs typically carry (timeouts, retry
+hints, rate-limit windows) this is well below the noise floor.
+"""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import Annotated, Any
+
+from pydantic import BeforeValidator, PlainSerializer
+
+_NS_PER_SECOND = 1_000_000_000
+
+
+def _validate(value: Any) -> Any:
+    """Accept serde's ``{secs, nanos}`` dict; pass other forms through."""
+    if isinstance(value, dict):
+        secs = value.get("secs", 0)
+        nanos = value.get("nanos", 0)
+        if not isinstance(secs, (int, float)) or not isinstance(nanos, (int, float)):
+            return value  # let Pydantic raise its own validation error
+        return timedelta(seconds=secs, microseconds=nanos / 1_000)
+    return value
+
+
+def _serialise(value: timedelta) -> dict[str, int]:
+    """Emit the wire shape Rust's ``serde::Deserialize<Duration>`` expects."""
+    if not isinstance(value, timedelta):
+        # Pydantic already coerced; if anything else slips through, surface
+        # the failure rather than papering over it.
+        raise TypeError(
+            f"ReflectapiDuration serialiser expected a timedelta, got {type(value).__name__}"
+        )
+    # Pull total nanoseconds out of the timedelta in two integer pieces
+    # so we never round-trip through float and lose precision below the
+    # microsecond level.
+    total_us = (value.days * 86_400 + value.seconds) * 1_000_000 + value.microseconds
+    secs, micros = divmod(total_us, 1_000_000)
+    nanos = micros * 1_000
+    return {"secs": secs, "nanos": nanos}
+
+
+ReflectapiDuration = Annotated[
+    timedelta,
+    BeforeValidator(_validate),
+    PlainSerializer(_serialise, when_used="json"),
+]
+"""Pydantic field type for ``std::time::Duration`` — see module docstring."""

{reflectapi_runtime-0.17.2a4 → reflectapi_runtime-0.17.3}/src/reflectapi_runtime/hypothesis_strategies.py

@@ -20,25 +20,8 @@ except ImportError:
 
 from pydantic import BaseModel
 
-from .option import ReflectapiOption, Undefined
-
 if HAS_HYPOTHESIS:
 
-    def strategy_for_option(inner_strategy: st.SearchStrategy) -> st.SearchStrategy:
-        """Create a strategy for ReflectapiOption types.
-
-        Args:
-            inner_strategy: Strategy for the inner type T in Option<T>.
-
-        Returns:
-            Strategy that produces ReflectapiOption instances with undefined, None, or values.
-        """
-        return st.one_of(
-            st.just(ReflectapiOption(Undefined)),  # Undefined case
-            st.just(ReflectapiOption(None)),  # None case
-            inner_strategy.map(ReflectapiOption),  # Some(value) case
-        )
-
     def strategy_for_type(type_hint: type) -> st.SearchStrategy:
         """Generate a Hypothesis strategy for a given type hint.
 
@@ -69,15 +52,6 @@ if HAS_HYPOTHESIS:
         elif type_hint is uuid.UUID:
             return st.uuids()
 
-        # Handle ReflectapiOption specifically
-        if (
-            hasattr(type_hint, "__origin__")
-            and type_hint.__origin__ is ReflectapiOption
-        ):
-            inner_type = get_args(type_hint)[0] if get_args(type_hint) else Any
-            inner_strategy = strategy_for_type(inner_type)
-            return strategy_for_option(inner_strategy)
-
         # Handle generic types
         origin = get_origin(type_hint)
         args = get_args(type_hint)

reflectapi_runtime-0.17.3/src/reflectapi_runtime/partial.py

@@ -0,0 +1,110 @@
+"""Base class for generated Pydantic models with partial fields.
+
+reflectapi schemas distinguish three states for nullable fields
+declared as ``reflectapi::Option<T>``: ``Some(value)``, explicit
+``null``, and "key absent on the wire" (``Undefined``). TypeScript
+clients express this natively (``field?: T | null``); Rust clients use
+the ``reflectapi::Option<T>`` enum. The Python equivalent uses
+``ReflectapiPartialModel`` — a ``BaseModel`` mixin that:
+
+- leaves field types as plain ``T | None``, so Pydantic validates them
+  exactly as it would any other nullable field;
+- relies on ``model_fields_set`` — Pydantic's built-in record of which
+  fields were actually provided during deserialise or construction —
+  as the source of truth for "was this on the wire?";
+- 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``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, model_serializer
+
+
+class ReflectapiPartialModel(BaseModel):
+    """Base class for reflectapi models with partial (three-state) fields.
+
+    Wire-format guarantee: a field that was never explicitly set on the
+    instance is omitted from the serialised output entirely. A field set
+    to ``None`` is emitted as ``null``. A field set to a value is emitted
+    as that value. This mirrors what TypeScript clients produce for
+    ``field?: T | null`` and what Rust clients produce for
+    ``reflectapi::Option<T>``.
+
+    Usage on the read path:
+
+    .. code-block:: python
+
+        item = Item.model_validate({"name": "x"})  # snapshot key absent
+        "snapshot" in item.model_fields_set        # False — was absent
+
+        item = Item.model_validate({"name": "x", "snapshot": None})
+        "snapshot" in item.model_fields_set        # True — explicit null
+        item.snapshot is None                      # True
+
+    Usage on the write path:
+
+    .. code-block:: python
+
+        Item(name="x").model_dump_json()
+        # '{"name":"x"}'   — snapshot omitted because it wasn't set
+
+        Item(name="x", snapshot=None).model_dump_json()
+        # '{"name":"x","snapshot":null}'
+    """
+
+    # NOTE on ``model_fields_set`` and post-construction assignment:
+    # Pydantic populates ``model_fields_set`` during construction
+    # (kwargs) and deserialise (``model_validate``). Subsequent
+    # attribute writes do **not** add to that set unless the model's
+    # ``model_config`` enables ``validate_assignment=True``. The
+    # generated client code emits ``ConfigDict(extra="ignore",
+    # populate_by_name=True, validate_assignment=True)`` on every
+    # partial class for this reason, so users can also do
+    # ``m.snapshot = None`` after construction and have it land on the
+    # wire.
+
+    @model_serializer(mode="wrap")
+    def _serialize_partial(
+        self, handler: Any, info: Any | None = None
+    ) -> dict[str, Any]:
+        """Drop fields the caller never explicitly set.
+
+        Pydantic populates ``model_fields_set`` with the *field names*
+        of every field that was either present in the input dict during
+        ``model_validate`` *or* passed as a keyword to ``__init__``.
+        Defaults populated by Pydantic itself are excluded — which is
+        exactly the "was this on the wire?" signal we need.
+
+        Two complications the implementation has to handle:
+
+        1. When ``by_alias=True`` is in effect, the handler returns a
+           dict keyed by the field's serialization alias, not by its
+           Python attribute name. ``model_fields_set`` always holds the
+           Python name, so we expand it into the set of names that
+           could plausibly appear in ``data`` (Python name + alias).
+
+        2. RootModel and friends may return non-dict data (e.g. a bare
+           string for a unit-variant enum). In that case there's nothing
+           to filter; just pass it through.
+        """
+        data = handler(self)
+        if not isinstance(data, dict):
+            return data
+        emit_keys: set[str] = set()
+        model_fields = type(self).model_fields
+        for name in self.model_fields_set:
+            emit_keys.add(name)
+            field_info = model_fields.get(name)
+            if field_info is None:
+                continue
+            alias = field_info.serialization_alias or field_info.alias
+            if alias:
+                emit_keys.add(alias)
+        return {key: value for key, value in data.items() if key in emit_keys}

reflectapi_runtime-0.17.3/src/reflectapi_runtime/serde.py

@@ -0,0 +1,48 @@
+"""Serialization helpers used by generated ReflectAPI clients."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+
+VariantHandler = Callable[[Any], Any] | str
+VariantSerializers = dict[str, tuple[Callable[[Any], bool], Callable[[Any], Any]]]
+
+
+def parse_externally_tagged(
+    data: Any,
+    variants: dict[str, VariantHandler],
+    types: tuple[type[Any], ...],
+    enum_name: str,
+) -> Any:
+    """Parse an externally tagged enum from ``{"Variant": value}`` format."""
+    if types and isinstance(data, types):
+        return data
+    if isinstance(data, str) and data in variants:
+        handler = variants[data]
+        if handler == "_unit":
+            return data
+    if isinstance(data, dict):
+        if len(data) != 1:
+            raise ValueError("Externally tagged enum must have exactly one key")
+        key, value = next(iter(data.items()))
+        if key in variants:
+            handler = variants[key]
+            if handler == "_unit":
+                return key
+            if callable(handler):
+                return handler(value)
+    raise ValueError(f"Unknown variant for {enum_name}: {data}")
+
+
+def serialize_externally_tagged(
+    root: Any,
+    serializers: VariantSerializers,
+    enum_name: str,
+) -> Any:
+    """Serialize an externally tagged enum to ``{"Variant": value}`` format."""
+    for _variant_name, (check, serialize) in serializers.items():
+        if check(root):
+            return serialize(root)
+    raise ValueError(f"Cannot serialize {enum_name} variant: {type(root)}")

{reflectapi_runtime-0.17.2a4 → reflectapi_runtime-0.17.3}/src/reflectapi_runtime/streaming.py

@@ -11,7 +11,6 @@ import httpx
 from .auth import AuthHandler
 from .exceptions import ApplicationError, NetworkError, TimeoutError
 from .middleware import AsyncMiddleware, AsyncMiddlewareChain
-from .option import serialize_option_dict
 from .response import TransportMetadata
 
 if TYPE_CHECKING:
@@ -237,26 +236,23 @@ class AsyncStreamingClient:
 
         request_headers = headers.copy() if headers else {}
 
-        # Serialize Pydantic model
+        # Serialize Pydantic model. `ReflectapiPartialModel` emits its
+        # own @model_serializer that omits keys not in
+        # `model_fields_set`; explicit `None` values must round-trip
+        # for it. Plain Pydantic models use `exclude_none=True` so
+        # unset optional fields stay absent on the wire (matches
+        # serde's `skip_serializing_if = "Option::is_none"`).
         if json_model is not None:
-            # Use Pydantic with improved ReflectapiOption serialization
-            model_dict = json_model.model_dump(exclude_none=False)  # Keep explicit None
-
-            # Filter out Undefined values (ReflectapiOption serializer returns Undefined sentinel)
-            from .option import Undefined
-
-            final_dict = {
-                k: v
-                for k, v in model_dict.items()
-                if not (hasattr(v, "__class__") and v is Undefined)
-            }
-
-            import json
-
-            content = json.dumps(final_dict, separators=(",", ":")).encode("utf-8")
+            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")
             request_headers["Content-Type"] = "application/json"
 
-            # Build request with raw content
             request = self._client.build_request(
                 method=method,
                 url=url,