cliV1 0.0.8__py3-none-any.whl

swagger_petstore_open_api_3_0/core/raw_client.py

@@ -0,0 +1,338 @@
+"""The seams every endpoint crosses: build a request, send it, shape a result.
+
+One pipeline, two flavors, one seam. :class:`BaseRawClient` holds the half that does not depend
+on concurrency -- resolving the API-wide, endpoint and caller parameter layers into a URL and
+headers -- and each concrete client adds only the transport-touching ``execute``. Both flavors spell
+it identically, so which flavor is in play is carried by the client a caller holds rather than by a
+suffix on the method.
+
+There is no ``_build_result`` beside ``_build_request`` any more. Shaping a result now needs the
+response *and* its lifetime in the same place -- the 2xx return has to escape without closing, while
+every other path closes -- and a static helper that could be handed a connection is one that can
+leak it. The decoder owns the body it is given (ADR-0063), so what is left here is one status
+branch, written out in each flavor because the two await differently.
+
+The two live in one module, with no ``async_raw_client.py`` beside it, because they are a peer pair:
+the handful of ``await``s they differ by 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 AsyncResponseDecoder, ErrorMapper, ResponseDecoder
+from .params import Param, UrlTemplate
+from .request_options import RequestOptions, RequestOptionsOrDict
+from .results import ApiResult, Failure, Success
+from .transport import (
+    AsyncHttpClient,
+    HttpClient,
+    HttpRequest,
+)
+
+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`` seam, which each writes out in its
+    own flavor because the two await differently; 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_request`` never sees the scheme, only the params it already resolved to."""
+
+    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,
+        )
+
+
+@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]:
+        """Send a request and shape the response into a result.
+
+        Returns once the response head has arrived. What happens to the body from there is the
+        ``decoder``'s decision, not this method's: a buffered one reads it, releases the connection
+        and parses what it read; ``file_decoder`` hands the open connection to the
+        :class:`FileResponse` it builds. Either way ``T`` is solved from that argument rather than
+        from the declared return type, and this method owns no connection on the success path.
+
+        Every operation names a decoder -- an empty 2xx body is ``empty_response``, not an omitted
+        argument -- so there is no "was one supplied?" branch and no empty-body special case. 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.
+
+        A non-2xx body is read in full and the connection released *before* the mapper runs, so a
+        :class:`Failure` never carries a lifetime obligation -- even when the mapper itself raises.
+
+        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 2xx decoder; ``empty_response`` when it declares no body,
+                ``file_decoder`` when the body is 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 decoded payload for a 2xx status, otherwise a
+            :class:`Failure` carrying the decoded error body.
+
+        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."""
+        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)
+        # The head, once, on arrival -- a fact as soon as the response exists. Read here, no path
+        # below has to touch a response it has already closed or handed to a decoder. Spelled
+        # response_headers because ``headers`` in this scope is the endpoint's own request params.
+        status_code, response_headers = response.status_code, dict(response.headers)
+        try:
+            if status_code == 401:
+                invalidate(auth_scheme)
+            if 200 <= status_code < 300:
+                # The 2xx return leaves before the read below: the body now belongs to the decoder,
+                # which either reads and releases it or hands it to the payload it builds. A decoder
+                # that raises instead is caught below, which is why nothing on this line has to be
+                # total. The handler below must never become a finally -- it would close the
+                # connection a FileResponse was just handed, on every download and silently.
+                return Success(
+                    payload=decoder.decode(response),
+                    status_code=status_code,
+                    headers=response_headers,
+                )
+            # Read once: re-reading a consumed stream raises, and read is what both releases
+            # the connection and preserves the bytes.
+            content = response.read()
+            response.close()
+            # Mapped AFTER the close, so a mapper raise cannot leak -- a Failure never holds a
+            # connection. Such a raise re-enters the handler below and closes a second time, which
+            # is a no-op: HttpResponse.close is required to be idempotent, and the 2xx decoder-raise
+            # path already relies on that.
+            return Failure(
+                error=error_mapper.map(status_code, content),
+                status_code=status_code,
+                headers=response_headers,
+            )
+        except BaseException:
+            response.close()
+            raise
+
+
+@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: AsyncResponseDecoder[T],
+        error_mapper: ErrorMapper[E],
+        request_options: RequestOptionsOrDict | None = None,
+    ) -> ApiResult[T, E]:
+        """Send a request and shape the response into a result.
+
+        Returns once the response head has arrived. What happens to the body from there is the
+        ``decoder``'s decision, not this method's: a buffered one reads it, releases the connection
+        and parses what it read; ``file_decoder`` hands the open connection to the
+        :class:`FileResponse` it builds. Either way ``T`` is solved from that argument rather than
+        from the declared return type, and this method owns no connection on the success path.
+
+        Every operation names a decoder -- an empty 2xx body is ``empty_response``, not an omitted
+        argument -- so there is no "was one supplied?" branch and no empty-body special case. 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.
+
+        A non-2xx body is read in full and the connection released *before* the mapper runs, so a
+        :class:`Failure` never carries a lifetime obligation -- even when the mapper itself raises.
+
+        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 2xx decoder; ``empty_response`` when it declares no body,
+                ``file_decoder`` when the body is 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 decoded payload for a 2xx status, otherwise a
+            :class:`Failure` carrying the decoded error body.
+
+        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."""
+        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)
+        # The head, once, on arrival -- a fact as soon as the response exists. Read here, no path
+        # below has to touch a response it has already closed or handed to a decoder. Spelled
+        # response_headers because ``headers`` in this scope is the endpoint's own request params.
+        status_code, response_headers = response.status_code, dict(response.headers)
+        try:
+            if status_code == 401:
+                invalidate(auth_scheme)
+            if 200 <= status_code < 300:
+                # The 2xx return leaves before the read below: the body now belongs to the decoder,
+                # which either reads and releases it or hands it to the payload it builds. A decoder
+                # that raises instead is caught below, which is why nothing on this line has to be
+                # total. The handler below must never become a finally -- it would close the
+                # connection an AsyncFileResponse was just handed, on every download and silently.
+                return Success(
+                    payload=await decoder.decode(response),
+                    status_code=status_code,
+                    headers=response_headers,
+                )
+            # Read once: re-reading a consumed stream raises, and aread is what both releases
+            # the connection and preserves the bytes.
+            content = await response.aread()
+            await response.aclose()
+            # Mapped AFTER the close, so a mapper raise cannot leak -- a Failure never holds a
+            # connection. Such a raise re-enters the handler below and closes a second time, which
+            # is a no-op: AsyncHttpResponse.aclose is required to be idempotent, and the 2xx
+            # decoder-raise path already relies on that.
+            return Failure(
+                error=error_mapper.map(status_code, content),
+                status_code=status_code,
+                headers=response_headers,
+            )
+        except BaseException:
+            await response.aclose()
+            raise
+
+
+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,123 @@
+"""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.
+
+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 Mapping
+from dataclasses import dataclass, field
+from typing import Any, Generic, NoReturn, TypeAlias, TypeVar
+
+from ._internal.wire import parse_json
+from .exceptions import ApiError
+
+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
+    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)."""
+
+    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
+    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)."""
+
+    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 the response head."""
+        raise ApiError(error=self.error, status_code=self.status_code, headers=self.headers)
+
+
+# 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).
+
+    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})"

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