cliV1 0.1.1__py3-none-any.whl

swagger_petstore_open_api_3_0/core/raw_client.py

@@ -0,0 +1,388 @@
+"""The seams every endpoint crosses: build a request, send it, shape a result.
+
+One pipeline, two flavors. :class:`BaseRawClient` holds the halves that do not depend on
+concurrency -- resolving the API-wide, endpoint and caller parameter layers into a URL and headers,
+and deciding whether a status code makes a :class:`Success` or a :class:`Failure` -- and each
+concrete client adds only the transport-touching seams: ``execute`` for a buffered response,
+``stream`` for one whose body stays unread. Both flavors spell both seams identically, so which
+flavor is in play is carried by the client a caller holds rather than by a suffix on the method.
+
+The two live in one module, with no ``async_raw_client.py`` beside it, because they are a peer pair:
+the two lines they differ by -- resolving the auth scheme and sending -- are visible on one screen,
+which is what keeps the sync and async paths from drifting apart."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+from ._internal.headers import resolve_headers
+from ._internal.urls import build_url, resolve_params
+from .auth import AsyncAuthScheme, AuthParams, AuthScheme, invalidate, no_auth, resolve_auth
+from .bodies import RequestBody
+from .decoding import AsyncStreamDecoder, ErrorMapper, ResponseDecoder, StreamDecoder
+from .params import Param, UrlTemplate
+from .request_options import RequestOptions, RequestOptionsOrDict
+from .results import ApiResult, Failure, Success
+from .transport import (
+    AsyncHttpClient,
+    AsyncStreamedResponse,
+    HttpClient,
+    HttpRequest,
+    HttpResponse,
+    StreamedResponse,
+)
+
+T = TypeVar("T")
+E = TypeVar("E")
+TransportT = TypeVar("TransportT", bound=HttpClient | AsyncHttpClient)
+
+
+@dataclass(frozen=True, slots=True)
+class BaseRawClient(Generic[TransportT]):
+    """Shared request-building and result-shaping for the raw clients.
+
+    Holds the one transport its concurrency flavor can actually use -- the type
+    parameter is what makes :class:`RawClient` provably sync and
+    :class:`AsyncRawClient` provably async, so neither can be handed the other's
+    transport. Subclasses add only the ``execute`` and ``stream`` seams, which differ
+    solely by how they resolve the auth scheme and by ``send`` vs ``await …send``; the
+    pipeline below is not duplicated and the sync/async boundary is never crossed.
+
+    The three ``global_*`` fields carry the parameters the API applies to *every*
+    request. They are derived from the API description, not from a caller: whoever
+    generates this SDK writes them here, and an API that declares none leaves them
+    empty. Each is combined with a single call's own parameters by the matching
+    ``resolve_*`` function, so this class decides nothing about precedence -- it only
+    says which two sides go in. All three are the same shape -- a sequence of
+    parameters, each naming the type it was declared as -- which is what lets one
+    ``param`` factory serve every location a request parameter can occupy, and what
+    makes a wrongly-typed API-wide header a build failure rather than a wire bug.
+
+    A single call's ``request_options`` is the third source: not what the API
+    prescribes and not what the endpoint declares, but what the caller asked for this
+    once. It is validated here, at the one place a request is built, so no emitted
+    endpoint ever inspects an option.
+
+    Authentication is a fourth source, and the full order for both headers and query parameters is::
+
+        global_*  ->  the endpoint's own  ->  auth  ->  the caller's extra_headers
+
+    Auth outranks the endpoint's own parameters because an operation parameter must not be able to
+    clobber a credential, and loses to ``extra_headers`` because that is how a caller deliberately
+    overrides one -- or blanks it, for a call meant to go out anonymous. Note that ``_build_request``
+    takes already-resolved :class:`~.auth.AuthParams`, not a scheme: resolving a scheme may require
+    I/O, so it happens in ``execute``, which is the one place the two flavors already differ.
+
+    A **401 invalidates whatever the scheme cached**, so a credential the server revoked ahead of its
+    own expiry is re-obtained on the next call rather than resent until it times out. For every scheme
+    that holds a constant this is one ``isinstance`` and nothing more. The failing request is
+    deliberately **not** retried: a caller sees one 401 and then recovery, which keeps this seam free
+    of the retry policy ADR-0001 rules out. Like scheme resolution, it lives in ``execute`` --
+    ``_build_result`` is a ``staticmethod`` that never sees the scheme."""
+
+    http_client: TransportT
+    global_headers: Sequence[Param[Any]] = ()
+    global_query_params: Sequence[Param[Any]] = ()
+    global_path_params: Sequence[Param[Any]] = ()
+
+    def _build_request(
+        self,
+        *,
+        http_method: str,
+        url_template: UrlTemplate,
+        path_params: Sequence[Param[Any]] | None,
+        query_params: Sequence[Param[Any]] | None,
+        headers: Sequence[Param[Any]] | None,
+        body: RequestBody | None,
+        auth: AuthParams,
+        request_options: RequestOptionsOrDict | None,
+    ) -> HttpRequest:
+        options = RequestOptions.coerce(request_options)
+        return HttpRequest(
+            method=http_method,
+            url=build_url(
+                url_template,
+                path_params=resolve_params(self.global_path_params, path_params),
+                query_params=resolve_params(self.global_query_params, (*(query_params or ()), *auth.query_params)),
+            ),
+            headers=resolve_headers(
+                self.global_headers,
+                (*(headers or ()), *auth.request_headers()),
+                extra_headers=options.extra_headers,
+            ),
+            body=body,
+            timeout=options.timeout,
+        )
+
+    @staticmethod
+    def _build_result(
+        response: HttpResponse,
+        *,
+        decoder: ResponseDecoder[T],
+        error_mapper: ErrorMapper[E],
+    ) -> ApiResult[T, E]:
+        """Shape a response into a result. 2xx succeeds, everything else fails.
+
+        Every operation names a decoder -- an empty 2xx body is ``empty_response``, not an omitted
+        argument -- so there is no "was one supplied?" branch here, and no empty-body special case
+        either. ``T`` therefore means what it says: a declared ``ApiResult[T, E]`` yields a ``T``,
+        and no cast or ``Any`` stands between the two.
+
+        An operation that declares a payload and receives no body raises out of its decoder rather
+        than quietly succeeding with ``None``, which is the rule every other
+        response-deserialization failure already follows.
+
+        Args:
+            response: The response as the transport returned it.
+            decoder: The operation's 2xx decoder; ``empty_response`` when it declares no body.
+            error_mapper: The operation's error mapper; ``raw_error_response`` when it declares
+                no error schemas.
+
+        Returns:
+            A :class:`Success` for a 2xx status, otherwise a :class:`Failure`.
+
+        Raises:
+            ValueError: If the body does not deserialize. A deserialization failure is not an API
+                error, so it propagates in both response modes rather than becoming a failure."""
+        if 200 <= response.status_code < 300:
+            return Success(payload=decoder.decode(response), response=response)
+
+        return Failure(error=error_mapper.map(response), response=response)
+
+
+def _head_response(streamed: StreamedResponse | AsyncStreamedResponse) -> HttpResponse:
+    # status/headers are synchronous properties on both streamed protocols, so one helper serves
+    # both flavours. content stays b"": on a streamed success the body IS the payload.
+    return HttpResponse(status_code=streamed.status_code, headers=dict(streamed.headers), content=b"")
+
+
+@dataclass(frozen=True, slots=True)
+class RawClient(BaseRawClient[HttpClient]):
+    """Synchronous raw client: builds the request, sends it, shapes the result."""
+
+    def execute(
+        self,
+        *,
+        http_method: str,
+        url_template: UrlTemplate,
+        path_params: Sequence[Param[Any]] | None = None,
+        query_params: Sequence[Param[Any]] | None = None,
+        headers: Sequence[Param[Any]] | None = None,
+        body: RequestBody | None = None,
+        auth_scheme: AuthScheme = no_auth,
+        decoder: ResponseDecoder[T],
+        error_mapper: ErrorMapper[E],
+        request_options: RequestOptionsOrDict | None = None,
+    ) -> ApiResult[T, E]:
+        request = self._build_request(
+            http_method=http_method,
+            url_template=url_template,
+            path_params=path_params,
+            query_params=query_params,
+            headers=headers,
+            body=body,
+            auth=auth_scheme.apply(),
+            request_options=request_options,
+        )
+        response = self.http_client.send(request)
+        if response.status_code == 401:
+            invalidate(auth_scheme)
+        return self._build_result(response, decoder=decoder, error_mapper=error_mapper)
+
+    def stream(
+        self,
+        *,
+        http_method: str,
+        url_template: UrlTemplate,
+        path_params: Sequence[Param[Any]] | None = None,
+        query_params: Sequence[Param[Any]] | None = None,
+        headers: Sequence[Param[Any]] | None = None,
+        body: RequestBody | None = None,
+        auth_scheme: AuthScheme = no_auth,
+        decoder: StreamDecoder[T],
+        error_mapper: ErrorMapper[E],
+        request_options: RequestOptionsOrDict | None = None,
+    ) -> ApiResult[T, E]:
+        """Send a request and return its body unread.
+
+        The ``decoder`` receives the body **unread**, unlike a :class:`ResponseDecoder`, and the
+        payload it builds owns the connection from that moment. A file names ``file_decoder``,
+        which carries no subscript because a file bypasses the model layer; a payload type that
+        varies per operation names it in a subscript, exactly as ``json_decoder[T]`` does. Either
+        way ``T`` is solved from an argument, never from the declared return type.
+
+        A non-2xx body is read in full and the connection released *before* the mapper runs, so an
+        error schema deserializes exactly as it does on the buffered path and a :class:`Failure`
+        never carries a lifetime obligation -- even when the error decoder itself raises. A
+        :class:`Success` owns the connection through its payload; see *File lifetime* in
+        docs/plans/file-handling.md.
+
+        Args:
+            http_method: The HTTP verb to send.
+            url_template: The unresolved URL for the configured environment.
+            path_params: The endpoint's path parameters, if any.
+            query_params: The endpoint's query parameters, if any.
+            headers: The endpoint's header parameters, if any.
+            body: The request body, already wire-ready, or ``None``.
+            auth_scheme: The scheme the operation declares; ``no_auth`` when it declares none.
+            decoder: The operation's streamed-payload decoder; ``file_decoder`` for a file.
+            error_mapper: The operation's error mapper; ``raw_error_response`` when it declares
+                no error schemas.
+            request_options: The caller's per-call overrides, if any.
+
+        Returns:
+            A :class:`Success` carrying the payload built over the unread body for a 2xx status,
+            otherwise a :class:`Failure` carrying the decoded error body."""
+        request = self._build_request(
+            http_method=http_method,
+            url_template=url_template,
+            path_params=path_params,
+            query_params=query_params,
+            headers=headers,
+            body=body,
+            auth=auth_scheme.apply(),
+            request_options=request_options,
+        )
+        streamed = self.http_client.stream(request)
+        try:
+            if streamed.status_code == 401:
+                invalidate(auth_scheme)
+            if 200 <= streamed.status_code < 300:
+                # The 2xx return exits the try without running else: the connection now belongs to
+                # the payload the decoder builds. A decoder that raises instead is caught below, which
+                # is why nothing on this line has to be total.
+                return Success(payload=decoder.decode(streamed, request.url), response=_head_response(streamed))
+            # Buffered once, then shared by both Failure fields -- re-reading a consumed stream
+            # raises, and read is what both releases the connection and preserves the bytes.
+            buffered = HttpResponse(
+                status_code=streamed.status_code,
+                headers=dict(streamed.headers),
+                content=streamed.read(),
+            )
+        except BaseException:
+            streamed.close()
+            raise
+        else:
+            streamed.close()
+        # Mapped AFTER the close, so a decoder raise cannot leak -- a Failure never holds a
+        # connection.
+        return Failure(error=error_mapper.map(buffered), response=buffered)
+
+
+@dataclass(frozen=True, slots=True)
+class AsyncRawClient(BaseRawClient[AsyncHttpClient]):
+    """Asynchronous raw client.
+
+    The method is named ``execute``, not ``execute_async``: sync and async peers
+    carry identical names throughout this SDK, and the transport already makes the
+    flavor unambiguous."""
+
+    async def execute(
+        self,
+        *,
+        http_method: str,
+        url_template: UrlTemplate,
+        path_params: Sequence[Param[Any]] | None = None,
+        query_params: Sequence[Param[Any]] | None = None,
+        headers: Sequence[Param[Any]] | None = None,
+        body: RequestBody | None = None,
+        auth_scheme: AsyncAuthScheme = no_auth,
+        decoder: ResponseDecoder[T],
+        error_mapper: ErrorMapper[E],
+        request_options: RequestOptionsOrDict | None = None,
+    ) -> ApiResult[T, E]:
+        request = self._build_request(
+            http_method=http_method,
+            url_template=url_template,
+            path_params=path_params,
+            query_params=query_params,
+            headers=headers,
+            body=body,
+            auth=await resolve_auth(auth_scheme),
+            request_options=request_options,
+        )
+        response = await self.http_client.send(request)
+        if response.status_code == 401:
+            invalidate(auth_scheme)
+        return self._build_result(response, decoder=decoder, error_mapper=error_mapper)
+
+    async def stream(
+        self,
+        *,
+        http_method: str,
+        url_template: UrlTemplate,
+        path_params: Sequence[Param[Any]] | None = None,
+        query_params: Sequence[Param[Any]] | None = None,
+        headers: Sequence[Param[Any]] | None = None,
+        body: RequestBody | None = None,
+        auth_scheme: AsyncAuthScheme = no_auth,
+        decoder: AsyncStreamDecoder[T],
+        error_mapper: ErrorMapper[E],
+        request_options: RequestOptionsOrDict | None = None,
+    ) -> ApiResult[T, E]:
+        """Send a request and return its body unread; the awaited twin of ``RawClient.stream``.
+
+        The same contract, with the same two-line delta ``execute`` already has: the auth scheme
+        is resolved rather than applied, and the transport is awaited.
+
+        Args:
+            http_method: The HTTP verb to send.
+            url_template: The unresolved URL for the configured environment.
+            path_params: The endpoint's path parameters, if any.
+            query_params: The endpoint's query parameters, if any.
+            headers: The endpoint's header parameters, if any.
+            body: The request body, already wire-ready, or ``None``.
+            auth_scheme: The scheme the operation declares; ``no_auth`` when it declares none.
+            decoder: The operation's streamed-payload decoder; ``async_file_decoder`` for a file.
+            error_mapper: The operation's error mapper; ``raw_error_response`` when it declares
+                no error schemas.
+            request_options: The caller's per-call overrides, if any.
+
+        Returns:
+            A :class:`Success` carrying the payload built over the unread body for a 2xx status,
+            otherwise a :class:`Failure` carrying the decoded error body."""
+        request = self._build_request(
+            http_method=http_method,
+            url_template=url_template,
+            path_params=path_params,
+            query_params=query_params,
+            headers=headers,
+            body=body,
+            auth=await resolve_auth(auth_scheme),
+            request_options=request_options,
+        )
+        streamed = await self.http_client.stream(request)
+        try:
+            if streamed.status_code == 401:
+                invalidate(auth_scheme)
+            if 200 <= streamed.status_code < 300:
+                # The 2xx return exits the try without running else: the connection now belongs to
+                # the payload the decoder builds. A decoder that raises instead is caught below, which
+                # is why nothing on this line has to be total.
+                return Success(payload=decoder.decode(streamed, request.url), response=_head_response(streamed))
+            # Buffered once, then shared by both Failure fields -- re-reading a consumed stream
+            # raises, and aread is what both releases the connection and preserves the bytes.
+            buffered = HttpResponse(
+                status_code=streamed.status_code,
+                headers=dict(streamed.headers),
+                content=await streamed.aread(),
+            )
+        except BaseException:
+            await streamed.aclose()
+            raise
+        else:
+            await streamed.aclose()
+        # Mapped AFTER the close, so a decoder raise cannot leak -- a Failure never holds a
+        # connection.
+        return Failure(error=error_mapper.map(buffered), response=buffered)
+
+
+RawClientT = TypeVar("RawClientT", bound=RawClient | AsyncRawClient)
+"""Fixes which raw client a generic holder carries -- ``RawClient`` or ``AsyncRawClient``.
+
+Bounded by the two concrete clients rather than by ``BaseRawClient[Any]``: the base defines only
+the request/result pipeline, not ``execute``, so the looser bound could not prove that a holder's
+``self._client.execute(...)`` exists -- it type-checked only because each subclass substitutes a
+concrete argument. This bound also removes the ``Any``."""

swagger_petstore_open_api_3_0/core/request_options.py

@@ -0,0 +1,94 @@
+"""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 constraint 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 typing import Final, TypeAlias
+
+from pydantic import BaseModel, ConfigDict, Field
+from typing_extensions import NotRequired, TypedDict
+
+
+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."""
+
+    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."""
+
+    @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]
+
+
+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."""

swagger_petstore_open_api_3_0/core/results.py

@@ -0,0 +1,110 @@
+"""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. ``.unwrap()`` is the
+shortcut for callers that would rather not branch -- it returns the payload or raises.
+
+: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 dataclasses import dataclass
+from typing import Any, Generic, NoReturn, TypeAlias, TypeVar
+
+from .exceptions import ApiError
+from .transport import HttpResponse
+
+T = TypeVar("T")
+E = TypeVar("E")
+
+
+@dataclass(frozen=True, slots=True)
+class Success(Generic[T]):
+    """A successful (2xx) API call carrying the decoded ``payload``."""
+
+    payload: T
+    response: HttpResponse
+
+    def unwrap(self) -> T:
+        """Collapse this result to its parsed value.
+
+        Returns:
+            The decoded payload. This variant never raises."""
+        return self.payload
+
+
+@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
+    response: HttpResponse
+
+    def unwrap(self) -> NoReturn:
+        """Collapse this result to its parsed value, which for a failure means raising.
+
+        Raises:
+            ApiError: Always, carrying this result's ``error`` and ``response``."""
+        raise ApiError(error=self.error, response=self.response)
+
+
+# One call yields exactly one of these; narrow with ``match`` or ``isinstance``,
+# or collapse to the parsed value with ``.unwrap()``.
+ApiResult: TypeAlias = Success[T] | Failure[E]
+
+
+@dataclass(frozen=True, slots=True)
+class RawError:
+    """Undecoded fallback body (unmapped status / no declared schema).
+
+    Wraps the raw response so the status and bytes are available and decoded on
+    demand. Constructed directly -- ``RawError(response)``."""
+
+    response: HttpResponse
+
+    @property
+    def status_code(self) -> int:
+        return self.response.status_code
+
+    @property
+    def content(self) -> bytes:
+        return self.response.content
+
+    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.response.text(encoding)
+
+    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 self.response.json()
+
+    def __repr__(self) -> str:
+        # Identify the response by status only -- the (undecoded, possibly large,
+        # binary, or sensitive) body and the headers/request are deliberately kept
+        # out of the string form. Read the body on demand via ``text``/``json``.
+        return f"{type(self).__name__}(status_code={self.status_code})"

swagger_petstore_open_api_3_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_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