reflectapi-runtime 0.22.0__tar.gz → 0.23.0__tar.gz

{reflectapi_runtime-0.22.0 → reflectapi_runtime-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: reflectapi-runtime
-Version: 0.22.0
+Version: 0.23.0
 Summary: Runtime library for ReflectAPI Python clients
 Project-URL: Homepage, https://github.com/thepartly/reflectapi
 Project-URL: Repository, https://github.com/thepartly/reflectapi
@@ -28,6 +28,7 @@ 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: jsonschema>=4.23.0; extra == 'dev'
 Requires-Dist: mypy>=1.5.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
@@ -35,6 +36,7 @@ Requires-Dist: pytest>=7.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
 Provides-Extra: test
 Requires-Dist: hypothesis>=6.0.0; extra == 'test'
+Requires-Dist: jsonschema>=4.23.0; extra == 'test'
 Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
 Requires-Dist: pytest>=7.0.0; extra == 'test'
 Description-Content-Type: text/markdown

{reflectapi_runtime-0.22.0 → reflectapi_runtime-0.23.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "reflectapi-runtime"
-version = "0.22.0"
+version = "0.23.0"
 description = "Runtime library for ReflectAPI Python clients"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -41,6 +41,7 @@ dev = [
     "pytest-asyncio>=0.21.0",
     "pytest-cov>=4.0.0",
     "hypothesis>=6.0.0",
+    "jsonschema>=4.23.0",
     "mypy>=1.5.0",
     "ruff>=0.1.0",
 ]
@@ -48,6 +49,7 @@ test = [
     "pytest>=7.0.0",
     "pytest-asyncio>=0.21.0",
     "hypothesis>=6.0.0",
+    "jsonschema>=4.23.0",
 ]
 
 [project.urls]

{reflectapi_runtime-0.22.0 → reflectapi_runtime-0.23.0}/src/reflectapi_runtime/__init__.py

@@ -42,6 +42,9 @@ from .response import ApiResponse, ApiStream, AsyncApiStream, TransportMetadata
 from .serde import (
     UnknownEnumValue,
     classify_tagged_enum,
+    externally_tagged_json_schema,
+    flattened_enum_json_schema,
+    known_variants_json_schema,
     parse_externally_tagged,
     serialize_externally_tagged,
 )
@@ -55,7 +58,7 @@ from .testing import (
 )
 from .types import BatchResult, ReflectapiEmpty, ReflectapiInfallible
 
-__version__ = "0.22.0"
+__version__ = "0.23.0"
 
 __all__ = [
     # Authentication
@@ -96,6 +99,9 @@ __all__ = [
     "ReflectapiEmpty",
     "ReflectapiInfallible",
     "ReflectapiPartialModel",
+    "externally_tagged_json_schema",
+    "flattened_enum_json_schema",
+    "known_variants_json_schema",
     "parse_externally_tagged",
     "serialize_externally_tagged",
     "UnknownEnumValue",

{reflectapi_runtime-0.22.0 → reflectapi_runtime-0.23.0}/src/reflectapi_runtime/partial.py

@@ -70,12 +70,13 @@ class ReflectapiPartialModel(BaseModel):
     # ``m.snapshot = None`` after construction and have it land on the
     # wire.
 
-    # 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]:
+    # Deliberately no return annotation and no ``return_type``: a declared
+    # ``dict[str, Any]`` replaces the model's serialization-mode JSON schema
+    # with a bare object, so consumers' OpenAPI specs lose the type. The
+    # missing annotation also keeps Pydantic 2.10 from resolving a postponed
+    # annotation in a subclass's module, which need not import ``Any``.
+    @model_serializer(mode="wrap")
+    def _serialize_partial(self, handler: Any, info: Any | None = None):
         """Drop fields the caller never explicitly set.
 
         Pydantic populates ``model_fields_set`` with the *field names*

reflectapi_runtime-0.23.0/src/reflectapi_runtime/serde.py

@@ -0,0 +1,393 @@
+"""Serialization helpers used by generated ReflectAPI clients."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, model_serializer, model_validator
+
+if TYPE_CHECKING:
+    from pydantic import GetJsonSchemaHandler
+    from pydantic.json_schema import JsonSchemaValue
+    from pydantic_core import CoreSchema
+
+VariantHandler = Callable[[Any], Any] | str
+VariantSerializers = dict[str, tuple[Callable[[Any], bool], Callable[[Any], Any]]]
+
+# Marks the JSON schema of an open enum's unknown case, which the enum drops.
+_UNKNOWN_VARIANT = "x-reflectapi-unknown-variant"
+
+
+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.
+
+    It is left out of JSON schemas: an open enum is described by its known
+    variants, as the server's own schema describes it. Its own schema is a
+    marker that the enum's schema (``known_variants_json_schema``) drops. The
+    marker matches no value, so an enum generated without that hook still
+    describes its known variants only.
+    """
+
+    tag: str
+    raw: Any
+
+    @classmethod
+    def __get_pydantic_json_schema__(
+        cls, core_schema: CoreSchema, handler: GetJsonSchemaHandler
+    ) -> JsonSchemaValue:
+        return {"not": {}, _UNKNOWN_VARIANT: True}
+
+    @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)}")
+
+
+# Pydantic builds a JSON schema from a model's fields and never runs its
+# custom validators or serializers. The generated classes below reshape the
+# wire value in those hooks, so they also describe the wire shape through
+# ``__get_pydantic_json_schema__``, which calls one of these helpers.
+
+_WRAPPER_SCHEMAS = frozenset(
+    ("function-before", "function-after", "function-wrap", "definitions")
+)
+
+
+def _unwrap(schema: Any) -> Any:
+    while schema.get("type") in _WRAPPER_SCHEMAS and "schema" in schema:
+        schema = schema["schema"]
+    return schema
+
+
+def _root_choices(core_schema: CoreSchema) -> list[CoreSchema]:
+    """The members of a ``RootModel[Union[...]]`` root type, in declaration order."""
+    schema = _unwrap(core_schema)
+    if schema.get("type") == "model":
+        schema = _unwrap(schema["schema"])
+    if schema.get("type") != "union":
+        return [schema]
+    return [c[0] if isinstance(c, tuple) else c for c in schema["choices"]]
+
+
+def _member_json_schema(
+    handler: GetJsonSchemaHandler, member: CoreSchema
+) -> JsonSchemaValue:
+    """A union member's schema, as a ``$ref`` when the member is a model.
+
+    The handler inlines a schema it is given directly; a reference to the
+    definition that the enum's default schema already registered keeps it
+    shared.
+    """
+    ref = member.get("ref")
+    if ref is None:
+        return handler(member)
+    return handler({"type": "definition-ref", "schema_ref": ref})
+
+
+def _resolve(
+    handler: GetJsonSchemaHandler, schema: JsonSchemaValue
+) -> JsonSchemaValue | None:
+    """The definition a ``$ref`` points at, or ``None`` if not generated yet."""
+    try:
+        return handler.resolve_ref_schema(schema)
+    except LookupError:
+        return None
+
+
+def known_variants_json_schema(
+    core_schema: CoreSchema, handler: GetJsonSchemaHandler
+) -> JsonSchemaValue:
+    """Describe an open enum by its known variants, without the unknown case.
+
+    The unknown case is the last member of the generated root union.
+    """
+    schema = dict(handler.resolve_ref_schema(handler(core_schema)))
+    choices = _root_choices(core_schema)
+    unknown = _member_json_schema(handler, choices[-1])
+    for union in ("anyOf", "oneOf"):
+        members = schema.get(union)
+        if not members:
+            continue
+        known = [m for m in members if m != unknown and _UNKNOWN_VARIANT not in m]
+        if len(known) == 1:
+            del schema[union]
+            schema = {**known[0], **schema}
+        else:
+            schema[union] = known
+        break
+    return schema
+
+
+def _model_metadata(
+    core_schema: CoreSchema, default: JsonSchemaValue
+) -> JsonSchemaValue:
+    """The enum class's own title and description.
+
+    The default schema of a RootModel over a single model is that model's
+    schema, so its title and description come from the class instead.
+    """
+    cls = _unwrap(core_schema).get("cls")
+    if cls is None:
+        return {k: default[k] for k in ("title", "description") if k in default}
+    metadata: JsonSchemaValue = {"title": cls.model_config.get("title") or cls.__name__}
+    doc = cls.__dict__.get("__doc__")
+    if doc:
+        metadata["description"] = inspect.cleandoc(doc)
+    return metadata
+
+
+def _tuple_items(
+    handler: GetJsonSchemaHandler, variant: CoreSchema
+) -> list[Any] | None:
+    """The schemas of a tuple variant class's ``field_0``, ``field_1``, ..."""
+    resolved = _resolve(handler, _member_json_schema(handler, variant))
+    if resolved is None:
+        return None
+    properties = resolved.get("properties", {})
+    items = []
+    for index in range(len(properties)):
+        item = dict(properties[f"field_{index}"])
+        item.pop("title", None)
+        items.append(item)
+    return items
+
+
+def externally_tagged_json_schema(
+    core_schema: CoreSchema,
+    handler: GetJsonSchemaHandler,
+    variants: Sequence[tuple[str, str]],
+) -> JsonSchemaValue:
+    """Describe an externally tagged enum as it appears on the wire.
+
+    ``variants`` lists ``(wire_name, shape)`` in the order of the RootModel's
+    union members, where ``shape`` is ``"unit"`` (``"Name"``), ``"newtype"``
+    (``{"Name": value}``), ``"tuple"`` (``{"Name": [a, b]}``) or ``"struct"``
+    (``{"Name": {...}}``). Members after the listed variants (the unknown case
+    of an open enum) are left out.
+    """
+    default = handler(core_schema)
+    choices = _root_choices(core_schema)
+    if len(choices) < len(variants):
+        return default
+    resolved = _resolve(handler, default) or {}
+    alternatives: list[JsonSchemaValue] = []
+    for (tag, shape), choice in zip(variants, choices, strict=False):
+        if shape == "unit":
+            alternatives.append({"const": tag, "type": "string"})
+            continue
+        if shape == "struct":
+            payload = _member_json_schema(handler, choice)
+        else:
+            items = _tuple_items(handler, choice)
+            if items is None:
+                return default
+            if shape == "newtype":
+                payload = items[0]
+            else:
+                payload = {
+                    "type": "array",
+                    "prefixItems": items,
+                    "minItems": len(items),
+                    "maxItems": len(items),
+                }
+        alternatives.append(
+            {"type": "object", "properties": {tag: payload}, "required": [tag]}
+        )
+    schema: JsonSchemaValue = (
+        alternatives[0] if len(alternatives) == 1 else {"oneOf": alternatives}
+    )
+    schema.update(_model_metadata(core_schema, resolved))
+    return schema
+
+
+def _flattened_alternative(alternative: JsonSchemaValue) -> JsonSchemaValue:
+    # A flattened unit variant of an externally tagged enum is a key with a
+    # null value, not a bare string.
+    if alternative.get("type") == "string" and "const" in alternative:
+        tag = alternative["const"]
+        return {
+            "type": "object",
+            "properties": {tag: {"type": "null"}},
+            "required": [tag],
+        }
+    return alternative
+
+
+def flattened_enum_json_schema(
+    core_schema: CoreSchema,
+    handler: GetJsonSchemaHandler,
+    field: str,
+    keys: Sequence[str],
+    *,
+    optional: bool = False,
+) -> JsonSchemaValue:
+    """Describe a struct whose enum field ``field`` is flattened into it.
+
+    The enum's keys sit next to the struct's own, so the schema is the
+    struct's other fields combined with the enum's schema. ``keys`` are the
+    keys that mark the enum as present (its tag, or the variant names of an
+    externally tagged enum); an ``optional`` group may also be absent.
+    """
+    parent = dict(handler.resolve_ref_schema(handler(core_schema)))
+    properties = dict(parent.get("properties", {}))
+    enum_schema = properties.pop(field, None)
+    if enum_schema is None:
+        return parent
+    parent["properties"] = properties
+    required = [name for name in parent.get("required", []) if name != field]
+    if required:
+        parent["required"] = required
+    else:
+        parent.pop("required", None)
+    if optional and "anyOf" in enum_schema:
+        present = [s for s in enum_schema["anyOf"] if s.get("type") != "null"]
+        enum_schema = present[0] if len(present) == 1 else {"anyOf": present}
+    resolved = _resolve(handler, enum_schema) or {}
+    # An externally tagged enum with only unit variants is a string enum.
+    tags = resolved.get("enum")
+    if tags is not None:
+        enum_schema = {
+            "oneOf": [
+                _flattened_alternative({"const": tag, "type": "string"}) for tag in tags
+            ]
+        }
+    else:
+        for union in ("oneOf", "anyOf"):
+            alternatives = resolved.get(union)
+            if alternatives and any(
+                _flattened_alternative(a) is not a for a in alternatives
+            ):
+                enum_schema = {union: [_flattened_alternative(a) for a in alternatives]}
+                break
+    if optional:
+        present_keys = [{"required": [key]} for key in keys]
+        absent = {
+            "not": present_keys[0]
+            if len(present_keys) == 1
+            else {"anyOf": present_keys}
+        }
+        enum_schema = {"anyOf": [enum_schema, absent]}
+    outer: JsonSchemaValue = {"allOf": [enum_schema, parent]}
+    for key in ("title", "description"):
+        if key in parent:
+            outer[key] = parent.pop(key)
+    return outer

reflectapi_runtime-0.23.0/tests/test_json_schema.py

@@ -0,0 +1,335 @@
+"""JSON schemas of models whose custom hooks reshape the wire value.
+
+The classes below follow the shape of generated code. Pydantic never runs a
+model's validators or serializers to build its JSON schema, so each class
+describes its wire shape through ``__get_pydantic_json_schema__``.
+"""
+
+# The classes spell unions as `Union[...]` and string enums as `(str, Enum)`,
+# as generated code does.
+# ruff: noqa: UP007, UP042
+
+from __future__ import annotations
+
+import json
+from enum import Enum
+from typing import Annotated, Any, Literal, Union
+
+import jsonschema
+import pytest
+from pydantic import BaseModel, Field, RootModel, model_serializer, model_validator
+from pydantic.json_schema import JsonSchemaMode
+
+from reflectapi_runtime import (
+    UnknownEnumValue,
+    classify_tagged_enum,
+    externally_tagged_json_schema,
+    flattened_enum_json_schema,
+    known_variants_json_schema,
+    parse_externally_tagged,
+    serialize_externally_tagged,
+)
+
+MODES: tuple[JsonSchemaMode, ...] = ("validation", "serialization")
+
+
+class PairVariant(BaseModel):
+    field_0: int
+    field_1: str
+
+
+class CountVariant(BaseModel):
+    field_0: int
+
+
+class NamedVariant(BaseModel):
+    name: str
+
+
+class ShapeUnknown(UnknownEnumValue):
+    pass
+
+
+class Shape(
+    RootModel[
+        Union[Literal["Empty"], PairVariant, CountVariant, NamedVariant, ShapeUnknown]
+    ]
+):
+    """Externally tagged enum"""
+
+    @model_validator(mode="before")
+    @classmethod
+    def _validate(cls, data: Any) -> Any:
+        return parse_externally_tagged(
+            data,
+            {
+                "Empty": "_unit",
+                "Pair": lambda v: PairVariant(field_0=v[0], field_1=v[1]),
+                "Count": lambda v: CountVariant(field_0=v),
+                "Named": lambda v: NamedVariant.model_validate(v),
+            },
+            (PairVariant, CountVariant, NamedVariant),
+            "Shape",
+            unknown_type=ShapeUnknown,
+        )
+
+    @model_serializer
+    def _serialize(self):  # a declared return type would become the schema
+        return serialize_externally_tagged(
+            self.root,
+            {
+                "Empty": (lambda r: r == "Empty", lambda r: "Empty"),
+                "Pair": (
+                    lambda r: isinstance(r, PairVariant),
+                    lambda r: {"Pair": [r.field_0, r.field_1]},
+                ),
+                "Count": (
+                    lambda r: isinstance(r, CountVariant),
+                    lambda r: {"Count": r.field_0},
+                ),
+                "Named": (
+                    lambda r: isinstance(r, NamedVariant),
+                    lambda r: {"Named": r.model_dump(by_alias=True)},
+                ),
+            },
+            "Shape",
+        )
+
+    @classmethod
+    def __get_pydantic_json_schema__(cls, core_schema: Any, handler: Any) -> Any:
+        return externally_tagged_json_schema(
+            core_schema,
+            handler,
+            (
+                ("Empty", "unit"),
+                ("Pair", "tuple"),
+                ("Count", "newtype"),
+                ("Named", "struct"),
+            ),
+        )
+
+
+class Dog(BaseModel):
+    kind: Literal["Dog"] = "Dog"
+    breed: str
+
+
+class Bird(BaseModel):
+    kind: Literal["Bird"] = "Bird"
+
+
+class AnimalUnknown(UnknownEnumValue):
+    pass
+
+
+AnimalKnown = Annotated[Union[Dog, Bird], Field(discriminator="kind")]
+
+
+class Animal(RootModel[Union[AnimalKnown, AnimalUnknown]]):
+    root: Union[AnimalKnown, AnimalUnknown]
+
+    @model_validator(mode="before")
+    @classmethod
+    def _classify(cls, data: Any) -> Any:
+        return classify_tagged_enum(
+            data,
+            frozenset(("Dog", "Bird")),
+            representation="tagged",
+            tag_field="kind",
+            unknown_type=AnimalUnknown,
+        )
+
+    @classmethod
+    def __get_pydantic_json_schema__(cls, core_schema: Any, handler: Any) -> Any:
+        return known_variants_json_schema(core_schema, handler)
+
+
+class Envelope(BaseModel):
+    id: int
+    value: Animal
+
+    @model_validator(mode="before")
+    @classmethod
+    def _unflatten_enum(cls, data: Any) -> Any:
+        if not isinstance(data, dict) or "kind" not in data:
+            return data
+        parent = {key: value for key, value in data.items() if key == "id"}
+        parent["value"] = {key: value for key, value in data.items() if key != "id"}
+        return parent
+
+    @model_serializer(mode="wrap")
+    def _flatten_enum(self, handler: Any):  # likewise
+        value = handler(self)
+        enum_value = value.pop("value")
+        return {**value, **enum_value}
+
+    @classmethod
+    def __get_pydantic_json_schema__(cls, core_schema: Any, handler: Any) -> Any:
+        return flattened_enum_json_schema(core_schema, handler, "value", ("kind",))
+
+
+class ClosedShape(RootModel[Union[Literal["Empty"], NamedVariant]]):
+    @model_validator(mode="before")
+    @classmethod
+    def _validate(cls, data: Any) -> Any:
+        return parse_externally_tagged(
+            data,
+            {"Empty": "_unit", "Named": lambda v: NamedVariant(**v)},
+            (NamedVariant,),
+            "ClosedShape",
+        )
+
+    @model_serializer
+    def _serialize(self):  # a declared return type would become the schema
+        return serialize_externally_tagged(
+            self.root,
+            {
+                "Empty": (lambda r: r == "Empty", lambda r: "Empty"),
+                "Named": (
+                    lambda r: isinstance(r, NamedVariant),
+                    lambda r: {"Named": r.model_dump(by_alias=True)},
+                ),
+            },
+            "ClosedShape",
+        )
+
+    @classmethod
+    def __get_pydantic_json_schema__(cls, core_schema: Any, handler: Any) -> Any:
+        return externally_tagged_json_schema(
+            core_schema, handler, (("Empty", "unit"), ("Named", "struct"))
+        )
+
+
+class OptionalEnvelope(BaseModel):
+    id: int
+    value: ClosedShape | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _unflatten_enum(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+        present = {"Empty", "Named"}.intersection(data)
+        parent = {key: value for key, value in data.items() if key == "id"}
+        if present:
+            key = next(iter(present))
+            parent["value"] = {key: data[key]}
+        return parent
+
+    @model_serializer(mode="wrap")
+    def _flatten_enum(self, handler: Any):  # likewise
+        value = handler(self)
+        enum_value = value.pop("value", None)
+        if enum_value is None:
+            return value
+        if isinstance(enum_value, str):
+            enum_value = {enum_value: None}
+        return {**value, **enum_value}
+
+    @classmethod
+    def __get_pydantic_json_schema__(cls, core_schema: Any, handler: Any) -> Any:
+        return flattened_enum_json_schema(
+            core_schema, handler, "value", ("Empty", "Named"), optional=True
+        )
+
+
+def matches(schema: dict[str, Any], value: Any) -> bool:
+    return jsonschema.Draft202012Validator(schema).is_valid(value)
+
+
+WIRE = {
+    Shape: ["Empty", {"Pair": [1, "one"]}, {"Count": 3}, {"Named": {"name": "n"}}],
+    Animal: [{"kind": "Dog", "breed": "corgi"}, {"kind": "Bird"}],
+    Envelope: [{"id": 1, "kind": "Dog", "breed": "corgi"}, {"id": 1, "kind": "Bird"}],
+    OptionalEnvelope: [
+        {"id": 1},
+        {"id": 1, "Empty": None},
+        {"id": 1, "Named": {"name": "n"}},
+    ],
+}
+
+
+@pytest.mark.parametrize("mode", MODES)
+@pytest.mark.parametrize(
+    ("model", "wire"),
+    [(model, wire) for model, wires in WIRE.items() for wire in wires],
+    ids=lambda v: json.dumps(v) if not isinstance(v, type) else v.__name__,
+)
+def test_schema_accepts_the_wire_value(
+    model: type[BaseModel], wire: Any, mode: JsonSchemaMode
+) -> None:
+    assert json.loads(model.model_validate(wire).model_dump_json()) == wire
+    assert matches(model.model_json_schema(mode=mode), wire)
+
+
+@pytest.mark.parametrize("mode", MODES)
+@pytest.mark.parametrize(
+    ("model", "wire"),
+    [
+        (Shape, {"field_0": 1, "field_1": "one"}),
+        (Shape, {"Pair": [1]}),
+        (Shape, {"Count": {"field_0": 3}}),
+        (OptionalEnvelope, {"id": 1, "Empty": "Empty"}),
+    ],
+)
+def test_schema_rejects_the_python_shape(
+    model: type[BaseModel], wire: Any, mode: JsonSchemaMode
+) -> None:
+    assert not matches(model.model_json_schema(mode=mode), wire)
+
+
+@pytest.mark.parametrize("mode", MODES)
+def test_unknown_case_is_left_out(mode: JsonSchemaMode) -> None:
+    for model in (Shape, Animal, Envelope):
+        schema = json.dumps(model.model_json_schema(mode=mode))
+        assert "Unknown" not in schema
+        assert "x-reflectapi-unknown-variant" not in schema
+
+
+def test_animal_keeps_discriminator() -> None:
+    schema = Animal.model_json_schema()
+    assert schema["discriminator"]["propertyName"] == "kind"
+    assert len(schema["oneOf"]) == 2
+
+
+@pytest.mark.parametrize("mode", MODES)
+def test_flattened_enum_has_no_nested_field(mode: JsonSchemaMode) -> None:
+    for model in (Envelope, OptionalEnvelope):
+        schema = model.model_json_schema(mode=mode)
+        enum, parent = schema["allOf"]
+        assert parent["properties"].keys() == {"id"}
+        assert parent["required"] == ["id"]
+
+
+class Colour(str, Enum):
+    RED = "Red"
+
+
+class PaintUnknown(UnknownEnumValue):
+    pass
+
+
+# An open enum generated before `known_variants_json_schema`, without the hook
+class Paint(RootModel[Union[Colour, PaintUnknown]]):
+    root: Union[Colour, PaintUnknown]
+
+    @model_validator(mode="before")
+    @classmethod
+    def _classify(cls, data: Any) -> Any:
+        return classify_tagged_enum(
+            data,
+            frozenset(("Red",)),
+            representation="external",
+            unknown_type=PaintUnknown,
+            unit_tags=frozenset(("Red",)),
+        )
+
+
+@pytest.mark.parametrize("mode", MODES)
+def test_unknown_case_matches_nothing_without_the_enum_hook(
+    mode: JsonSchemaMode,
+) -> None:
+    schema = Paint.model_json_schema(mode=mode)
+    assert matches(schema, "Red")
+    assert not matches(schema, "Blue")
+    assert not matches(schema, {"tag": "Blue", "raw": "Blue"})

{reflectapi_runtime-0.22.0 → reflectapi_runtime-0.23.0}/tests/test_partial.py

@@ -251,3 +251,21 @@ def test_partial_subclass_does_not_require_any_in_callers_module(monkeypatch):
     assert caller.Request(required=None, optional=None).model_dump_json() == (
         '{"required":null,"optional":null}'
     )
+
+
+class TestJsonSchema:
+    """The serializer must not hide the model from serialization-mode schemas."""
+
+    def test_serialization_schema_keeps_model_properties(self):
+        schema = PartialItem.model_json_schema(mode="serialization")
+        assert set(schema["properties"]) == {"identity", "snapshot"}
+        assert schema["required"] == ["identity"]
+
+    def test_serialization_schema_keeps_nested_partial_refs(self):
+        schema = PartialItem.model_json_schema(mode="serialization")
+        refs = json.dumps(schema["properties"]["snapshot"])
+        assert "PartialSnapshot" in refs
+        assert set(schema["$defs"]["PartialSnapshot"]["properties"]) == {
+            "name",
+            "description",
+        }

{reflectapi_runtime-0.22.0 → reflectapi_runtime-0.23.0}/tests/test_sse.py

@@ -68,6 +68,13 @@ def test_parse_ignores_comments_and_unknown_fields() -> None:
     assert events == [SseEvent(data="kept")]
 
 
+def test_parse_skips_keep_alive_comments_between_events() -> None:
+    # A server keeps an idle stream open with `:` comment blocks.
+    payload = "data: 1\n\n:\n\n:\n\ndata: 2\n\n"
+    events = list(parse_sse(_lines(payload)))
+    assert events == [SseEvent(data="1"), SseEvent(data="2")]
+
+
 def test_parse_field_without_colon_treated_as_empty_value() -> None:
     events = list(parse_sse(_lines("data\n\n")))
     assert events == [SseEvent(data="")]

reflectapi_runtime-0.22.0/src/reflectapi_runtime/serde.py

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