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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: reflectapi-runtime
-Version: 0.19.0
+Version: 0.20.0
 Summary: Runtime library for ReflectAPI Python clients
 Project-URL: Homepage, https://github.com/thepartly/reflectapi
 Project-URL: Repository, https://github.com/thepartly/reflectapi
@@ -19,9 +19,13 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
-Requires-Dist: httpx>=0.25.0
-Requires-Dist: pydantic>=2.0.0
-Requires-Dist: typing-extensions>=4.4.0
+Requires-Dist: anyio>=4.14.2
+Requires-Dist: httpcore>=1.0.9
+Requires-Dist: httpx>=0.25.2
+Requires-Dist: idna>=3.15
+Requires-Dist: pydantic>=2.10.0; python_version < '3.14'
+Requires-Dist: pydantic>=2.12.0; python_version >= '3.14'
+Requires-Dist: typing-extensions>=4.5.0
 Provides-Extra: dev
 Requires-Dist: hypothesis>=6.0.0; extra == 'dev'
 Requires-Dist: mypy>=1.5.0; extra == 'dev'
@@ -81,12 +85,15 @@ against the declared item model. The wire format is Server-Sent Events
 do not enter the iterator. Breaking out of the loop or calling
 `stream.aclose()` releases the underlying HTTP connection.
 
-Validation is strict: an event whose payload doesn't match the item model
-(for example, an unknown discriminated-union variant added by a newer
-server) raises `ValidationError` mid-stream and the iterator terminates.
-Items received before the bad event are still delivered.
+Events are validated against the generated model. Closed response enums reject
+unfamiliar variants; enums declared with `#[reflectapi(open)]` retain them as
+an unknown case with the tag and parsed JSON, and `#[serde(other)]` uses the
+declared fallback. A malformed known variant raises `ValidationError`
+mid-stream and terminates the iterator. Earlier items remain delivered.
 
 ## Compatibility
 
-Python 3.12+. The package targets the same `reflectapi` minor version as
-the schema you generate from; mismatches will surface at import time.
+Python 3.12+. SDKs generated with ReflectAPI 0.20 require the 0.20 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.19.0 → reflectapi_runtime-0.20.0}/README.md

@@ -44,12 +44,15 @@ against the declared item model. The wire format is Server-Sent Events
 do not enter the iterator. Breaking out of the loop or calling
 `stream.aclose()` releases the underlying HTTP connection.
 
-Validation is strict: an event whose payload doesn't match the item model
-(for example, an unknown discriminated-union variant added by a newer
-server) raises `ValidationError` mid-stream and the iterator terminates.
-Items received before the bad event are still delivered.
+Events are validated against the generated model. Closed response enums reject
+unfamiliar variants; enums declared with `#[reflectapi(open)]` retain them as
+an unknown case with the tag and parsed JSON, and `#[serde(other)]` uses the
+declared fallback. A malformed known variant raises `ValidationError`
+mid-stream and terminates the iterator. Earlier items remain delivered.
 
 ## Compatibility
 
-Python 3.12+. The package targets the same `reflectapi` minor version as
-the schema you generate from; mismatches will surface at import time.
+Python 3.12+. SDKs generated with ReflectAPI 0.20 require the 0.20 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.19.0 → reflectapi_runtime-0.20.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "reflectapi-runtime"
-version = "0.19.0"
+version = "0.20.0"
 description = "Runtime library for ReflectAPI Python clients"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -26,9 +26,13 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "pydantic>=2.0.0",
-    "httpx>=0.25.0",
-    "typing-extensions>=4.4.0",
+    "pydantic>=2.10.0; python_version < '3.14'",
+    "pydantic>=2.12.0; python_version >= '3.14'",
+    "httpx>=0.25.2",
+    "httpcore>=1.0.9",
+    "anyio>=4.14.2",
+    "idna>=3.15",
+    "typing-extensions>=4.5.0",
 ]
 
 [project.optional-dependencies]

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

@@ -39,7 +39,12 @@ from .hypothesis_strategies import (
 from .middleware import AsyncMiddleware
 from .partial import ReflectapiPartialModel
 from .response import ApiResponse, ApiStream, AsyncApiStream, TransportMetadata
-from .serde import parse_externally_tagged, serialize_externally_tagged
+from .serde import (
+    UnknownEnumValue,
+    classify_tagged_enum,
+    parse_externally_tagged,
+    serialize_externally_tagged,
+)
 from .streaming import AsyncStreamingClient, StreamingResponse
 from .testing import (
     AsyncCassetteMiddleware,
@@ -50,7 +55,7 @@ from .testing import (
 )
 from .types import BatchResult, ReflectapiEmpty, ReflectapiInfallible
 
-__version__ = "0.19.0"
+__version__ = "0.20.0"
 
 __all__ = [
     # Authentication
@@ -93,6 +98,8 @@ __all__ = [
     "ReflectapiPartialModel",
     "parse_externally_tagged",
     "serialize_externally_tagged",
+    "UnknownEnumValue",
+    "classify_tagged_enum",
     "StreamingResponse",
     "ApiStream",
     "AsyncApiStream",

reflectapi_runtime-0.20.0/src/reflectapi_runtime/serde.py

@@ -0,0 +1,141 @@
+"""Serialization helpers used by generated ReflectAPI clients."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from pydantic import BaseModel, model_serializer, model_validator
+
+VariantHandler = Callable[[Any], Any] | str
+VariantSerializers = dict[str, tuple[Callable[[Any], bool], Callable[[Any], Any]]]
+
+
+class UnknownEnumValue(BaseModel):
+    """An output enum case whose wire tag was not in the generated schema.
+
+    Generated clients construct this after checking the wire discriminator. A
+    raw object cannot be validated directly as this case, which keeps malformed
+    known cases from silently falling through a Pydantic union.
+    """
+
+    tag: str
+    raw: Any
+
+    @model_validator(mode="before")
+    @classmethod
+    def _instance_only(cls, value: Any) -> Any:
+        if not isinstance(value, cls):
+            raise ValueError("Unknown enum cases are created from unfamiliar wire tags")
+        return value
+
+    @model_serializer(mode="plain")
+    def _serialize_raw(self) -> Any:
+        return self.raw
+
+
+def classify_tagged_enum(
+    data: Any,
+    known_tags: frozenset[str],
+    *,
+    representation: str,
+    tag_field: str = "",
+    content_field: str = "",
+    fallback_tag: str | None = None,
+    unknown_type: type[UnknownEnumValue] | None = None,
+    unit_tags: frozenset[str] = frozenset(),
+) -> Any:
+    """Classify an unfamiliar valid tag without masking other validation errors."""
+    if isinstance(data, UnknownEnumValue):
+        return data
+    if representation == "external":
+        if isinstance(data, str):
+            tag = data
+        elif isinstance(data, dict) and len(data) == 1:
+            tag = next(iter(data))
+        else:
+            return data
+    elif isinstance(data, dict):
+        if tag_field not in data or not isinstance(data[tag_field], str):
+            raise ValueError("Tagged enum requires a string discriminator")
+        tag = data[tag_field]
+    else:
+        return data
+    if isinstance(tag, str) and tag in unit_tags and isinstance(data, dict):
+        if representation == "adjacent" and data.get(content_field) is not None:
+            raise ValueError("Unit variant cannot carry non-null content")
+        if representation == "external":
+            if data[tag] is not None:
+                raise ValueError("Unit variant cannot carry non-null content")
+            return tag
+    if not isinstance(tag, str) or tag in known_tags:
+        return data
+    if (
+        representation == "adjacent"
+        and unknown_type is None
+        and fallback_tag is not None
+        and data.get(content_field) is not None
+    ):
+        raise ValueError("Fallback unit variant cannot carry non-null content")
+    if unknown_type is not None:
+        return unknown_type.model_construct(tag=tag, raw=data)
+    if fallback_tag is not None:
+        if representation == "external":
+            return fallback_tag
+        return {tag_field: fallback_tag}
+    return data
+
+
+def parse_externally_tagged(
+    data: Any,
+    variants: dict[str, VariantHandler],
+    types: tuple[type[Any], ...],
+    enum_name: str,
+    *,
+    fallback_tag: str | None = None,
+    unknown_type: type[UnknownEnumValue] | None = None,
+    strict_unit: bool = False,
+) -> Any:
+    """Parse an externally tagged enum from ``{"Variant": value}`` format."""
+    if types and isinstance(data, types):
+        return data
+    data = classify_tagged_enum(
+        data,
+        frozenset(variants),
+        representation="external",
+        fallback_tag=fallback_tag,
+        unknown_type=unknown_type,
+    )
+    if isinstance(data, UnknownEnumValue):
+        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":
+                if strict_unit and value is not None:
+                    raise ValueError(f"Unit variant {key} cannot carry a payload")
+                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."""
+    if isinstance(root, UnknownEnumValue):
+        return root.raw
+    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.20.0/tests/test_enum_forward_compatibility.py

@@ -0,0 +1,129 @@
+"""The runtime must preserve future response cases without hiding bad known cases."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+import pytest
+from pydantic import BaseModel, RootModel, ValidationError, model_validator
+
+from reflectapi_runtime import (
+    UnknownEnumValue,
+    classify_tagged_enum,
+    parse_externally_tagged,
+    serialize_externally_tagged,
+)
+
+
+class Known(BaseModel):
+    kind: Literal["Known"]
+    value: int
+
+
+class FutureUnknown(UnknownEnumValue):
+    pass
+
+
+class OpenResult(RootModel[Known | FutureUnknown]):
+    root: Known | FutureUnknown
+
+    @model_validator(mode="before")
+    @classmethod
+    def _classify(cls, data):
+        return classify_tagged_enum(
+            data,
+            frozenset(("Known",)),
+            representation="tagged",
+            tag_field="kind",
+            unknown_type=FutureUnknown,
+        )
+
+
+class Envelope(BaseModel):
+    results: list[OpenResult]
+
+
+def test_open_case_round_trips_inside_nested_model():
+    wire = {"results": [{"kind": "Known", "value": 2}, {"kind": "Future", "x": [1]}]}
+    parsed = Envelope.model_validate(wire)
+    assert isinstance(parsed.results[0].root, Known)
+    unknown = parsed.results[1].root
+    assert isinstance(unknown, FutureUnknown)
+    assert unknown.tag == "Future"
+    assert unknown.raw == wire["results"][1]
+    assert parsed.model_dump() == wire
+    assert Envelope.model_validate_json(parsed.model_dump_json()).model_dump() == wire
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        {"kind": "Known", "value": "not an integer"},
+        {"value": 2},
+        {"kind": 42, "value": 2},
+        {"kind": None, "value": 2},
+    ],
+)
+def test_open_case_rejects_malformed_known_or_missing_tag(value):
+    with pytest.raises(ValidationError):
+        OpenResult.model_validate(value)
+
+
+def test_other_fallback_discards_unfamiliar_payload():
+    assert classify_tagged_enum(
+        {"kind": "Future", "payload": {"x": 1}},
+        frozenset(("Known", "Other")),
+        representation="tagged",
+        tag_field="kind",
+        fallback_tag="Other",
+    ) == {"kind": "Other"}
+    assert classify_tagged_enum(
+        {"kind": "Known", "value": "bad"},
+        frozenset(("Known", "Other")),
+        representation="tagged",
+        tag_field="kind",
+        fallback_tag="Other",
+    ) == {"kind": "Known", "value": "bad"}
+
+
+def test_external_unknown_string_and_single_key_object():
+    for wire in ("Future", {"Future": {"x": 1}}):
+        unknown = parse_externally_tagged(
+            wire,
+            {"Known": "_unit"},
+            (),
+            "Result",
+            unknown_type=FutureUnknown,
+        )
+        assert isinstance(unknown, FutureUnknown)
+        assert unknown.tag == "Future"
+        assert serialize_externally_tagged(unknown, {}, "Result") == wire
+
+
+def test_external_unit_object_normalizes_to_known_literal():
+    assert classify_tagged_enum(
+        {"Known": None},
+        frozenset(("Known",)),
+        representation="external",
+        unit_tags=frozenset(("Known",)),
+    ) == "Known"
+    for payload in (1, {"bad": True}):
+        with pytest.raises(ValueError):
+            classify_tagged_enum(
+                {"Known": payload},
+                frozenset(("Known",)),
+                representation="external",
+                unit_tags=frozenset(("Known",)),
+            )
+
+
+@pytest.mark.parametrize("wire", [{"A": 1, "B": 2}, {42: "value"}, None, 42])
+def test_external_malformed_tags_do_not_become_unknown(wire):
+    with pytest.raises(ValueError):
+        parse_externally_tagged(
+            wire,
+            {"Known": "_unit"},
+            (),
+            "Result",
+            unknown_type=FutureUnknown,
+        )

reflectapi_runtime-0.19.0/src/reflectapi_runtime/serde.py

@@ -1,48 +0,0 @@
-"""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)}")