cliV1 0.0.7__py3-none-any.whl

swagger_petstore_open_api_3_1_0/core/request_options.py

@@ -0,0 +1,172 @@
+"""Per-call request options -- the SDK's one override channel.
+
+Every endpoint takes an optional ``request_options``, so a caller can override request-scoped
+behaviour for a single call without re-configuring the client::
+
+    client.body_params.send_long(5, request_options={"timeout": 5.0})
+
+One bundled parameter rather than a keyword per knob. That is what keeps the set of names a
+generated endpoint reserves at exactly one, however many options are added later: a new option is a
+field here and collides with nobody's parameter.
+
+Accepted either typed or dict-shaped, the same either-spelling convention the model input companions
+use. :meth:`RequestOptions.coerce` is the one place the dict form is resolved, so the two spellings
+cannot produce different requests.
+
+A validated model rather than a plain frozen dataclass, because of who supplies the value: this is
+caller input, so its constraints and its unknown-key rejection are declared here rather than
+hand-written, exactly as they are for the configuration models. What the runtime *builds* --
+including the resolved timeout that reaches a transport on :class:`HttpRequest` -- stays a plain
+dataclass field, so no model crosses the transport boundary."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from collections.abc import Set as AbstractSet
+from typing import Final, TypeAlias
+
+from pydantic import BaseModel, ConfigDict, Field
+from typing_extensions import NotRequired, TypedDict
+
+from .retries import MaxRetries, RetryOptions
+
+
+class RequestOptions(BaseModel):
+    """Overrides that apply to a single request.
+
+    ``frozen`` matches every other value type in the runtime; ``extra="forbid"`` rejects a
+    misspelled option that reached here without a type checker having seen the call.
+
+    The retry terms are spelled **flat**, under the names :class:`~.retries.RetryOptions` gives them,
+    and each one **merges** onto the client's policy rather than replacing it
+    (:func:`apply_retry_overrides`, below): a field left ``None`` is a field the caller did not set,
+    and the client's value stands. So overriding one term costs one key -- ``{"max_retries": 0}``
+    turns retrying off for this call and moves nothing else -- where a nested policy obliged the
+    caller to restate every term they were happy with in order to change one.
+
+    Of the retry terms, only the two that vary by call site are here: how many times *this* call may
+    be retried, and which statuses count as transient for *this* endpoint. The wait curve --
+    ``initial_delay``, ``backoff_factor``, ``max_delay``, ``max_jitter`` -- describes how the server
+    recovers, a fact about the API rather than about one call, and ``http_methods_to_retry`` is fixed
+    by the method an endpoint was emitted with, so a per-call set could only agree with it or disable
+    this call's retrying by a second route. All five stay the client's alone.
+
+    ``log_level`` is the third per-call term: how loud *this* call may be, read where a call's log
+    scope is opened."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    timeout: float | None = Field(default=None, gt=0)
+    """Seconds to wait for this one request. ``None`` leaves the client's own timeout in force."""
+
+    extra_headers: Mapping[str, str] | None = None
+    """Headers added to this one request, winning over both the API's and the endpoint's own."""
+
+    max_retries: MaxRetries | None = None
+    """Retries after the initial attempt of this one request. ``0`` turns retrying off for it."""
+
+    status_codes_to_retry: AbstractSet[int] | None = None
+    """Statuses that qualify for a retry of this request, under the client's method gate."""
+
+    log_level: int | None = Field(default=None, ge=0)
+    """A floor for this one call's log records: a ``logging`` level. Records below it are not written;
+    records at or above it are written when the logger's own level and the client's flags allow them. It
+    silences, and never turns a dump or the body on. ``None`` leaves every event to the client's options."""
+
+    @classmethod
+    def coerce(cls, options: RequestOptionsOrDict | None) -> RequestOptions:
+        """Return ``options`` as a :class:`RequestOptions`, dict-shaped input included.
+
+        An instance passes straight through -- it validated itself when it was built -- and ``None``
+        yields the shared empty options rather than ``None`` itself, so the path every call that
+        overrides nothing takes neither validates nor allocates, and every read downstream stays
+        unconditional as fields are added.
+
+        Everything else is validated, an empty mapping and a falsy value of the wrong type included.
+        ``None`` is the only short circuit deliberately: a caller no type checker saw is exactly who
+        this validation is for, and absorbing their ``False`` or ``()`` as "no overrides" would
+        leave them believing an override took effect.
+
+        Args:
+            options: The caller's per-call overrides, in either spelling, or ``None`` for none.
+
+        Returns:
+            A validated :class:`RequestOptions`; the shared empty instance when ``options`` is
+            ``None``.
+
+        Raises:
+            ValidationError: If ``options`` carries an unknown key or an out-of-range value. It
+                subclasses ``ValueError``, so a caller catching that still covers this."""
+        if isinstance(options, cls):
+            return options
+        if options is None:
+            return _NO_OPTIONS
+        return cls.model_validate(options)
+
+
+class RequestOptionsDict(TypedDict):
+    """The dict-shaped spelling of :class:`RequestOptions`, mirroring it field for field.
+
+    Closed and typed per key, which is what makes ``request_options={"timeuot": 1}`` a type error at
+    the call site rather than a surprise at runtime."""
+
+    timeout: NotRequired[float | None]
+    extra_headers: NotRequired[Mapping[str, str] | None]
+    max_retries: NotRequired[int | None]
+    status_codes_to_retry: NotRequired[AbstractSet[int] | None]
+    log_level: NotRequired[int | None]
+
+
+RequestOptionsOrDict: TypeAlias = RequestOptions | RequestOptionsDict
+"""What an endpoint accepts: the typed options, or a dict carrying the same keys.
+
+Aliased rather than spelled out at each call site -- unlike a model and its companion, which a
+generator writes as a pair per schema, there is exactly one options type, so a single alias is what
+keeps every emitted signature on one line instead of four."""
+
+_NO_OPTIONS: Final = RequestOptions()
+"""The empty options, built once -- the default path for every call that overrides nothing."""
+
+
+def apply_retry_overrides(options: RequestOptions, retry_options: RetryOptions) -> RetryOptions:
+    """Return the client's policy with one call's retry overrides applied.
+
+    A function rather than a method, and not re-exported from ``core/__init__.py``: the two terms are
+    a caller's to *write*, but folding them onto a policy is the raw client's business, and nothing a
+    caller holds should offer it. The runtime's one caller is ``raw_client.execute``, once per
+    request, in both flavours.
+
+    The terms are a *layer over* ``retry_options``, never a policy of their own: each one the caller
+    set replaces the client's value for this request, and each left ``None`` leaves the client's
+    standing. ``None`` is therefore **unset rather than a value** -- the same reading ``timeout`` has,
+    and the reading the dict spelling requires, since an omitted key and ``{"max_retries": None}``
+    cannot be allowed to mean different things once the companion accepts both. The cost of that is
+    one thing a caller cannot say: there is no per-call way to put a field *back* to the policy's own
+    default, only to name the value they want.
+
+    The client's policy is copied rather than rebuilt, which is what keeps this merge correct as the
+    policy grows: a field this function has never heard of keeps the client's value instead of
+    silently falling back to its class default. It is copied rather than revalidated because the
+    overriding values were already validated against the very bounds ``RetryOptions`` declares --
+    both models name ``MaxRetries``, and a status set has no bound -- so there is nothing left to
+    re-check.
+
+    A call that overrode nothing gets the client's own instance back, unwrapped and unallocated; that
+    is the path every request takes.
+
+    Args:
+        options: The caller's per-call overrides, already coerced.
+        retry_options: The client's policy -- what governs every term this call is silent about.
+
+    Returns:
+        The client's policy where this call is silent and the caller's value at each field they set;
+        ``retry_options`` itself when they set none."""
+    overrides = {
+        name: value
+        for name, value in (
+            ("max_retries", options.max_retries),
+            ("status_codes_to_retry", options.status_codes_to_retry),
+        )
+        if value is not None
+    }
+    return retry_options.model_copy(update=overrides) if overrides else retry_options

swagger_petstore_open_api_3_1_0/core/results.py

@@ -0,0 +1,178 @@
+"""The result of one API call, as a value rather than an exception.
+
+``ApiResult`` is a tagged union: a call yields exactly one of :class:`Success` or :class:`Failure`,
+never both and never neither, so which one you hold is a fact the type checker can see. Narrow it
+with ``match`` or ``isinstance`` and the payload or error comes with it:
+
+    match client.body_params.with_raw_response.send_model(employee):
+        case Success(payload=confirmation):
+            ...
+        case Failure(error=err):
+            ...
+
+Both variants are frozen dataclasses, so pattern matching needs nothing added. To skip the branch,
+call ``unwrap(result)``: it returns the payload or raises ``ApiError``. It is a function, not a method, so
+the same name also covers paginators: ``unwrap(paginator, items_selector)`` returns a paginator of payloads.
+
+Each carries the response's **head** -- its status and headers -- as fields of its own rather than a
+response object. There is no body beside them: the body *is* the payload on a success, and on a
+failure it is the error, reachable through :class:`RawError` where the operation documents no schema
+for it. A no-content operation therefore cannot show a caller the body it discarded; reaching one
+deliberately is future work, and an empty ``content`` on a response object was the wrong way to
+advertise its absence.
+
+:class:`RawError` lives here too: it is the error type a :class:`Failure` carries when the operation
+does not document the status that came back."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable, Iterator, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Generic, NoReturn, TypeAlias, TypeVar, overload
+
+from ._internal.wire import parse_json
+from .exceptions import ApiError
+from .paginator import AsyncPaginator, Paginator
+
+T = TypeVar("T")
+E = TypeVar("E")
+ItemT = TypeVar("ItemT")
+
+
+@dataclass(frozen=True, slots=True)
+class Success(Generic[T]):
+    """A successful (2xx) API call carrying the decoded ``payload``."""
+
+    payload: T
+    status_code: int
+    headers: Mapping[str, str] = field(repr=False)
+    """Header names lowercased, per the transports' obligation -- look keys up in lowercase.
+
+    Kept out of the generated repr: a response's headers carry ``set-cookie``, so a result printed
+    in a log line or a debugger pane would otherwise hand over a session secret. The status stays,
+    because identifying the result is the whole job of the string form (ADR-0017)."""
+
+
+@dataclass(frozen=True, slots=True)
+class Failure(Generic[E]):
+    """A failed (non-2xx) API call carrying the decoded error body ``error``.
+
+    ``error`` is the typed error payload directly (a union of the operation's
+    documented schemas, or :class:`RawError` for an unmapped status) -- not a wrapper."""
+
+    error: E
+    status_code: int
+    headers: Mapping[str, str] = field(repr=False)
+    """Header names lowercased, per the transports' obligation -- look keys up in lowercase.
+
+    Kept out of the generated repr: a response's headers carry ``set-cookie``, so a result printed
+    in a log line or a debugger pane would otherwise hand over a session secret. The status stays,
+    because identifying the result is the whole job of the string form (ADR-0017)."""
+
+
+# One call returns exactly one of these. Narrow with ``match`` or ``isinstance``,
+# or get the payload with ``unwrap(result)``.
+ApiResult: TypeAlias = Success[T] | Failure[E]
+
+
+@dataclass(frozen=True, slots=True)
+class RawError:
+    """Undecoded fallback body (unmapped status / no declared schema).
+
+    Holds the status and the bytes themselves rather than a response, so the one object that *is*
+    the error carries everything it needs to describe itself. Decoded on demand --
+    ``RawError(status_code, content)``."""
+
+    status_code: int
+    content: bytes
+
+    def text(self, encoding: str = "utf-8") -> str:
+        """Decode the undecoded body as text, for a log line or a diagnostic.
+
+        Args:
+            encoding: Character encoding to decode with.
+
+        Returns:
+            The body as text, undecodable bytes replaced rather than raising."""
+        return self.content.decode(encoding, errors="replace")
+
+    def json(self) -> Any:
+        """Parse the undecoded body as JSON.
+
+        Returns:
+            Whatever the body parses to.
+
+        Raises:
+            ValueError: If the body is not valid JSON."""
+        return parse_json(self.content)
+
+    def __repr__(self) -> str:
+        # Identify by status only -- the (undecoded, possibly large, binary, or sensitive) body is
+        # deliberately kept out of the string form. Read it on demand via ``text``/``json``.
+        return f"{type(self).__name__}(status_code={self.status_code})"
+
+
+@overload
+def unwrap(result: Failure[E], /) -> NoReturn: ...
+
+
+@overload
+def unwrap(result: ApiResult[T, E], /) -> T: ...
+
+
+@overload
+def unwrap(
+    paginator: Paginator[ApiResult[T, E], ItemT], items_selector: Callable[[T], Sequence[ItemT]], /
+) -> Paginator[T, ItemT]: ...
+
+
+@overload
+def unwrap(
+    paginator: AsyncPaginator[ApiResult[T, E], ItemT], items_selector: Callable[[T], Sequence[ItemT]], /
+) -> AsyncPaginator[T, ItemT]: ...
+
+
+def unwrap(
+    value: ApiResult[T, E] | Paginator[ApiResult[T, E], ItemT] | AsyncPaginator[ApiResult[T, E], ItemT],
+    items_selector: Callable[[T], Sequence[ItemT]] | None = None,
+    /,
+) -> T | Paginator[T, ItemT] | AsyncPaginator[T, ItemT]:
+    """Return the parsed form of a raw value: a result's payload, or a paginator over payloads.
+
+    A ``Success`` returns its payload and a ``Failure`` raises. A paginator of ``ApiResult`` pages returns a
+    paginator of the same flavour over the payloads: earlier pages arrive, and the first failed page raises.
+    The raw paginator's own item selector is not used.
+
+    Args:
+        value: A result, or a paginator whose pages are results.
+        items_selector: Returns one payload's items, in order. Required with a paginator; omit it with a result.
+
+    Returns:
+        The payload, or a lazy paginator over payloads that can be iterated more than once.
+
+    Raises:
+        ApiError: For a ``Failure``, carrying its ``error`` and response head. For a paginator, raised while
+            iterating, at the first failed page.
+        TypeError: If the value is neither a result nor a paginator, or a paginator arrives without ``items_selector``.
+            The overloads reject both statically."""
+    match value, items_selector:
+        case Success(payload=payload), _:
+            return payload
+        case Failure(error=error, status_code=status_code, headers=headers), _:
+            raise ApiError(error=error, status_code=status_code, headers=headers)
+        case Paginator(), items if items is not None:
+
+            def fetch_pages() -> Iterator[T]:
+                for result in value.iter_pages():
+                    yield unwrap(result)
+
+            return Paginator(fetch_pages, items)
+        case AsyncPaginator(), items if items is not None:
+
+            async def async_fetch_pages() -> AsyncIterator[T]:
+                async for result in value.iter_pages():
+                    yield unwrap(result)
+
+            return AsyncPaginator(async_fetch_pages, items)
+        case _:
+            raise TypeError("the value cannot be unwrapped")

swagger_petstore_open_api_3_1_0/core/retries.py

@@ -0,0 +1,237 @@
+"""What to retry, how long to wait, and when to stop.
+
+Decisions only, never action: the loop that sleeps and sends again is ``raw_client.execute``, and
+this module is what it asks. That is what makes every rule here testable without a transport.
+
+A retry is safe only when two things hold, and both are answered here: the request may be repeated
+without knowing whether the server acted on it -- a method the caller nominated, failing in a way
+the policy names -- and its body can go out again byte for byte (:func:`is_retryable_body`)."""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Mapping
+from collections.abc import Set as AbstractSet
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from pathlib import Path
+from typing import Annotated, TypeAlias
+
+from pydantic import BaseModel, ConfigDict, Field
+from typing_extensions import NotRequired, TypedDict
+
+from ._internal.headers import find_header
+from .bodies import BinaryBody, FormBody, JsonBody, MultipartBody, MultipartFile, RequestBody, TextBody
+from .transport import HttpMethod
+
+# This policy's bounds, each declared once as an alias. ``MaxRetries`` is the one the per-call layer
+# shares: ``RequestOptions`` spells the same field as ``MaxRetries | None`` and the two must not be
+# able to drift, because the merge there copies a caller's value onto this policy *without*
+# revalidating it -- sound only while the bound that admitted the value is the bound governing the
+# field it lands on. A value out of range reaching the loop is not a rejected call but a malformed
+# one: a negative ``max_retries`` empties ``range(max_retries + 1)``, so ``execute`` sends nothing at
+# all. The four curve bounds are the client's alone and are aliased for uniformity;
+# ``status_codes_to_retry`` has no alias because it has no bound to single-source -- but it shares a
+# *type* the same way: ``AbstractSet[int]`` at both boundaries, stored by pydantic as a ``frozenset``,
+# so the copy lands a ``frozenset`` on a field that already holds one.
+MaxRetries: TypeAlias = Annotated[int, Field(ge=0)]
+InitialDelay: TypeAlias = Annotated[float, Field(gt=0)]
+BackoffFactor: TypeAlias = Annotated[float, Field(ge=1)]
+MaxDelay: TypeAlias = Annotated[float, Field(gt=0)]
+MaxJitter: TypeAlias = Annotated[float, Field(ge=0)]
+
+
+class RetryOptions(BaseModel):
+    """How many times to retry, how long to wait, and which failures qualify.
+
+    Caller input, so its constraints are declared rather than hand-written, exactly as they are on
+    :class:`~.request_options.RequestOptions`. The field counts *retries*, not attempts, so
+    ``max_retries=0`` disables retrying -- the spelling Stainless, Fern and APIMatic v1 all use, so a
+    count reads the same wherever a caller met it before. The loop adds the initial attempt.
+
+    Retries are counted rather than time budgeted. A wall-clock budget makes the elapsed time
+    predictable and the attempt count arbitrary; counting retries makes the worst case
+    ``max_retries + 1`` timeouts plus the delays between them -- every term of which the caller set.
+
+    One status set under one method gate, and the gate covers a request that produced no response
+    too. A 5xx or a 408 says the server may have processed the request; a dropped connection leaves
+    that unknown; and a 429, though a refusal, is gated the same way rather than given a set of its
+    own. Nothing is repeated for a method outside ``http_methods_to_retry``; a caller whose API honors
+    the ``Idempotency-Key`` this SDK already sends on every non-GET declares that by adding ``POST``."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    max_retries: MaxRetries = 3
+    """Retries after the initial attempt. ``0`` disables retrying."""
+
+    initial_delay: InitialDelay = 1.0
+    """Seconds to wait before the first retry, before jitter."""
+
+    backoff_factor: BackoffFactor = 2.0
+    """Multiplier applied per attempt. ``1`` makes the delay constant."""
+
+    max_delay: MaxDelay = 60.0
+    """Ceiling for one wait: the curve is capped at it, and a longer ``Retry-After`` is trimmed to it."""
+
+    max_jitter: MaxJitter = 0.5
+    """Widest random addition to one wait, in seconds. ``0`` makes the curve exact."""
+
+    status_codes_to_retry: AbstractSet[int] = frozenset({408, 429, 500, 502, 503, 504})
+    """Statuses that qualify for a retry -- for a method in ``http_methods_to_retry``, never otherwise."""
+
+    http_methods_to_retry: AbstractSet[HttpMethod] = frozenset({"GET", "HEAD", "PUT", "OPTIONS"})
+    """Methods safe to repeat blind. Add ``POST`` when the API honours our ``Idempotency-Key``."""
+
+    @classmethod
+    def coerce(cls, retry: int | RetryOptionsOrDict | None) -> RetryOptions:
+        """Return ``retry`` as a :class:`RetryOptions`, whichever spelling it arrived in.
+
+        An instance passes straight through -- it validated itself when it was built -- and ``None``
+        yields ``RetryOptions()``, because **retrying is on by default**: a caller who
+        configured nothing gets the tuned policy, three retries on the idempotent methods. Turning it
+        off is ``0`` (or ``{"max_retries": 0}``); asking with a count alone is a bare ``int``, which is
+        ``max_retries`` and leaves every other field at its default. It is handed to that field
+        unexamined, so it coerces exactly as ``max_retries`` does -- a ``bool`` included, ``True`` being
+        one retry -- and no rule here is stricter or laxer than the field it stands for.
+
+        Args:
+            retry: A retry count, the policy in either spelling, or ``None`` for the tuned
+                defaults. It is the client's own ``retry_options`` argument, whichever spelling it
+                arrived in; a single call overrides the policy it yields field by field, through
+                the flat terms on :class:`~.request_options.RequestOptions`.
+
+        Returns:
+            A validated :class:`RetryOptions`; ``RetryOptions()`` when ``retry`` is ``None``.
+
+        Raises:
+            ValidationError: If ``retry`` carries an unknown key or an out-of-range value -- a
+                negative count included. It subclasses ``ValueError``, so a caller catching that
+                still covers this."""
+        if retry is None:
+            return cls()
+        if isinstance(retry, int):
+            return cls(max_retries=retry)
+        if isinstance(retry, cls):
+            return retry
+        return cls.model_validate(retry)
+
+
+class RetryOptionsDict(TypedDict):
+    """The dict-shaped spelling of :class:`RetryOptions`, mirroring it field for field.
+
+    Closed and typed per key, which is what makes ``{"max_retires": 2}`` a type error at the call
+    site rather than a surprise at runtime."""
+
+    max_retries: NotRequired[int]
+    initial_delay: NotRequired[float]
+    backoff_factor: NotRequired[float]
+    max_delay: NotRequired[float]
+    max_jitter: NotRequired[float]
+    status_codes_to_retry: NotRequired[AbstractSet[int]]
+    http_methods_to_retry: NotRequired[AbstractSet[HttpMethod]]
+
+
+RetryOptionsOrDict: TypeAlias = RetryOptions | RetryOptionsDict
+"""The typed policy, or a dict carrying the same keys -- the two spellings the companion covers."""
+
+
+def backoff_seconds(retries_taken: int, retry_options: RetryOptions) -> float:
+    """The curve's wait after ``retries_taken`` retries, plus a random addition up to ``max_jitter``.
+
+    The exponential curve is the floor and the jitter sits on top of it. ``max_delay`` bounds the
+    **sum**, so a wait never exceeds it and the jitter is what the cap swallows first: every attempt
+    whose curve has reached the ceiling waits exactly ``max_delay``.
+
+    That includes a curve too large for a float. ``float ** int`` raises ``OverflowError`` rather
+    than answering infinity -- a factor of 2 does from the 1024th retry -- and the loop asks for this
+    wait while it still holds the discarded response, outside its close guard. So this never raises:
+    an overflow is read as past the ceiling.
+
+    Args:
+        retries_taken: How many retries this call has already made; ``0`` for the first one.
+        retry_options: The policy in force for this call.
+
+    Returns:
+        Seconds to wait: the curve plus ``0.0`` to ``max_jitter``, capped at ``max_delay``."""
+    try:
+        backoff_sec = retry_options.initial_delay * retry_options.backoff_factor**retries_taken
+    except OverflowError:
+        backoff_sec = retry_options.max_delay
+    return min(backoff_sec + random.uniform(0.0, retry_options.max_jitter), retry_options.max_delay)
+
+
+def is_retryable_body(body: RequestBody | None) -> bool:
+    """Whether ``body`` can be sent again byte for byte.
+
+    ``None``, JSON, form and text bodies always can: each already holds its wire bytes. The two that
+    carry caller-held content -- a raw binary body, and a multipart body's file parts -- are each
+    asked about their content.
+
+    A multipart body's text parts are not consulted: they hold their bytes. One non-retryable file part
+    disqualifies the whole body, because the parts are encoded as a single stream.
+
+    Args:
+        body: The body the endpoint built, or ``None`` for a request that carries none.
+
+    Returns:
+        ``True`` only for a shape proven re-sendable."""
+    match body:
+        case None | JsonBody() | FormBody() | TextBody():
+            return True
+        case BinaryBody(content=content):
+            return isinstance(content, (bytes, bytearray, Path))
+        case MultipartBody(parts=parts):
+            return all(
+                isinstance(part.content, (bytes, bytearray, Path)) for part in parts if isinstance(part, MultipartFile)
+            )
+
+
+def retry_after_seconds(headers: Mapping[str, str], now: datetime) -> float | None:
+    """Seconds named by ``Retry-After``, or ``None`` if the header is absent or unusable.
+
+    Both RFC 9110 forms are read: delta-seconds, and an HTTP-date. A date already past floors at
+    ``0.0`` -- the server is naming a moment, and a moment gone means *now*.
+
+    Delta-seconds is read exactly as the grammar writes it, ``1*DIGIT``, and never through bare
+    ``float`` -- which would take ``1_0`` as ten, ``inf`` as a wait beyond any ceiling, and ``1.5``
+    and ``-5`` as values the grammar has no room for. So a non-conforming value is *unparseable*
+    rather than quietly reinterpreted, and the floor above is the date branch's alone.
+
+    An unparseable value yields ``None`` rather than raising. A malformed header is the server's
+    defect, and turning a retryable failure into an exception would make the SDK's behavior worse
+    than if the header had never been sent.
+
+    The clock is the caller's: ``now`` is read once in ``raw_client.execute``, immediately after the
+    head arrives, and handed over. So the one branch that needs a reference moment names it as an
+    argument rather than reaching for a global, which keeps this module free of ambient state and
+    makes the date branch testable by passing a moment instead of patching ``datetime``.
+
+    The field is found case-insensitively rather than by ``headers.get("retry-after")``. Both
+    response protocols oblige a transport to lowercase its header names, and the shipped one does --
+    but a custom transport that forgets would not fail here, it would silently ignore every
+    ``Retry-After`` a server sends and wait out the curve instead. That is the kind of defect a
+    caller never sees, so the one reader of a response header pays a scan of the head to be
+    independent of the obligation. The scan runs only on a retryable failure.
+
+    Args:
+        headers: The failing response's head, scanned case-insensitively for the field.
+        now: The moment an HTTP-date is measured against -- the loop's own reading of the clock,
+            taken when the head arrived. Unused by the delta-seconds form.
+
+    Returns:
+        Seconds to wait, never negative; ``None`` where the header is absent or unusable."""
+    token = find_header(headers, "Retry-After")
+    if token is None:
+        return None
+    # ``isdigit`` alone would take a non-ASCII digit; ``isascii`` fences the pair to ``[0-9]+``.
+    if token.isascii() and token.isdigit():
+        return float(token)
+    try:
+        when = parsedate_to_datetime(token)
+    except (TypeError, ValueError):
+        return None
+    # A date with no zone is UTC by RFC 9110: HTTP-dates are always GMT, and the one legacy format
+    # parsedate_to_datetime accepts without a zone would otherwise subtract as naive and raise.
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=timezone.utc)
+    return max(0.0, (when - now).total_seconds())

swagger_petstore_open_api_3_1_0/core/runtime_env.py

@@ -0,0 +1,43 @@
+"""The host environment this SDK reports in its identification headers.
+
+Two values, both constant for the life of the process: the operating system with its architecture,
+and the Python implementation with its version. They are probed once at import rather than per
+request -- neither can change while the process runs, and a request-path probe would pay for that
+certainty on every call.
+
+The architecture is reported exactly as the host spells it. ``platform.machine()`` is what the
+machine answered, so the header is ground truth for the host that sent it, and no table here can
+fall behind an architecture that ships after this SDK does. A consumer comparing hosts across
+operating systems folds the spellings on its own side -- ``AMD64`` and ``x86_64`` are one machine
+described by two kernels, and only the collector knows which spellings it wants joined.
+
+Every probe is guarded. These values are computed while the package is being imported, so an
+unhandled failure here would not degrade a header, it would stop the SDK from importing at all."""
+
+from __future__ import annotations
+
+import platform
+from typing import Final
+
+
+def _operating_system() -> str:
+    """Return the host OS, its release and its architecture, or ``unknown`` if a probe fails."""
+    try:
+        return f"{platform.system()} {platform.release()} {platform.machine()}".strip()
+    except Exception:
+        return "unknown"
+
+
+def _python_runtime() -> str:
+    """Return the interpreter and its version, or ``unknown`` if a probe fails."""
+    try:
+        return f"{platform.python_implementation()} {platform.python_version()}"
+    except Exception:
+        return "unknown"
+
+
+OPERATING_SYSTEM: Final = _operating_system()
+"""The host OS, its release and its architecture -- ``Windows 11 AMD64``, ``Darwin 23.5.0 arm64``."""
+
+PYTHON_RUNTIME: Final = _python_runtime()
+"""The interpreter and its version -- ``CPython 3.13.14``, ``PyPy 3.10.14``."""

swagger_petstore_open_api_3_1_0/core/servers.py

@@ -0,0 +1,33 @@
+"""Runtime helpers for the generated ``server/`` layer."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+def validate_one_of(value: T, allowed: Sequence[T], label: str) -> T:
+    """Return ``value`` unchanged, or raise a guided ``ValueError`` naming the valid names.
+
+    The generated ``server/environment.py`` calls this with the arms of its ``Environment``
+    literal alias, which is why the check is a membership test rather than an enum lookup: the
+    environment is an internal selector for a URL variant and never reaches the wire, so it is
+    spelled as a plain string. There is no case or whitespace coercion -- with one spelling per
+    environment there is nothing to reconcile.
+
+    Args:
+        value: The candidate the caller supplied.
+        allowed: Every accepted value, in the order the message should name them.
+        label: What ``value`` names, used in the error message (e.g. ``"environment"``).
+
+    Returns:
+        ``value`` unchanged.
+
+    Raises:
+        ValueError: If ``value`` is not in ``allowed``; the message names every accepted value."""
+    if value not in allowed:
+        valid = ", ".join(repr(name) for name in allowed)
+        raise ValueError(f"{value!r} is not a valid {label}; expected one of {valid}")
+    return value