hyperfluid 0.1.0__py3-none-any.whl

hyperfluid/serialization.py

@@ -0,0 +1,911 @@
+# this file is @generated by Perseid; edit the shared runtime template.
+"""(De)serialization support for the generated Hyperfluid models.
+
+The generated models are plain :mod:`dataclasses`. All JSON conversion lives
+here, driven by their type annotations, so the generated code stays declarative
+and dependency free.
+
+* An optional field left to ``None`` is omitted from the payload. An optional
+  field that the API accepts as ``null`` defaults to :data:`UNSET` instead:
+  ``UNSET`` is omitted, while ``None`` is sent as ``null`` (to clear a value).
+  A required field is always sent.
+* JSON properties, enum values and union variants added to the API after
+  this SDK was generated are kept as received, and sent back unchanged.
+  Models whose schema types its ``additionalProperties`` decode the
+  properties they do not declare into that type, in ``extra_fields``.
+* ``Decimal`` values travel as JSON strings, ``datetime`` values as RFC 3339
+  strings. Only finite decimals are valid: ``NaN`` and ``Infinity`` are
+  rejected in both directions.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime as _datetime
+import enum
+import importlib
+import json
+import re
+import sys
+import types
+import typing as t
+import uuid as _uuid
+from decimal import Decimal
+
+__all__ = [
+    "FROM_CONTENT",
+    "UNSET",
+    "HyperfluidError",
+    "BaseModel",
+    "Discriminator",
+    "IntEnum",
+    "JSONValue",
+    "ModelParseError",
+    "StrEnum",
+    "TaggedUnionModel",
+    "UnknownVariant",
+    "Unset",
+    "format_decimal",
+    "from_json_value",
+    "parse_datetime",
+    "parse_decimal",
+    "to_json_value",
+]
+
+_M = t.TypeVar("_M", bound="BaseModel")
+
+JSONValue: t.TypeAlias = (
+    "dict[str, JSONValue] | list[JSONValue] | str | int | float | bool | None"
+)
+"""A decoded JSON value."""
+
+
+# `HyperfluidError` is defined here rather than in `errors.py` because the
+# generated models import this module and `errors.py` imports the models. It is
+# re-exported from `hyperfluid.errors` and `hyperfluid`, which is where to import it.
+class HyperfluidError(Exception):
+    """Base class for every error raised by this SDK."""
+
+
+class ModelParseError(HyperfluidError, ValueError):
+    """Raised when a payload cannot be mapped onto a model.
+
+    It is also a :class:`ValueError`. A client call never lets it escape on its
+    own: a response body that fails to parse raises
+    :class:`hyperfluid.errors.APIResponseValidationError`, chained to this error.
+    """
+
+
+class Unset(enum.Enum):
+    """The type of :data:`UNSET`."""
+
+    UNSET = "UNSET"
+
+    def __bool__(self) -> t.Literal[False]:
+        return False
+
+    def __repr__(self) -> str:
+        return "UNSET"
+
+
+FROM_CONTENT: t.Any = None
+"""Default of a tagged union's discriminator: the tag of its content's model."""
+
+UNSET: t.Final = Unset.UNSET
+"""Default of the optional fields that also accept ``null``: the field is left
+out of the payload, whereas ``None`` sends ``null``."""
+
+
+class StrEnum(str, enum.Enum):
+    """A string enum that keeps values this SDK version does not know.
+
+    ``Color("ultraviolet")`` returns a member whose ``value`` is
+    ``"ultraviolet"`` and whose ``is_known`` is false, instead of raising.
+    """
+
+    def __str__(self) -> str:
+        return str(self.value)
+
+    @classmethod
+    def _missing_(cls, value: object) -> t.Any:
+        if not isinstance(value, str):
+            return None
+        member = str.__new__(cls, value)
+        member._name_ = value
+        member._value_ = value
+        return member
+
+    @property
+    def is_known(self) -> bool:
+        """Whether the value is one of those declared by the API spec."""
+        return self._value_ in type(self)._value2member_map_
+
+
+class IntEnum(int, enum.Enum):
+    """An integer enum that keeps values this SDK version does not know."""
+
+    def __str__(self) -> str:
+        return str(self.value)
+
+    @classmethod
+    def _missing_(cls, value: object) -> t.Any:
+        if isinstance(value, bool) or not isinstance(value, int):
+            return None
+        member = int.__new__(cls, value)
+        member._name_ = str(value)
+        member._value_ = value
+        return member
+
+    @property
+    def is_known(self) -> bool:
+        """Whether the value is one of those declared by the API spec."""
+        return self._value_ in type(self)._value2member_map_
+
+
+@dataclasses.dataclass(frozen=True)
+class UnknownVariant:
+    """A union variant this SDK version does not know, kept as received."""
+
+    tag: str
+    """The discriminator value."""
+    data: t.Mapping[str, t.Any]
+    """The raw JSON object, which serializes back unchanged."""
+
+
+class Discriminator:
+    """Annotation metadata of a union of models told apart by one property.
+
+    ``Annotated[Circle | Square | UnknownVariant, Discriminator("type", ...)]``
+    decodes into the model its ``type`` names, and writes that name back when
+    the model is serialized.
+    """
+
+    def __init__(self, property: str, mapping: t.Mapping[str, type[BaseModel]]) -> None:
+        self.property = property
+        self.mapping = dict(mapping)
+        self.tags = {model: tag for tag, model in self.mapping.items()}
+
+    def parse(self, value: t.Any, ctx: str) -> t.Any:
+        if not isinstance(value, t.Mapping):
+            raise ModelParseError(
+                f"{ctx}: expected an object, got {type(value).__name__}"
+            )
+        tag = value.get(self.property)
+        if not isinstance(tag, str):
+            raise ModelParseError(f"{ctx}: missing discriminator {self.property!r}")
+        model = self.mapping.get(tag)
+        if model is None:
+            return UnknownVariant(tag, dict(value))
+        variant = model.from_dict(value)
+        # The tag is written back on serialization, from the variant's type.
+        variant.__dict__.get("_extra", {}).pop(self.property, None)
+        return variant
+
+    def serialize(self, value: t.Any) -> t.Any:
+        data = to_json_value(value)
+        tag = self.tags.get(type(value))
+        if tag is not None and isinstance(data, dict):
+            data[self.property] = tag
+        return data
+
+
+# --------------------------------------------------------------------------
+# Serialization
+# --------------------------------------------------------------------------
+
+_NoneType = type(None)
+_UNION_TYPES: tuple[t.Any, ...] = (t.Union, types.UnionType)
+
+
+def to_json_value(value: t.Any, annotation: t.Any = t.Any) -> t.Any:
+    """Convert ``value`` into something ``json.dumps`` understands.
+
+    ``annotation`` is the declared type of ``value``; it only matters for
+    unions of models whose variants do not carry their own discriminator.
+    """
+    origin = t.get_origin(annotation)
+    if origin is t.Annotated:
+        base, *metadata = t.get_args(annotation)
+        for meta in metadata:
+            if isinstance(meta, Discriminator) and value is not None:
+                return meta.serialize(value)
+        return to_json_value(value, base)
+    if origin in _UNION_TYPES:
+        members = [a for a in t.get_args(annotation) if a not in (_NoneType, Unset)]
+        if len(members) == 1:
+            return to_json_value(value, members[0])
+        return to_json_value(value, _union_member(members, value) or t.Any)
+    if isinstance(value, enum.Enum):
+        return to_json_value(value.value)
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, BaseModel):
+        return value.to_dict()
+    if isinstance(value, UnknownVariant):
+        return dict(value.data)
+    if isinstance(value, Decimal):
+        return format_decimal(value)
+    if isinstance(value, _datetime.datetime):
+        return format_datetime(value)
+    if isinstance(value, _datetime.date):
+        return value.isoformat()
+    if isinstance(value, _uuid.UUID):
+        return str(value)
+    args = t.get_args(annotation)
+    if isinstance(value, (list, tuple, set, frozenset)):
+        inner = args[0] if origin in (list, set, frozenset) and args else t.Any
+        return [to_json_value(v, inner) for v in value]
+    if isinstance(value, t.Mapping):
+        inner = args[1] if origin is dict and len(args) == 2 else t.Any
+        return {str(k): to_json_value(v, inner) for k, v in value.items()}
+    return value
+
+
+def format_decimal(value: Decimal) -> str:
+    """Render a decimal as its JSON string form.
+
+    Raises :class:`ValueError` for ``NaN`` and infinities, which the API does
+    not accept and no other Hyperfluid SDK can represent.
+    """
+    if not value.is_finite():
+        raise ValueError(f"cannot serialize non-finite decimal {value!r}")
+    return str(value)
+
+
+def parse_decimal(value: t.Any) -> Decimal:
+    """Parse a ``format: decimal`` JSON value into a finite :class:`Decimal`.
+
+    The API sends decimals as JSON strings (``"12.50"``, ``"1e3"``). JSON
+    numbers are rejected, since they may already have lost precision, and so
+    are ``NaN``/``Infinity``, which are not decimals the API can produce.
+    """
+    if not isinstance(value, str):
+        raise ModelParseError(f"expected a decimal string, got {value!r}")
+    try:
+        parsed = Decimal(value)
+    except ArithmeticError as exc:  # `decimal.InvalidOperation`
+        raise ModelParseError(f"invalid decimal {value!r}") from exc
+    if not parsed.is_finite():
+        raise ModelParseError(f"non-finite decimal {value!r}")
+    return parsed
+
+
+def format_datetime(value: _datetime.datetime) -> str:
+    """Render a datetime as an RFC 3339 string (naive values are treated as UTC)."""
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=_datetime.timezone.utc)
+    return value.isoformat()
+
+
+_FRACTION_RE = re.compile(r"(?<=[Tt ]\d\d:\d\d:\d\d)\.(\d+)")
+
+
+def _normalize_fraction(match: re.Match[str]) -> str:
+    return "." + match.group(1)[:6].ljust(6, "0")
+
+
+def parse_datetime(value: t.Any) -> _datetime.datetime:
+    """Parse an ISO 8601 / RFC 3339 string into an aware :class:`datetime.datetime`.
+
+    A string without a UTC offset (``2026-09-19T10:00:00.123456``) is read as
+    UTC; one with an explicit offset (``Z``, ``+02:00``) keeps it. Fractional
+    seconds may have 1 to 9 digits: they are truncated to microseconds, the
+    precision of :class:`datetime.datetime`.
+    """
+    if isinstance(value, _datetime.datetime):
+        parsed = value
+    elif isinstance(value, str):
+        text = value
+        # `fromisoformat` only learned about the `Z` suffix in Python 3.11.
+        if text.endswith(("Z", "z")):
+            text = text[:-1] + "+00:00"
+        # Before Python 3.11, `fromisoformat` only accepts exactly 3 or 6
+        # fractional digits, while servers send anywhere from 1 to 9.
+        text = _FRACTION_RE.sub(_normalize_fraction, text, count=1)
+        try:
+            parsed = _datetime.datetime.fromisoformat(text)
+        except ValueError as exc:
+            raise ModelParseError(f"invalid date-time string {value!r}") from exc
+    else:
+        raise ModelParseError(
+            f"expected a date-time string, got {type(value).__name__}"
+        )
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=_datetime.timezone.utc)
+    return parsed
+
+
+# --------------------------------------------------------------------------
+# Deserialization
+# --------------------------------------------------------------------------
+
+_hints_cache: dict[type, dict[str, t.Any]] = {}
+_known_keys_cache: dict[type, frozenset[str] | None] = {}
+
+
+def _type_hints(cls: type) -> dict[str, t.Any]:
+    """Resolve the annotations of a model.
+
+    Models import each other only for type checkers, which keeps recursive
+    schemas importable, so their names are looked up in the models package.
+    """
+    hints = _hints_cache.get(cls)
+    if hints is None:
+        hints = t.get_type_hints(cls, localns=_namespace(cls), include_extras=True)
+        _hints_cache[cls] = hints
+    return hints
+
+
+class _Namespace(dict[str, t.Any]):
+    """The names of a model's module, then the models, each imported when first looked up."""
+
+    def __missing__(self, name: str) -> t.Any:
+        if __package__:
+            models = importlib.import_module(".models", __package__)
+            if name in models._MODULES:
+                value = getattr(models, name)
+                self[name] = value
+                return value
+        raise KeyError(name)
+
+
+_namespaces: dict[str, _Namespace] = {}
+
+
+def _namespace(cls: type) -> _Namespace:
+    namespace = _namespaces.get(cls.__module__)
+    if namespace is None:
+        namespace = _Namespace(vars(sys.modules[cls.__module__]))
+        _namespaces[cls.__module__] = namespace
+    return namespace
+
+
+def from_json_value(annotation: t.Any, value: t.Any) -> t.Any:
+    """Build a value of type ``annotation`` from decoded JSON."""
+    return _from_json_value(annotation, value, getattr(annotation, "__name__", "value"))
+
+
+def _from_json_value(annotation: t.Any, value: t.Any, ctx: str) -> t.Any:
+    if annotation is t.Any or annotation is None or annotation is _NoneType:
+        return value
+
+    origin = t.get_origin(annotation)
+    args = t.get_args(annotation)
+
+    if origin is t.Annotated:
+        for meta in args[1:]:
+            if isinstance(meta, Discriminator):
+                return meta.parse(value, ctx)
+        return _from_json_value(args[0], value, ctx)
+
+    if origin in _UNION_TYPES:
+        if value is None and _NoneType in args:
+            return None
+        members = [a for a in args if a not in (_NoneType, Unset)]
+        if len(members) == 1:
+            return _from_json_value(members[0], value, ctx)
+        candidates = _union_candidates(members, _value_kind(value))
+        if not candidates:
+            raise ModelParseError(
+                f"{ctx}: {value!r} matches no member of {annotation!r}"
+            )
+        # Members sharing a JSON type (`str | list[str] | list[int]`, `datetime | str`) are tried
+        # in order: the first that decodes the value wins.
+        failure: ModelParseError | None = None
+        for member in candidates:
+            if t.get_origin(member) is t.Literal and value not in t.get_args(member):
+                continue
+            try:
+                return _from_json_value(member, value, ctx)
+            except ModelParseError as exc:
+                failure = exc
+        raise failure or ModelParseError(
+            f"{ctx}: {value!r} matches no member of {annotation!r}"
+        )
+
+    if origin in (list, set, frozenset, tuple):
+        inner = args[0] if args else t.Any
+        if not isinstance(value, list):
+            raise ModelParseError(f"{ctx}: expected a list, got {type(value).__name__}")
+        items = [_from_json_value(inner, v, f"{ctx}[{i}]") for i, v in enumerate(value)]
+        return set(items) if origin in (set, frozenset) else items
+
+    if origin is dict:
+        inner = args[1] if len(args) == 2 else t.Any
+        if not isinstance(value, dict):
+            raise ModelParseError(
+                f"{ctx}: expected an object, got {type(value).__name__}"
+            )
+        return {
+            str(k): _from_json_value(inner, v, f"{ctx}.{k}") for k, v in value.items()
+        }
+
+    if origin is t.Literal:
+        return value
+
+    if isinstance(annotation, type):
+        if issubclass(annotation, BaseModel):
+            if not isinstance(value, dict):
+                raise ModelParseError(
+                    f"{ctx}: expected an object, got {type(value).__name__}"
+                )
+            return annotation.from_dict(value)
+        if issubclass(annotation, enum.Enum):
+            try:
+                return annotation(value)
+            except ValueError as exc:
+                raise ModelParseError(f"{ctx}: invalid value {value!r}") from exc
+        if annotation is _datetime.datetime:
+            return parse_datetime(value)
+        if annotation is _datetime.date:
+            if isinstance(value, _datetime.date):
+                return value
+            try:
+                return _datetime.date.fromisoformat(str(value))
+            except ValueError as exc:
+                raise ModelParseError(f"{ctx}: invalid date {value!r}") from exc
+        if annotation is _uuid.UUID:
+            if isinstance(value, _uuid.UUID):
+                return value
+            try:
+                return _uuid.UUID(str(value))
+            except ValueError as exc:
+                raise ModelParseError(f"{ctx}: invalid UUID {value!r}") from exc
+        if annotation is Decimal:
+            try:
+                return parse_decimal(value)
+            except ModelParseError as exc:
+                raise ModelParseError(f"{ctx}: {exc}") from exc
+        if annotation is bool:
+            if not isinstance(value, bool):
+                raise ModelParseError(f"{ctx}: expected a boolean, got {value!r}")
+            return value
+        if annotation is float:
+            if isinstance(value, bool) or not isinstance(value, (int, float)):
+                raise ModelParseError(f"{ctx}: expected a number, got {value!r}")
+            return float(value)
+        if annotation is int:
+            if isinstance(value, bool) or not isinstance(value, int):
+                raise ModelParseError(f"{ctx}: expected an integer, got {value!r}")
+            return value
+        if annotation is str:
+            if not isinstance(value, str):
+                raise ModelParseError(f"{ctx}: expected a string, got {value!r}")
+            return value
+
+    return value
+
+
+_STRING_TYPES = (str, _datetime.datetime, _datetime.date, _uuid.UUID, Decimal)
+
+
+def _json_kind(annotation: t.Any) -> str | None:
+    """The JSON type of the values of ``annotation``, ``None`` when it takes any."""
+    origin = t.get_origin(annotation)
+    if origin is t.Annotated:
+        base, *metadata = t.get_args(annotation)
+        if any(isinstance(meta, Discriminator) for meta in metadata):
+            return "object"
+        return _json_kind(base)
+    if origin is t.Literal:
+        return _value_kind(t.get_args(annotation)[0])
+    if origin in (list, set, frozenset, tuple):
+        return "array"
+    if origin is dict:
+        return "object"
+    if isinstance(annotation, type):
+        if issubclass(annotation, bool):
+            return "boolean"
+        if issubclass(annotation, (int, float)):
+            return "number"
+        if issubclass(annotation, _STRING_TYPES):
+            return "string"
+        if issubclass(annotation, BaseModel):
+            return "object"
+    return None
+
+
+def _value_kind(value: t.Any) -> str | None:
+    if isinstance(value, bool):
+        return "boolean"
+    if isinstance(value, (int, float)):
+        return "number"
+    if isinstance(value, _STRING_TYPES):
+        return "string"
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return "array"
+    if isinstance(value, (t.Mapping, BaseModel, UnknownVariant)):
+        return "object"
+    return None
+
+
+def _union_candidates(members: list[t.Any], kind: str | None) -> list[t.Any]:
+    """The members of an untagged union whose JSON type is ``kind``, in declaration order.
+
+    The members that take any JSON value come last, as a fallback.
+    """
+    exact: list[t.Any] = []
+    fallback: list[t.Any] = []
+    for member in members:
+        member_kind = _json_kind(member)
+        if member_kind == kind:
+            exact.append(member)
+        elif member_kind is None:
+            fallback.append(member)
+    return exact + fallback
+
+
+def _fits(annotation: t.Any, value: t.Any) -> bool:
+    """Whether ``value``, a value held by the caller, is of ``annotation``, looking at the
+    first item of a list: how members sharing a JSON type are told apart."""
+    origin = t.get_origin(annotation)
+    args = t.get_args(annotation)
+    if annotation is t.Any:
+        return True
+    if origin is t.Annotated:
+        return _fits(args[0], value)
+    if origin in _UNION_TYPES:
+        return any(_fits(a, value) for a in args)
+    if origin is t.Literal:
+        return value in args
+    if origin in (list, set, frozenset, tuple):
+        if not isinstance(value, (list, tuple, set, frozenset)):
+            return False
+        first = next(iter(value), None)
+        return first is None or not args or _fits(args[0], first)
+    if origin is dict:
+        return isinstance(value, (t.Mapping, BaseModel))
+    if isinstance(annotation, type):
+        if annotation is float:
+            return isinstance(value, (int, float)) and not isinstance(value, bool)
+        if annotation is int:
+            return isinstance(value, int) and not isinstance(value, bool)
+        return isinstance(value, annotation)
+    return True
+
+
+def _union_member(members: list[t.Any], value: t.Any) -> t.Any:
+    """The member of an untagged union that ``value``, held by the caller, is an instance of."""
+    candidates = _union_candidates(members, _value_kind(value))
+    for member in candidates:
+        if _fits(member, value):
+            return member
+    return candidates[0] if candidates else None
+
+
+# --------------------------------------------------------------------------
+# Base classes
+# --------------------------------------------------------------------------
+
+
+def _has_default(field: dataclasses.Field[t.Any]) -> bool:
+    return (
+        field.default is not dataclasses.MISSING
+        or field.default_factory is not dataclasses.MISSING
+    )
+
+
+@dataclasses.dataclass
+class BaseModel:
+    """Base class of every generated model."""
+
+    #: Maps python attribute names onto their JSON key, when they differ.
+    _JSON_KEYS: t.ClassVar[t.Mapping[str, str]] = {}
+    #: Attribute names whose (model) value is merged into the parent object.
+    _FLATTENED: t.ClassVar[tuple[str, ...]] = ()
+    # A model whose schema types its `additionalProperties` declares the annotation of
+    # `extra_fields` as `_EXTRA_FIELDS: t.ClassVar[dict[str, Value]]`, without a value.
+
+    @classmethod
+    def _json_key(cls, name: str) -> str:
+        return cls._JSON_KEYS.get(name, name)
+
+    @classmethod
+    def _extra_type(cls) -> t.Any:
+        """The annotation of :attr:`extra_fields`, ``t.Any`` when the schema does not type it."""
+        hint = _type_hints(cls).get("_EXTRA_FIELDS", t.Any)
+        if t.get_origin(hint) is t.ClassVar:
+            args = t.get_args(hint)
+            hint = args[0] if args else t.Any
+        return hint
+
+    @property
+    def extra_fields(self) -> dict[str, t.Any]:
+        """JSON properties this SDK version does not know, as received.
+
+        They are sent back with the model; add entries to send properties the
+        SDK does not declare yet.
+        """
+        extra: dict[str, t.Any] | None = self.__dict__.get("_extra")
+        if extra is None:
+            extra = self.__dict__["_extra"] = {}
+        return extra
+
+    if not t.TYPE_CHECKING:
+
+        def __getattr__(self, name: str) -> t.Any:
+            extra = self.__dict__.get("_extra")
+            if extra is not None and name in extra and not name.startswith("__"):
+                return extra[name]
+            raise AttributeError(
+                f"{type(self).__name__!r} object has no attribute {name!r}"
+            )
+
+    @classmethod
+    def _known_keys(cls) -> frozenset[str] | None:
+        """The JSON keys of the fields and of flattened models, ``None`` when unbounded."""
+        if cls not in _known_keys_cache:
+            _known_keys_cache[cls] = cls._field_keys()
+        return _known_keys_cache[cls]
+
+    @classmethod
+    def _field_keys(cls) -> frozenset[str] | None:
+        keys: set[str] = set()
+        hints = _type_hints(cls)
+        for field in dataclasses.fields(cls):
+            if field.name not in cls._FLATTENED:
+                keys.add(cls._json_key(field.name))
+                continue
+            model = _model_of(hints.get(field.name))
+            inner = None if model is None else model._known_keys()
+            if inner is None:
+                return None
+            keys |= inner
+        return frozenset(keys)
+
+    def _keep_extra(
+        self,
+        data: t.Mapping[str, t.Any],
+        known: frozenset[str] | None,
+        decoded: bool = False,
+    ) -> None:
+        """Keeps the keys of ``data`` outside ``known``, decoded unless ``decoded`` already."""
+        extra = {k: v for k, v in data.items() if known is not None and k not in known}
+        annotation = type(self)._extra_type()
+        if extra and not decoded and annotation is not t.Any:
+            ctx = f"{type(self).__name__}.extra_fields"
+            extra = dict(_from_json_value(annotation, extra, ctx))
+        if extra or "_extra" in self.__dict__:
+            self.__dict__["_extra"] = extra
+
+    def _keep_nulls(self, data: t.Mapping[str, t.Any]) -> None:
+        """Remembers the optional fields received as ``null``, which ``None`` otherwise leaves out."""
+        nulls = {
+            field.name
+            for field in dataclasses.fields(self)
+            if field.default is None
+            and field.name not in self._FLATTENED
+            and data.get(self._json_key(field.name), UNSET) is None
+        }
+        if nulls:
+            self.__dict__["_nulls"] = nulls
+
+    def _with_extra(self, out: dict[str, t.Any]) -> dict[str, t.Any]:
+        extra: dict[str, t.Any] = self.__dict__.get("_extra") or {}
+        if extra:
+            # Entries may hold models, enums or datetimes, set by the caller or typed by
+            # `additionalProperties`.
+            extra = to_json_value(extra, type(self)._extra_type())
+        for key, value in extra.items():
+            out.setdefault(key, value)
+        return out
+
+    def _field_value(self, name: str) -> t.Any:
+        """The value of the field ``name``, which a page reads from its body when it shadows it."""
+        return getattr(self, name)
+
+    def _fields_to_dict(self, skip: t.Container[str] = ()) -> dict[str, t.Any]:
+        out: dict[str, t.Any] = {}
+        hints = _type_hints(type(self))
+        nulls: t.Container[str] = self.__dict__.get("_nulls", ())
+        for field in dataclasses.fields(self):
+            if field.name in skip:
+                continue
+            value = self._field_value(field.name)
+            # `None` leaves out an optional field defaulting to `None` rather than UNSET,
+            # unless it was received as `null`.
+            if value is UNSET or (
+                value is None and field.default is None and field.name not in nulls
+            ):
+                continue
+            data = to_json_value(value, hints.get(field.name, t.Any))
+            if field.name in self._FLATTENED:
+                if not isinstance(data, dict):
+                    raise TypeError(
+                        f"{type(self).__name__}.{field.name} must serialize to an object"
+                    )
+                out.update(data)
+            else:
+                out[self._json_key(field.name)] = data
+        return out
+
+    @classmethod
+    def _fields_from_dict(
+        cls, data: t.Mapping[str, t.Any], skip: t.Container[str] = ()
+    ) -> dict[str, t.Any]:
+        hints = _type_hints(cls)
+        kwargs: dict[str, t.Any] = {}
+        for field in dataclasses.fields(cls):
+            if field.name in skip:
+                continue
+            annotation = hints.get(field.name, t.Any)
+            ctx = f"{cls.__name__}.{field.name}"
+            if field.name in cls._FLATTENED:
+                kwargs[field.name] = _from_json_value(annotation, data, ctx)
+                if isinstance(kwargs[field.name], BaseModel):
+                    kwargs[field.name]._keep_extra({}, None)
+                continue
+            key = cls._json_key(field.name)
+            if key in data:
+                kwargs[field.name] = _from_json_value(annotation, data[key], ctx)
+            elif not _has_default(field):
+                if not _accepts_none(annotation):
+                    raise ModelParseError(
+                        f"{cls.__name__}: missing required field {key!r}"
+                    )
+                kwargs[field.name] = None
+        return kwargs
+
+    def to_dict(self) -> dict[str, t.Any]:
+        """Serialize into a JSON-compatible dict, with :attr:`extra_fields`."""
+        return self._with_extra(self._fields_to_dict())
+
+    def to_json(self) -> str:
+        """Serialize into a JSON string."""
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_dict(cls: type[_M], data: t.Mapping[str, t.Any]) -> _M:
+        """Build a model from a decoded JSON object, unknown keys in :attr:`extra_fields`."""
+        if not isinstance(data, t.Mapping):
+            raise ModelParseError(
+                f"{cls.__name__}: expected an object, got {type(data).__name__}"
+            )
+        model = cls(**cls._fields_from_dict(data))
+        model._keep_extra(data, cls._known_keys())
+        model._keep_nulls(data)
+        return model
+
+    @classmethod
+    def from_json(cls: type[_M], data: str | bytes) -> _M:
+        """Build a model from a JSON string."""
+        return cls.from_dict(json.loads(data))
+
+
+def _model_of(annotation: t.Any) -> type[BaseModel] | None:
+    """The model class of an annotation such as ``Address`` or ``Address | None``."""
+    if t.get_origin(annotation) in _UNION_TYPES:
+        members = [a for a in t.get_args(annotation) if a not in (_NoneType, Unset)]
+        annotation = members[0] if len(members) == 1 else None
+    if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        return annotation
+    return None
+
+
+def _accepts_none(annotation: t.Any) -> bool:
+    if t.get_origin(annotation) is t.Annotated:
+        annotation = t.get_args(annotation)[0]
+    return annotation is t.Any or (
+        t.get_origin(annotation) in _UNION_TYPES and _NoneType in t.get_args(annotation)
+    )
+
+
+@dataclasses.dataclass
+class TaggedUnionModel(BaseModel):
+    """Base class for discriminated unions (``oneOf`` with a discriminator).
+
+    Subclasses declare the discriminator (a ``Literal`` of the variant names),
+    the content (a union of the variant models, plus :class:`UnknownVariant`
+    for variants added to the API later) and any property shared by all
+    variants.
+    """
+
+    #: JSON key holding the variant name.
+    _DISCRIMINATOR: t.ClassVar[str] = ""
+    #: Attribute holding the discriminator value.
+    _DISCRIMINATOR_ATTR: t.ClassVar[str] = ""
+    #: Attribute holding the variant payload.
+    _CONTENT_ATTR: t.ClassVar[str] = ""
+    #: JSON key holding the variant payload; ``None`` when internally tagged
+    #: (i.e. the payload's fields sit next to the discriminator).
+    _CONTENT_KEY: t.ClassVar[str | None] = None
+    #: Variant name -> model name in the models package (``None`` for
+    #: variants without a payload).
+    _VARIANTS: t.ClassVar[t.Mapping[str, str | None]] = {}
+
+    @classmethod
+    def _variant(cls, tag: str) -> type[BaseModel] | None:
+        variant = cls._VARIANTS[tag]
+        if variant is None:
+            return None
+        model: type[BaseModel] = _namespace(cls)[variant]
+        return model
+
+    def __post_init__(self) -> None:
+        if getattr(self, self._DISCRIMINATOR_ATTR) is None:
+            setattr(
+                self,
+                self._DISCRIMINATOR_ATTR,
+                self._tag_of(getattr(self, self._CONTENT_ATTR)),
+            )
+
+    @classmethod
+    def _tag_of(cls, content: t.Any) -> str:
+        if isinstance(content, UnknownVariant):
+            return content.tag
+        tags = [tag for tag in cls._VARIANTS if cls._variant(tag) is type(content)]
+        if len(tags) != 1:
+            raise TypeError(
+                f"{cls.__name__}: pass {cls._DISCRIMINATOR_ATTR}=, it cannot be told"
+                f" from a {type(content).__name__} content"
+            )
+        return tags[0]
+
+    def to_dict(self) -> dict[str, t.Any]:
+        tag = getattr(self, self._DISCRIMINATOR_ATTR)
+        content = getattr(self, self._CONTENT_ATTR)
+        if tag not in self._VARIANTS and not isinstance(content, UnknownVariant):
+            raise ValueError(f"{type(self).__name__}: unknown variant {tag!r}")
+        out = self._fields_to_dict(skip=(self._DISCRIMINATOR_ATTR, self._CONTENT_ATTR))
+        serialized = to_json_value(content)
+        if self._CONTENT_KEY is not None and content is not None:
+            out[self._CONTENT_KEY] = serialized
+        elif isinstance(serialized, dict):
+            out.update(serialized)
+        elif content is not None:
+            raise TypeError(
+                f"{type(self).__name__}: variant {tag!r} must serialize to an object"
+            )
+        out[self._DISCRIMINATOR] = tag
+        return self._with_extra(out)
+
+    @classmethod
+    def _field_keys(cls) -> frozenset[str] | None:
+        keys = super()._field_keys()
+        if keys is None:
+            return None
+        content = set() if cls._CONTENT_KEY is None else {cls._CONTENT_KEY}
+        return keys - {cls._json_key(cls._CONTENT_ATTR)} | {
+            cls._DISCRIMINATOR,
+            *content,
+        }
+
+    @classmethod
+    def from_dict(cls: type[_M], data: t.Mapping[str, t.Any]) -> _M:
+        if not isinstance(data, t.Mapping):
+            raise ModelParseError(
+                f"{cls.__name__}: expected an object, got {type(data).__name__}"
+            )
+        union = t.cast("type[TaggedUnionModel]", cls)
+        tag = data.get(union._DISCRIMINATOR)
+        if not isinstance(tag, str):
+            raise ModelParseError(
+                f"{cls.__name__}: missing discriminator {union._DISCRIMINATOR!r}"
+            )
+        payload: t.Any = (
+            data if union._CONTENT_KEY is None else data.get(union._CONTENT_KEY, {})
+        )
+        if not isinstance(payload, t.Mapping):
+            raise ModelParseError(
+                f"{cls.__name__}: variant {tag!r} payload must be an object"
+            )
+        content: t.Any
+        if tag not in union._VARIANTS:
+            content = UnknownVariant(tag, dict(payload))
+        else:
+            variant = union._variant(tag)
+            content = None if variant is None else variant.from_dict(payload)
+        skip = (union._DISCRIMINATOR_ATTR, union._CONTENT_ATTR)
+        kwargs = union._fields_from_dict(data, skip=skip)
+        kwargs[union._DISCRIMINATOR_ATTR] = tag
+        kwargs[union._CONTENT_ATTR] = content
+        model = cls(**kwargs)
+        model._keep_nulls(data)
+        known = union._known_keys()
+        if union._CONTENT_KEY is not None:
+            model._keep_extra(data, known)
+        elif isinstance(content, BaseModel) and known is not None:
+            content._keep_extra(
+                content.__dict__.get("_extra") or {}, known, decoded=True
+            )
+        return model