cliV1 0.0.8__py3-none-any.whl

swagger_petstore_open_api_3_0/core/models.py

@@ -0,0 +1,143 @@
+"""The base model every domain model subclasses."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict
+
+from .optionality import strip_unset
+
+
+class SdkBaseModel(BaseModel):
+    """Base class for every domain model.
+
+    Immutable (``frozen``), **preserves** unknown JSON fields rather than dropping
+    them (``extra="allow"``), accepts either the Python field name or its wire alias
+    on input, and serializes declared fields back under the wire alias. Attribute
+    docstrings on fields are lifted into their schema ``description``.
+
+    A field the server adds after this SDK was generated survives on the instance --
+    readable via ``model_extra``, or by attribute access unless the key collides with
+    the model API -- and is re-emitted under the key it arrived with, at every nesting
+    level. Preservation is deliberately symmetric: an unknown key a caller supplies is
+    likewise sent, so a model received from the server can be echoed back without
+    silently discarding server-side state. See
+    ``docs/designs/unknown-field-preservation.md``.
+
+    ``frozen`` blocks rebinding an attribute; it does not deep-freeze values. The
+    contents of a ``list``/``dict`` field and the ``model_extra`` mapping remain
+    mutable in place.
+
+    :meth:`to_dict` and :meth:`to_json` are the ergonomic front door to serialization;
+    ``model_dump``/``model_dump_json`` remain available for the full option set. See
+    ``docs/designs/model-serialization-helpers.md``."""
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="allow",
+        validate_by_name=True,
+        validate_by_alias=True,
+        serialize_by_alias=True,
+        use_attribute_docstrings=True,
+    )
+
+    def to_dict(
+        self,
+        *,
+        mode: Literal["json", "python"] = "json",
+        by_alias: bool = True,
+        exclude_unset: bool = False,
+        exclude_defaults: bool = False,
+        exclude_none: bool = False,
+    ) -> dict[str, Any]:
+        """Return this model as a dictionary in the shape the API exchanges.
+
+        Defaults produce JSON-safe values under the wire alias of every field, so the
+        result is ``json.dumps``-able, equals ``json.loads(self.to_json())``, and
+        validates back into an equal model -- including through a discriminated-union
+        alias. Unknown fields the server sent are included (see
+        ``docs/designs/unknown-field-preservation.md``).
+
+        This is a convenience wrapper over ``model_dump``; reach for that directly when
+        you need the options this deliberately does not surface (``include``/``exclude``,
+        ``context``, ``round_trip``, ``warnings``, ``serialize_as_any``, ``fallback``).
+
+        A field typed ``OptionalNullable[...]`` (e.g. an omit-vs-null field) that the caller
+        never touched is always omitted here, even though plain ``model_dump`` shows it as
+        ``null`` -- this is the one documented exception to "exactly the underlying dump".
+        See ``docs/designs/optional-nullable-fields.md``.
+
+        Args:
+            mode: ``"json"`` coerces values to JSON-safe types (``datetime`` becomes a
+                string); ``"python"`` keeps the Python objects.
+            by_alias: Emit each field under its wire alias rather than its Python name.
+                The base config already serializes by alias, so this restates the
+                contract; pass ``False`` for Python-name keys.
+            exclude_unset: Omit fields that were never explicitly set, narrowing the
+                output to what the server actually sent. **Opt-in, not the default**:
+                a variant that pins its tag in its own schema carries it as a
+                *defaulted* field, so on a locally constructed model this drops the tag
+                and the result no longer validates against the union alias.
+            exclude_defaults: Omit fields still holding their default value.
+            exclude_none: Omit fields whose value is ``None``. The round-trip-safe way
+                to suppress nulls -- it keeps defaulted discriminators.
+
+        Returns:
+            The model's fields keyed by wire alias, plus any unknown fields it preserved."""
+        return strip_unset(
+            self,
+            self.model_dump(
+                mode=mode,
+                by_alias=by_alias,
+                exclude_unset=exclude_unset,
+                exclude_defaults=exclude_defaults,
+                exclude_none=exclude_none,
+            ),
+        )
+
+    def to_json(
+        self,
+        *,
+        indent: int | None = 2,
+        by_alias: bool = True,
+        exclude_unset: bool = False,
+        exclude_defaults: bool = False,
+        exclude_none: bool = False,
+    ) -> str:
+        """Return this model as a JSON string in the shape the API exchanges.
+
+        Indented by default for logs and debugging, and otherwise identical in content
+        to :meth:`to_dict` -- ``json.loads(self.to_json()) == self.to_dict()``.
+
+        This is a convenience wrapper over ``model_dump``/``model_dump_json``; reach for
+        those directly when you need the options this deliberately does not surface
+        (``include``/``exclude``, ``context``, ``round_trip``, ``warnings``,
+        ``ensure_ascii``, ``serialize_as_any``, ``fallback``).
+
+        Built on :meth:`to_dict` (rather than delegating to ``model_dump_json`` directly)
+        so the pair can never drift apart -- including the ``OptionalNullable`` omission
+        documented there.
+
+        Args:
+            indent: Spaces of indentation; ``None`` emits compact JSON.
+            by_alias: Emit each field under its wire alias rather than its Python name.
+            exclude_unset: Omit fields that were never explicitly set. Carries the same
+                discriminator caveat as :meth:`to_dict`.
+            exclude_defaults: Omit fields still holding their default value.
+            exclude_none: Omit fields whose value is ``None``.
+
+        Returns:
+            The JSON text the API exchanges, indented unless ``indent`` is ``None``."""
+        return json.dumps(
+            self.to_dict(
+                mode="json",
+                by_alias=by_alias,
+                exclude_unset=exclude_unset,
+                exclude_defaults=exclude_defaults,
+                exclude_none=exclude_none,
+            ),
+            indent=indent,
+            ensure_ascii=False,
+        )

swagger_petstore_open_api_3_0/core/optionality.py

@@ -0,0 +1,130 @@
+"""The unset sentinel and the states it enables: omitted vs ``null`` vs a value.
+
+:data:`UNSET` marks a field the caller never touched and :func:`strip_unset` is where "omitted" is
+recovered at dump time, by dropping any key whose live value is still the sentinel. Two annotations
+admit it, one per spelling a spec can declare: :data:`Optional` for a property that may be omitted,
+:data:`OptionalNullable` for one that may be omitted *or* explicitly ``null``. See
+``docs/designs/optional-nullable-fields.md``.
+
+:data:`Optional` is deliberately **not** ``typing.Optional``. Here it means ``T | UnsetType`` --
+present or absent, with no ``None`` arm -- where ``typing.Optional[T]`` means ``T | None``. They
+differ by exactly the arm that matters: a property the spec does not declare nullable must not be
+able to reach the wire as ``null``, so passing ``None`` to one of these fields is a type error
+rather than a value that serializes. Nothing in a generated SDK imports ``typing.Optional`` -- unions
+are spelled with PEP 604 ``|`` -- so the two never appear in the same module."""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar, Final, Literal, TypeVar, cast, final
+
+from pydantic import BaseModel, GetCoreSchemaHandler
+from pydantic_core import core_schema
+from typing_extensions import TypeAliasType
+
+
+@final
+class UnsetType:
+    """Marks a field the caller never touched, distinct from one set to ``None``.
+
+    Only ever seen as a field's default -- never constructed or passed by a caller. Dumps
+    as plain ``None`` through pydantic's normal fast path (see :func:`strip_unset` for
+    where the tri-state is actually recovered). See
+    ``docs/designs/optional-nullable-fields.md``.
+
+    A singleton, and identity-stable through every channel that could duplicate it: ``UnsetType()``
+    returns the existing instance, ``copy`` and ``deepcopy`` return it unchanged, and unpickling
+    reduces back through the constructor. Without that, ``model_copy(deep=True)`` would deep-copy
+    the sentinel into a *second* object, and ``field is UNSET`` -- the natural way to test for
+    it -- would start returning ``False`` on the copy. :func:`strip_unset` uses ``isinstance`` and
+    so is immune either way, but callers should not have to know that. ``final`` is the same
+    guarantee stated statically: a subclass would inherit ``_instance`` already set, so its
+    constructor would hand back a ``UnsetType`` rather than an instance of itself."""
+
+    _instance: ClassVar[UnsetType | None] = None
+
+    def __new__(cls) -> UnsetType:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __bool__(self) -> Literal[False]:
+        return False
+
+    def __repr__(self) -> str:
+        return "UNSET"
+
+    def __copy__(self) -> UnsetType:
+        return self
+
+    def __deepcopy__(self, memo: dict[int, Any]) -> UnsetType:
+        return self
+
+    def __reduce__(self) -> tuple[type[UnsetType], tuple[()]]:
+        # Protocols >= 2 reduce via ``cls.__new__(cls)`` and reach the guard above by luck of
+        # protocol; 0 and 1 reconstruct through ``copyreg._reconstructor``, which calls
+        # ``object.__new__`` and bypasses ``__new__`` entirely -- measured, ``restored is UNSET``
+        # was ``False`` at both. Reducing to a plain call makes every protocol uniform.
+        return (UnsetType, ())
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source_type: Any, handler: GetCoreSchemaHandler) -> core_schema.CoreSchema:
+        return core_schema.is_instance_schema(
+            cls, serialization=core_schema.plain_serializer_function_ser_schema(lambda _: None)
+        )
+
+
+UNSET: Final = UnsetType()
+
+T = TypeVar("T")
+Optional = TypeAliasType("Optional", T | UnsetType, type_params=(T,))
+OptionalNullable = TypeAliasType("OptionalNullable", T | None | UnsetType, type_params=(T,))
+
+DumpedT = TypeVar("DumpedT")
+
+
+def strip_unset(value: object, dumped: DumpedT) -> DumpedT:
+    """Recursively drop any dumped key whose live field value is :class:`UnsetType`.
+
+    Walks ``value`` (the validated model, list or dict, pre-dump) alongside ``dumped`` (its
+    ``mode="json"`` dump) so a field that dumped as ``None`` only because it defaulted to
+    ``UNSET`` is omitted, while one explicitly set to ``None`` stays ``null``.
+
+    The mapping branch pairs the two by *key* rather than by position, because ``mode="json"``
+    renders a non-``str`` key as text (``{1: "x"}`` dumps as ``{"1": "x"}``): an entry the dump
+    renamed keeps its dumped form instead of misaligning the walk. ``list`` and ``dict`` are the
+    whole container set on purpose -- an array and a map are what a spec can express, so they are
+    the only shapes an emitted declared type nests, and they are the same two ``adapters.py``
+    descends. A ``tuple`` or ``set`` passes through like any other value.
+
+    Shape-preserving: a dict in, a dict out; a list in, a list out. The three ``cast`` calls
+    are that invariant, which mypy cannot verify through the rebuild -- they keep the
+    imprecision here rather than returning ``Any`` to every caller.
+
+    Args:
+        value: The validated model, list or dict, before dumping -- the side that still
+            holds the sentinel.
+        dumped: That same value's ``mode="json"`` dump, walked alongside it.
+
+    Returns:
+        ``dumped`` with every never-touched key removed, in the shape it arrived in."""
+    if isinstance(value, BaseModel):
+        result = dict(cast(Any, dumped))
+        for name, field in type(value).model_fields.items():
+            # ``dumped`` may be keyed by wire alias (the default) or by Python name
+            # (``to_dict(by_alias=False)``); prefer whichever spelling is actually there.
+            key = field.alias if field.alias is not None and field.alias in result else name
+            if key not in result:
+                continue
+            attr = getattr(value, name)
+            if isinstance(attr, UnsetType):
+                del result[key]
+            else:
+                result[key] = strip_unset(attr, result[key])
+        return cast(DumpedT, result)
+    if isinstance(value, list) and isinstance(dumped, list):
+        stripped = [strip_unset(item, d) for item, d in zip(value, dumped, strict=True)]
+        return cast(DumpedT, stripped)
+    if isinstance(value, dict) and isinstance(dumped, dict):
+        stripped_values = {key: strip_unset(value[key], item) if key in value else item for key, item in dumped.items()}
+        return cast(DumpedT, stripped_values)
+    return dumped

swagger_petstore_open_api_3_0/core/params.py

@@ -0,0 +1,157 @@
+"""Request parameters and the unresolved URL they are attached to.
+
+A :class:`Param` is one query, header, path or form parameter: a key, the value the endpoint
+received, and the adapter for the type it was declared as. The declared type decides how the value
+reaches the wire -- a temporal alias carries its own serializer, so ``RFC1123DateTime`` and
+``UnixSecondsDateTime`` render the same ``datetime`` as a string and as an int -- and is what
+dict-shaped input is validated against. How a *collection* explodes into keys is the one choice a
+type cannot express, so it stays a field (:class:`SerializationFormat`)."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Final, Generic, TypeVar
+
+from pydantic import TypeAdapter
+from typing_extensions import TypeForm
+
+from ._internal.subscripts import SubscriptOnly
+from .adapters import adapter_for, validation_target
+
+T = TypeVar("T")
+
+
+class SerializationFormat(Enum):
+    """How a multi-valued *query or form* parameter explodes into keys.
+
+    Only those two destinations can honour it, because only they can repeat or subscript a key. A
+    path array folds into one comma-separated segment and a header array into one comma-separated
+    field value -- OpenAPI's default ``style: simple`` for both, and RFC 9110's own rule for a
+    repeated header -- so a path or header :class:`Param` carries this field and nothing reads it.
+    That is the price of one ``Param`` and one :func:`param` factory serving every location a
+    parameter can occupy, and it is a price rather than a defect: the alternative is a parameter
+    type per destination, and with it a generator branch deciding which to emit -- the conditional
+    emission ADR-0012 removed.
+
+    The remaining path and header styles -- ``label``, ``matrix``, ``explode: true`` -- are not
+    modelled, and cannot be from here: nothing below this module carries ``style`` or ``explode``,
+    so the default is the whole of what there is to render."""
+
+    INDEXED = "indexed"
+    """Example: variableName[0]=value1"""
+
+    UNINDEXED = "unindexed"
+    """Example: variableName[]=value1"""
+
+    PLAIN = "plain"
+    """Example: variableName=value1&variableName=value2"""
+
+    CSV = "csv"
+    """Example: variableName=value1,value2"""
+
+    TSV = "tsv"
+    r"""Example: variableName=value1\tvalue2"""
+
+    PSV = "psv"
+    """Example: variableName=value1|value2"""
+
+
+@dataclass(frozen=True, slots=True)
+class Param(Generic[T]):
+    """One request parameter, not yet flattened onto the wire.
+
+    ``T`` is the endpoint's declared type in full, dict-shaped companion included -- exactly what
+    ``param[...]`` accepts -- while the adapter targets :func:`validation_target` of it, which is
+    what the value is validated *into*. ``value`` is typed ``object`` all the same, deliberately:
+    every consumer holds a ``Param[Any]``, where a ``T``-typed field would read as ``Any`` and be
+    checked as nothing, so ``object`` leaves the adapter as the only route to the value. The
+    *resolved* adapter is held rather than the type expression it came from, so the one cache
+    lookup happens when the parameter is built rather than on every flatten.
+
+    Unlike a request body, a parameter is deliberately *not* serialized when it is built: query,
+    header and path parameters are merged per key with the API-wide ``global_*`` sets while the
+    request is being built, so they have to stay inspectable until then. ``wire_value``
+    (``_internal/wire.py``) performs the same validate-then-dump through this ``adapter`` at that
+    point, for every destination; each destination then decides only how the result is arranged --
+    into query pairs, path segments, or one header value.
+
+    Construct it through ``param[...]``, whose subscript is where ``T`` is bound.
+
+    Two parameters compare equal when key, value and format match *and* they share an adapter.
+    Adapters are cached per type by :func:`adapter_for`, so that holds for any cacheable type; an
+    unhashable type form bypasses the cache and would make two otherwise-identical parameters
+    unequal. Nothing depends on it -- resolution keys on ``key`` alone."""
+
+    key: str
+    value: object
+    adapter: TypeAdapter[T]
+    serialization_format: SerializationFormat = SerializationFormat.INDEXED
+
+
+@dataclass(frozen=True, slots=True)
+class _DeclaredParam(Generic[T]):
+    """A parameter's declared type, bound to its adapter; call it with the key and value.
+
+    Built by ``param[T]``; resolving the adapter there is what lets the parameter hold a typed
+    ``TypeAdapter[T]``."""
+
+    adapter: TypeAdapter[T]
+
+    def __call__(
+        self,
+        key: str,
+        value: T,
+        *,
+        serialization_format: SerializationFormat = SerializationFormat.INDEXED,
+    ) -> Param[T]:
+        return Param(key, value, self.adapter, serialization_format)
+
+
+class _ParamFactory(SubscriptOnly):
+    """``param[T](key, value)`` -- name a parameter's declared type in the subscript.
+
+    Subscripted for the reason ``json_body`` documents in full: ``T`` is solved from the
+    subscript alone, before the value is compared against it, so ``param[bool]("array",
+    employee)`` is a build failure where a one-call ``param("array", employee, bool)`` would
+    have inference absorb the disagreement. And because the factory declares no ``__call__``,
+    *omitting* the declared type is a build failure too: ``param("array", True)`` is rejected
+    statically (``[operator]``); the runtime ``__call__`` inherited from :class:`SubscriptOnly` is
+    invisible to type checkers and exists only to turn that same mistake into a guided ``TypeError``.
+
+    The subscript is a ``TypeForm``, exactly as in ``json_body[...]``, so a runtime union alias
+    (``Person``, which is ``Employee | Boss``) binds ``T`` as precisely as a concrete class
+    does. It is the endpoint's declared type in full, companion included --
+    ``param[Person | PersonDict]`` -- and :func:`validation_target` keeps the companion out of
+    the adapter."""
+
+    factory_name = "param"
+    spelling = 'param[T](key, value), e.g. param[bool]("array", True)'
+
+    def __getitem__(self, declared: TypeForm[T]) -> _DeclaredParam[T]:
+        return _DeclaredParam(adapter_for(validation_target(declared)))
+
+
+param: Final = _ParamFactory()
+
+
+@dataclass(frozen=True, slots=True)
+class UrlTemplate:
+    """An unresolved endpoint URL.
+
+    Holds a (possibly templated) base URL, the endpoint-relative path, and the
+    server variables that fill the base URL's ``{placeholder}`` tokens. The base
+    URL and the path are expanded separately when the request is built.
+
+    A server variable is *configuration* rather than a spec-declared parameter --
+    it is resolved from ``ServerConfig`` before any request exists -- but it fills
+    a placeholder exactly as a path parameter does, so it is carried as a
+    :class:`Param` and rendered by the same function. Naming its declared type is
+    what retires the hand ``.value`` unwrap an enum-typed variable used to need,
+    and what makes forgetting one a type error rather than a base URL reading
+    ``Region.EU``."""
+
+    base_url: str
+    path: str
+    variables: Sequence[Param[Any]] = ()