cliV1 0.1.1__py3-none-any.whl

swagger_petstore_open_api_3_0/core/adapters.py

@@ -0,0 +1,177 @@
+"""The one place a ``TypeAdapter`` is built, and what a value is validated *into*.
+
+Shared by the request path (:func:`json_body`, :func:`param`) and the response path (the decoders),
+so the expensive step in pydantic v2 -- building the adapter -- happens once per type for the life
+of the process rather than once per request.
+
+It sits on its own, below both paths, because both need it and neither owns it: a request-body
+module reaching into the response-decoding module for it would put a cycle in the import graph."""
+
+from __future__ import annotations
+
+from functools import reduce
+from operator import or_
+from threading import RLock
+from types import UnionType
+from typing import Any, Final, TypeVar, Union, get_args, get_origin
+
+from pydantic import TypeAdapter
+from typing_extensions import TypeForm, is_typeddict
+
+T = TypeVar("T")
+
+_CONTAINERS: Final = (list, dict)
+"""The container origins a spec can express -- an array and a map -- so the only two emitted."""
+
+_ADAPTER_CACHE_MAX: Final = 512
+_adapter_lock: Final = RLock()
+_adapters: Final[dict[object, TypeAdapter[Any]]] = {}
+
+
+def validation_target(type_: TypeForm[T]) -> TypeForm[T]:
+    """Drop the dict-shaped companions from ``type_``, leaving what a value is validated *into*.
+
+    An endpoint accepts ``Employee | EmployeeDict``, and that whole union is what it declares and
+    hands the factory -- but only ``Employee`` may reach :func:`adapter_for`. The adapter both
+    validates *and* dumps, and a dict matching the ``TypedDict`` arm is dumped verbatim: wire
+    aliases lost (``address_line_1`` for ``addressLine1``), defaulted fields absent, unknown keys
+    silently dropped. A companion is an *input* shape, never a wire shape, so the type describing
+    what a caller may pass and the type a value is validated into are two different things.
+
+    The strip reaches wherever a companion can be written -- through union members and into
+    container parameters -- so ``list[Employee | EmployeeDict]`` and
+    ``list[Employee] | list[EmployeeDict]`` both resolve to ``list[Employee]``. Generic over ``T``
+    so that ``adapter_for(validation_target(type_))`` keeps the adapter's type instead of erasing
+    it to ``Any`` at the one hop between two otherwise precise signatures.
+
+    A type form that is dict-shaped *throughout* has no target at all. Only a generator defect
+    emits one, and it type-checks, so it is named here rather than surfacing as ``reduce`` failing
+    on an empty sequence at the first request.
+
+    Args:
+        type_: The declared type expression, dict-shaped companions included.
+
+    Returns:
+        The same expression with every companion arm removed -- what a value validates into.
+
+    Raises:
+        TypeError: If ``type_`` is dict-shaped throughout, leaving no model arm to validate into."""
+    if _is_companion(type_):
+        raise TypeError(
+            f"{type_!r} names only dict-shaped companions, which are input shapes and never wire "
+            f"shapes -- a validation target needs the model arm each companion accompanies"
+        )
+
+    target: TypeForm[T] = _strip_companions(type_)
+    return target
+
+
+def _is_companion(type_: TypeForm[Any]) -> bool:
+    """Whether ``type_`` is dict-shaped throughout, so no model arm survives the strip.
+
+    ``all`` for a union and ``any`` for a container, and the asymmetry is the rule itself: a union
+    keeps a target while *one* member has one, whereas a container whose parameter has none has none
+    either -- ``list[EmployeeDict]`` cannot be narrowed to a list of anything.
+
+    Args:
+        type_: The type expression to classify.
+
+    Returns:
+        ``True`` when nothing in ``type_`` would survive the companion strip."""
+    if is_typeddict(type_):
+        return True
+
+    origin = get_origin(type_)
+    if origin in (Union, UnionType):
+        return all(_is_companion(arg) for arg in get_args(type_))
+    if origin in _CONTAINERS:
+        return any(_is_companion(arg) for arg in get_args(type_))
+    return False
+
+
+def _strip_companions(type_: TypeForm[Any]) -> TypeForm[Any]:
+    """``type_`` with every companion dropped, rebuilt only where something actually changed.
+
+    Two properties, each load-bearing:
+
+    - the origin checks, because ``get_args(list[str])`` is ``(str,)`` -- descending is only sound
+      for the origins whose parameters *are* element types, so everything else is returned
+      untouched. Notably ``Annotated``, which is how ``Person`` carries its
+      ``Field(discriminator=...)``: descending would silently untag a discriminated union.
+      ``_CONTAINERS`` is closed at ``list`` and ``dict`` rather than "every container Python has" --
+      a spec expresses arrays and maps, and descending a shape no generator emits would be
+      speculative surface. A ``tuple`` or ``set`` parameter passes through like any other origin;
+    - the nothing-changed short-circuits, which hand back the expression *as written* rather than a
+      rebuilt one, so a companion-free union such as ``EmailStr | str`` cannot lose a member to
+      ``Union``'s deduplication, and one declared type keeps one :func:`adapter_for` cache entry.
+
+    Rebuilt with ``|`` rather than ``Union[tuple(targets)]``: mypy types that subscript as a typing
+    special form rather than a ``TypeForm``, so it cannot be returned from this signature. The
+    annotated locals are what keep the imprecision of ``get_args`` here instead of at every caller.
+
+    Args:
+        type_: The type expression to strip.
+
+    Returns:
+        ``type_`` itself when no companion was found, otherwise the rebuilt expression."""
+    origin = get_origin(type_)
+    args = get_args(type_)
+
+    if origin in (Union, UnionType):
+        targets = [_strip_companions(arg) for arg in args if not _is_companion(arg)]
+        if len(targets) == len(args) and all(target is arg for target, arg in zip(targets, args, strict=True)):
+            return type_
+        rebuilt: TypeForm[Any] = reduce(or_, targets)
+        return rebuilt
+
+    if origin in _CONTAINERS:
+        stripped = [_strip_companions(arg) for arg in args]
+        if all(target is arg for target, arg in zip(stripped, args, strict=True)):
+            return type_
+        reparametrized: TypeForm[Any] = origin[tuple(stripped)]
+        return reparametrized
+
+    return type_
+
+
+def adapter_for(type_: TypeForm[T]) -> TypeAdapter[T]:
+    """Return the process-wide cached ``TypeAdapter`` for ``type_``, building it once.
+
+    The cache must be module-level to work at all: a decoder is constructed per call, so
+    an instance-owned cache would be discarded with it and never see a second lookup.
+
+    Unhashable type forms bypass the cache. At ``_ADAPTER_CACHE_MAX`` entries it is cleared
+    wholesale -- predictable, and far beyond the number of distinct types one generated SDK
+    produces.
+
+    A hit is served without the lock, which is sound because a dict read is atomic under the GIL and
+    internally locked on free-threaded builds; a stale read racing the wholesale ``clear()`` still
+    returns a correct adapter for that type. The lock is there to make each *build* happen once --
+    the contract ``test_adapter_cache.py`` pins -- not to serialize reads, so the build stays inside
+    it and the re-check inside catches a type another thread built while this one waited.
+
+    Args:
+        type_: The validation target, already stripped of companions by :func:`validation_target`.
+
+    Returns:
+        The adapter for ``type_``, shared across the process unless ``type_`` is unhashable."""
+    try:
+        hash(type_)
+    except TypeError:
+        return TypeAdapter(type_)
+
+    cached = _adapters.get(type_)
+    if cached is not None:
+        return cached
+
+    with _adapter_lock:
+        cached = _adapters.get(type_)
+        if cached is not None:
+            return cached
+
+        if len(_adapters) >= _ADAPTER_CACHE_MAX:
+            _adapters.clear()
+
+        adapter: TypeAdapter[T] = TypeAdapter(type_)
+        _adapters[type_] = adapter
+        return adapter

swagger_petstore_open_api_3_0/core/auth/__init__.py

@@ -0,0 +1,70 @@
+"""The authentication layer's curated surface: its models, its contract, its composites.
+
+The route the runtime facade and ``raw_client`` take, so neither needs to know how this package is laid
+out. What only ``schemes/`` needs -- ``ScopeT``, ``OAuth2Credentials``, ``CredentialsPlacement``,
+``OAuthParams`` and ``scope_params`` -- stays behind, reached at ``models`` directly.
+
+⚠️ **``schemes/`` is deliberately not re-exported here.** A scheme module reaches ``raw_client``, which
+reaches this package -- so importing ``.schemes`` from this file would close that loop into an
+``ImportError`` on whichever of the two is imported first. The facade names ``.schemes`` itself."""
+
+from .composition import (
+    AllSchemes,
+    AnySchemes,
+    AsyncAllSchemes,
+    AsyncAnySchemes,
+    invalidate,
+    is_configured,
+    no_auth,
+    resolve_auth,
+)
+from .models import (
+    AuthParams,
+    OAuthError,
+    OAuthProviderError,
+    OAuthToken,
+    OAuthTokenRefreshable,
+    client_secret_basic,
+    client_secret_post,
+    oauth_error_response,
+)
+from .protocols import (
+    AsyncAuthScheme,
+    AsyncRefreshableTokenSource,
+    AsyncTokenSource,
+    AuthScheme,
+    RefreshableTokenSource,
+    RevocableAuthScheme,
+    TokenSource,
+)
+
+__all__ = [
+    # What one scheme contributes to a request
+    "AuthParams",
+    # The contract
+    "AuthScheme",
+    "AsyncAuthScheme",
+    "RevocableAuthScheme",
+    # The absent credential, and composition
+    "no_auth",
+    "is_configured",
+    "resolve_auth",
+    "invalidate",
+    "AllSchemes",
+    "AnySchemes",
+    "AsyncAllSchemes",
+    "AsyncAnySchemes",
+    # Managed OAuth 2.0 -- the token source seam
+    "TokenSource",
+    "AsyncTokenSource",
+    "RefreshableTokenSource",
+    "AsyncRefreshableTokenSource",
+    # Managed OAuth 2.0 -- the provider's vocabulary
+    "OAuthToken",
+    "OAuthTokenRefreshable",
+    "OAuthProviderError",
+    "OAuthError",
+    "oauth_error_response",
+    "client_secret_basic",
+    "client_secret_post",
+]

swagger_petstore_open_api_3_0/core/auth/composition.py

@@ -0,0 +1,175 @@
+"""The absent credential, and the two ways an operation's ``security`` composes several schemes.
+
+:data:`no_auth` is what an unconfigured credential becomes, and :func:`is_configured` tests identity
+against that one instance -- never "applying it did not raise", so a *blank* credential is configured
+and is sent. :class:`AllSchemes` and :class:`AnySchemes`, with their async twins, are OpenAPI's AND and
+OR requirements. Neither withholds a request over a partial set: the SDK never refuses to send because
+a credential is missing, the server decides.
+
+All four composites carry ``invalidate``, which makes a composite itself revocable so nesting
+propagates."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Final
+
+from .models import AuthParams
+from .protocols import AsyncAuthScheme, AuthScheme, RevocableAuthScheme
+
+
+async def resolve_auth(scheme: AsyncAuthScheme) -> AuthParams:
+    """The async client's counterpart to a plain ``scheme.apply()``.
+
+    Narrowing is on :class:`AuthParams` rather than on awaitability, so the awaited branch keeps its
+    precise type instead of widening to ``Any``.
+
+    Args:
+        scheme: The scheme to apply, whether or not it needs I/O to produce its parameters.
+
+    Returns:
+        What the scheme contributes to this request."""
+    applied = scheme.apply()
+    return applied if isinstance(applied, AuthParams) else await applied
+
+
+@dataclass(frozen=True, slots=True)
+class _NoAuth:
+    """The absent credential: a scheme that contributes nothing.
+
+    Private so that :func:`is_configured` can test identity against the one instance below; a second
+    instance would be indistinguishable from a configured scheme by that test."""
+
+    def apply(self) -> AuthParams:
+        return AuthParams()
+
+
+no_auth: Final[AuthScheme] = _NoAuth()
+"""What the client writes when a credential is absent, and ``execute``'s default.
+
+An endpoint whose operation declares no ``security`` omits ``auth=`` entirely and takes this. The SDK
+never refuses to send a request because a credential is missing -- the server decides."""
+
+
+def is_configured(scheme: AuthScheme | AsyncAuthScheme) -> bool:
+    """Whether a credential was supplied for ``scheme``.
+
+    Identity against the one null object, never "applying it did not raise". A *blank* credential is
+    configured and is sent: ``None`` is the only sentinel.
+
+    Args:
+        scheme: The scheme to test, a caller's own included.
+
+    Returns:
+        ``True`` unless this is the null object :data:`no_auth`."""
+    return scheme is not no_auth
+
+
+def invalidate(scheme: AuthScheme | AsyncAuthScheme) -> None:
+    """Drop whatever ``scheme`` cached, if it caches anything at all.
+
+    A no-op for every static scheme, so on an API with no managed OAuth the 401 branch in ``execute``
+    costs one ``isinstance`` and nothing else.
+
+    Args:
+        scheme: The scheme a 401 was received against."""
+    if isinstance(scheme, RevocableAuthScheme):
+        scheme.invalidate()
+
+
+class AllSchemes:
+    """AND-composition: every configured member applies.
+
+    An unconfigured member contributes nothing and drops out on its own; the request still goes out
+    with whatever *was* configured. This layer never withholds a request over a partial set."""
+
+    __slots__ = ("_schemes",)
+
+    def __init__(self, *schemes: AuthScheme) -> None:
+        self._schemes = schemes
+
+    def apply(self) -> AuthParams:
+        applied = [scheme.apply() for scheme in self._schemes]
+        return AuthParams(
+            headers=tuple(p for a in applied for p in a.headers),
+            query_params=tuple(p for a in applied for p in a.query_params),
+            cookies=tuple(p for a in applied for p in a.cookies),
+        )
+
+    def invalidate(self) -> None:
+        """Drop every member's cached credential, via the module-level :func:`invalidate`.
+
+        Having this makes a composite itself revocable, so nesting one inside another propagates."""
+        for scheme in self._schemes:
+            invalidate(scheme)
+
+
+class AnySchemes:
+    """OR-composition: the first *configured* member applies.
+
+    Selection is on credential presence, never on "applying it did not fail" -- an unconfigured member
+    listed ahead of a configured one must not win and send the request unauthenticated. With nothing
+    configured the request goes out unauthenticated, as a single unconfigured scheme would."""
+
+    __slots__ = ("_schemes",)
+
+    def __init__(self, *schemes: AuthScheme) -> None:
+        self._schemes = schemes
+
+    def apply(self) -> AuthParams:
+        for scheme in self._schemes:
+            if is_configured(scheme):
+                return scheme.apply()
+        return AuthParams()
+
+    def invalidate(self) -> None:
+        """Drop every member's cached credential; see :meth:`AllSchemes.invalidate`.
+
+        Over-invalidates on purpose: which arm won the last :meth:`apply` is not tracked, and tracking
+        it would mean per-request state on an object every request shares."""
+        for scheme in self._schemes:
+            invalidate(scheme)
+
+
+class AsyncAllSchemes:
+    """:class:`AllSchemes` for the asynchronous client: a member may await its credential."""
+
+    __slots__ = ("_schemes",)
+
+    def __init__(self, *schemes: AsyncAuthScheme) -> None:
+        self._schemes = schemes
+
+    async def apply(self) -> AuthParams:
+        applied = [await resolve_auth(scheme) for scheme in self._schemes]
+        return AuthParams(
+            headers=tuple(p for a in applied for p in a.headers),
+            query_params=tuple(p for a in applied for p in a.query_params),
+            cookies=tuple(p for a in applied for p in a.cookies),
+        )
+
+    def invalidate(self) -> None:
+        """See :meth:`AllSchemes.invalidate`. Not a coroutine: dropping a cache never awaits."""
+        for scheme in self._schemes:
+            invalidate(scheme)
+
+
+class AsyncAnySchemes:
+    """:class:`AnySchemes` for the asynchronous client: the chosen member may await its credential.
+
+    Selection still happens without I/O, so only the one member that wins is ever resolved."""
+
+    __slots__ = ("_schemes",)
+
+    def __init__(self, *schemes: AsyncAuthScheme) -> None:
+        self._schemes = schemes
+
+    async def apply(self) -> AuthParams:
+        for scheme in self._schemes:
+            if is_configured(scheme):
+                return await resolve_auth(scheme)
+        return AuthParams()
+
+    def invalidate(self) -> None:
+        """See :meth:`AnySchemes.invalidate`, including why it over-invalidates."""
+        for scheme in self._schemes:
+            invalidate(scheme)

swagger_petstore_open_api_3_0/core/auth/models.py

@@ -0,0 +1,217 @@
+"""What every security scheme trades in, and the OAuth 2.0 vocabulary its grants share.
+
+:class:`AuthParams` is what one scheme contributes to a request. The rest is managed OAuth 2.0's
+grant-agnostic half: the token endpoint's success and error bodies (RFC 6749 §5.1 and §5.2, fixed for
+every provider, which is why they are runtime types at all), §2.3.1's client-authentication placements,
+§3.3's scope delimiter, and the scope vocabulary parameter every grant's credentials carry.
+
+The bottom of the auth layer. It names no protocol and no scheme, so ``protocols``, ``composition`` and
+``schemes/`` all import from here and nothing imports back. It performs no token request either --
+which is why no ``RawClient``, ``form_body`` or ``UrlTemplate`` appears below."""
+
+from __future__ import annotations
+
+from base64 import b64encode
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Any, Final, TypeAlias
+from urllib.parse import quote
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# ``TypeVar`` from here and not ``typing``: PEP 696 defaults reach ``typing`` at 3.13, and ``ScopeT``
+# below needs one at the 3.10 floor.
+from typing_extensions import TypeVar
+
+from .._internal.wire import text_values
+from ..decoding import ErrorMapper
+from ..params import Param, param
+from ..results import RawError
+from ..transport import HttpResponse
+
+
+@dataclass(frozen=True, slots=True)
+class AuthParams:
+    """What one scheme contributes to a request.
+
+    Held as :class:`Param` rather than plain strings, so a credential is validated, dumped and
+    encoded by the same code as an endpoint's own parameters."""
+
+    headers: tuple[Param[Any], ...] = ()
+    query_params: tuple[Param[Any], ...] = ()
+    cookies: tuple[Param[Any], ...] = ()
+
+    def request_headers(self) -> tuple[Param[Any], ...]:
+        """Every header this contributes, cookie pairs folded into one ``Cookie`` (RFC 6265).
+
+        Folding here rather than at each scheme is what lets two cookie-bearing schemes compose;
+        two ``Cookie`` parameters would see the second overwrite the first. This covers only what
+        *this request's* schemes contributed -- folding the jar across the API's, the endpoint's and
+        the caller's layers is ``_internal/headers.py``'s.
+
+        The jar is tested rather than the tuple, so cookies that all render to nothing contribute no
+        header at all instead of an empty one that would clobber a lower layer.
+
+        Returns:
+            The headers, plus one folded ``Cookie`` when any cookie was contributed."""
+        jar = "; ".join(f"{cookie.key}={value}" for cookie in self.cookies for value in text_values(cookie))
+        if not jar:
+            return self.headers
+
+        return *self.headers, param[str]("Cookie", jar)
+
+
+ScopeT = TypeVar("ScopeT", bound=str, default=str)
+"""A grant's scope vocabulary, as its flow declares it.
+
+Bound to ``str`` because RFC 6749 §3.3 puts scopes on the wire as space-delimited strings, and
+defaulted to it so an unparametrized credential means what it always did: any scope the provider
+accepts, which is also what a flow declaring no scopes emits."""
+
+
+class OAuth2Credentials(BaseModel):
+    """The base every OAuth 2.0 grant's credentials share, carrying one thing: their repr.
+
+    Each grant's credentials are generic over :data:`ScopeT`, and pydantic names a parametrized model
+    after its parametrization -- so an unhelped repr prints the flow's whole scope vocabulary in place
+    of the class a caller wrote. This restores the latter.
+
+    ⚠️ **It declares no fields, and must not gain one.** Pydantic orders a base's fields ahead of a
+    subclass's, so a field here would move to the front of every credential's repr and ``model_dump``.
+    A grant's own fields stay in its own model, which is also where ``model_config``, its ``coerce``
+    and its validators stay."""
+
+    def __repr_name__(self) -> str:
+        """The class name without its parametrization.
+
+        Returns:
+            The unsubscripted class's name, or this class's own when it was never subscripted."""
+        origin = type(self).__pydantic_generic_metadata__["origin"]
+        return origin.__name__ if origin is not None else type(self).__name__
+
+
+class OAuthToken(BaseModel):
+    """The token endpoint's success body (RFC 6749 §5.1), and what a token source returns.
+
+    ``expires_in`` is RECOMMENDED rather than required, so its absence means "no client-side
+    deadline". ``token_type`` is parsed because the RFC requires it and deliberately **not** used
+    when applying: echoing a wire keyword into ``Authorization`` would put unvalidated data there.
+
+    No ``refresh_token``: RFC 6749 §4.4.3 says the client-credentials grant SHOULD NOT be issued
+    one. A grant that may be returns :class:`OAuthTokenRefreshable` instead."""
+
+    model_config = ConfigDict(frozen=True)
+
+    access_token: str = Field(repr=False)
+    token_type: str
+    expires_in: int | None = None
+    scope: str | None = None
+
+
+class OAuthTokenRefreshable(OAuthToken):
+    """The token endpoint's success body for a grant that may issue a refresh token.
+
+    RFC 6749 §4.1.4 and §4.3.3 both make ``refresh_token`` OPTIONAL. A subclass rather than an
+    optional field, so a source's declared return type says which tier it belongs to."""
+
+    refresh_token: str | None = Field(default=None, repr=False)
+
+
+class OAuthProviderError(BaseModel):
+    """The token endpoint's error body (RFC 6749 §5.2).
+
+    Typed, unlike the rest of a failed token fetch, because §5.2 fixes these three members for every
+    provider."""
+
+    model_config = ConfigDict(frozen=True)
+
+    error: str
+    error_description: str | None = None
+    error_uri: str | None = None
+
+
+OAuthError: TypeAlias = OAuthProviderError | RawError
+"""What a failed token fetch carries: the RFC 6749 §5.2 body, or the raw response without one."""
+
+
+@dataclass(frozen=True, slots=True)
+class OAuthErrorResponse:
+    """Error mapper for the token endpoint.
+
+    The only mapper here that selects a *schema*, and it can: RFC 6749 §5.2 fixes one error body for
+    every provider. A response that does not conform becomes a :class:`RawError` rather than raising
+    out of the mapper, because a failed fetch must surface the provider's answer, not a parse error."""
+
+    def map(self, response: HttpResponse) -> OAuthError:
+        try:
+            return OAuthProviderError.model_validate(response.json())
+        except ValueError:
+            return RawError(response)
+
+
+oauth_error_response: Final[ErrorMapper[OAuthError]] = OAuthErrorResponse()
+
+
+OAuthParams: TypeAlias = tuple[Param[Any], ...]
+"""One destination's worth of parameters: half a token request, or an authorization URL's query."""
+
+CredentialsPlacement: TypeAlias = Callable[[str, str | None], tuple[OAuthParams, OAuthParams]]
+"""Where a client's own credentials travel on a token request: its headers, and its form fields.
+
+Named after the specification extension it is read from, ``x-oauth2-credentials-placement``.
+Grant-agnostic: RFC 6749 §2.3.1 authenticates the *client*, which every grant does identically."""
+
+
+def scope_params(scopes: Sequence[str] | None) -> OAuthParams:
+    """The ``scope`` field, or nothing at all when no scopes were asked for.
+
+    RFC 6749 §3.3's space delimiter, written once, so a caller passes a list and never learns it.
+    Takes a ``Sequence`` so a credential's narrowed ``list[ScopeT]`` reaches it without a copy.
+
+    Args:
+        scopes: The scopes to request; absent or empty asks for the client's defaults.
+
+    Returns:
+        One ``scope`` parameter, or an empty tuple."""
+    if not scopes:
+        return ()
+    return (param[str]("scope", " ".join(scopes)),)
+
+
+def client_secret_basic(client_id: str, client_secret: str | None) -> tuple[OAuthParams, OAuthParams]:
+    """RFC 6749 §2.3.1: the client authenticates with HTTP Basic on the token request.
+
+    Both halves are percent-encoded before base64, as §2.3.1 requires. A client with **no secret**
+    identifies itself with a ``client_id`` form field instead, which is §3.2.1's requirement exactly
+    then rather than a degraded fallback.
+
+    Args:
+        client_id: The client's identifier, as issued by the provider.
+        client_secret: Its secret, or ``None`` for a public client.
+
+    Returns:
+        The headers and the form fields the client's credentials contribute, in that order."""
+    if client_secret is None:
+        return (), (param[str]("client_id", client_id),)
+    raw = f"{quote(client_id, safe='')}:{quote(client_secret, safe='')}"
+    return (param[str]("Authorization", f"Basic {b64encode(raw.encode()).decode()}"),), ()
+
+
+def client_secret_post(client_id: str, client_secret: str | None) -> tuple[OAuthParams, OAuthParams]:
+    """RFC 6749 §2.3.1's alternative: the credentials travel in the form body instead.
+
+    The empty header tuple is the invariant, not an oversight -- carrying the pair in both places
+    would authenticate the client twice.
+
+    Args:
+        client_id: The client's identifier, as issued by the provider.
+        client_secret: Its secret, omitted entirely when ``None`` (§3.2.1).
+
+    Returns:
+        An empty header tuple, and the form fields the client's credentials contribute."""
+    if client_secret is None:
+        return (), (param[str]("client_id", client_id),)
+    return (), (
+        param[str]("client_id", client_id),
+        param[str]("client_secret", client_secret),
+    )