cliV1 0.0.8__py3-none-any.whl

swagger_petstore_open_api_3_0/core/auth/schemes/oauth2_password.py

@@ -0,0 +1,142 @@
+"""``oauth2`` / ``password`` -- RFC 6749 §4.3, the resource owner password credentials grant.
+
+Two credential pairs on one request: the resource owner's, always as form fields, and the client's
+own, wherever ``x-oauth2-credentials-placement`` puts them.
+
+**Plain tier, not refreshable.** §4.3.3 permits a refresh token here and this ignores it, so the
+resource owner's password is re-sent at every expiry -- the cost §10.7 warns about, taken
+deliberately (ADR-0019 decision 6). The refreshable tier is available to a generator that emits it;
+this API's client does not."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Generic, TypeAlias
+
+from pydantic import ConfigDict, Field
+from typing_extensions import NotRequired, TypedDict
+
+from ...bodies import form_body
+from ...decoding import async_json_decoder, json_decoder
+from ...params import UrlTemplate, param
+from ...raw_client import AsyncRawClient, RawClient
+from ..models import (
+    CredentialsPlacement,
+    OAuth2Credentials,
+    OAuthParams,
+    OAuthToken,
+    ScopeT,
+    oauth_error_response,
+    scope_params,
+)
+
+
+class PasswordCredentials(OAuth2Credentials, Generic[ScopeT]):
+    """The resource owner's credentials, plus the client's own (RFC 6749 §4.3.2).
+
+    ``client_secret`` is optional because a public client has none -- §3.2.1 then makes ``client_id``
+    the required identification, which the placement function writes. ``scopes`` is typed by the
+    flow's declared vocabulary, as every grant's is."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    client_id: str
+    client_secret: str | None = Field(default=None, repr=False)
+    username: str
+    password: str = Field(repr=False)
+    scopes: list[ScopeT] | None = None
+
+    @classmethod
+    def coerce(cls, value: PasswordCredentialsOrDict[ScopeT]) -> PasswordCredentials[ScopeT]:
+        """Accept either spelling, validating the mapping form.
+
+        Args:
+            value: The credential, as the typed model or as a mapping.
+
+        Returns:
+            The validated model; see :meth:`BasicAuthCredentials.coerce` for why it takes no
+            ``None``.
+
+        Raises:
+            ValidationError: If the mapping is missing a key, carries an unknown one, or names a
+                scope this flow does not declare."""
+        if isinstance(value, cls):
+            return value
+        return cls.model_validate(value)
+
+
+class PasswordCredentialsDict(TypedDict, Generic[ScopeT]):
+    client_id: str
+    client_secret: NotRequired[str | None]
+    username: str
+    password: str
+    scopes: NotRequired[list[ScopeT] | None]
+
+
+PasswordCredentialsOrDict: TypeAlias = PasswordCredentials[ScopeT] | PasswordCredentialsDict[ScopeT]
+"""What a password credential accepts: the typed model, or a mapping of the same keys."""
+
+
+def _token_params(credentials: PasswordCredentials[ScopeT]) -> OAuthParams:
+    """RFC 6749 §4.3.2's token request, less the client's own half.
+
+    Shared by both flavours rather than duplicated, so an edit cannot land in one only.
+
+    Args:
+        credentials: The configured password credentials.
+
+    Returns:
+        The ``grant_type``, the resource owner's pair and the scopes. The client's half is
+        deliberately absent: it comes from the source's ``placement``."""
+    return (
+        param[str]("grant_type", "password"),
+        param[str]("username", credentials.username),
+        param[str]("password", credentials.password),
+        *scope_params(credentials.scopes),
+    )
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class PasswordTokenSource(Generic[ScopeT]):
+    """The built-in :class:`TokenSource` for the password grant: POST the token request.
+
+    ``placement`` is read from the flow's own ``x-oauth2-credentials-placement`` by the generated
+    client, exactly as the client-credentials source's is. Carries no ``auth_scheme=`` -- the
+    credentials are on this request already, so the fetch provably cannot recurse into itself."""
+
+    client: RawClient
+    token_url: UrlTemplate
+    placement: CredentialsPlacement
+
+    def fetch(self, credentials: PasswordCredentials[ScopeT]) -> OAuthToken:
+        headers, client_params = self.placement(credentials.client_id, credentials.client_secret)
+        return self.client.execute(
+            http_method="POST",
+            url_template=self.token_url,
+            headers=headers,
+            body=form_body(*_token_params(credentials), *client_params),
+            decoder=json_decoder[OAuthToken],
+            error_mapper=oauth_error_response,
+        ).unwrap()
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AsyncPasswordTokenSource(Generic[ScopeT]):
+    """:class:`PasswordTokenSource` for the asynchronous client: the request is awaited."""
+
+    client: AsyncRawClient
+    token_url: UrlTemplate
+    placement: CredentialsPlacement
+
+    async def fetch(self, credentials: PasswordCredentials[ScopeT]) -> OAuthToken:
+        headers, client_params = self.placement(credentials.client_id, credentials.client_secret)
+        return (
+            await self.client.execute(
+                http_method="POST",
+                url_template=self.token_url,
+                headers=headers,
+                body=form_body(*_token_params(credentials), *client_params),
+                decoder=async_json_decoder[OAuthToken],
+                error_mapper=oauth_error_response,
+            )
+        ).unwrap()

swagger_petstore_open_api_3_0/core/auth/schemes/oauth2_schemes.py

@@ -0,0 +1,300 @@
+"""Managed OAuth 2.0's caching schemes: two tiers, four classes, and no fetching code at all.
+
+:class:`OAuth2Scheme` owns the token cache, the deadline, ``invalidate`` and the ``Bearer``
+application, and obtains a token by calling ``source.fetch(credentials)``.
+:class:`OAuth2RefreshableScheme` is its sibling for a grant whose endpoint may issue a refresh token,
+and prefers a refresh over a re-acquisition. Two tiers and not one with a flag: client credentials can
+never reach a refresh branch (RFC 6749 §4.4.3), so making that branch reachable would need an
+``isinstance`` on the token.
+
+The one module in this directory that names no grant, which is what lets four classes serve every one."""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+import time
+from dataclasses import dataclass, field
+from math import inf
+from typing import Final, Generic, TypeVar
+
+from ...params import param
+from ..models import AuthParams, OAuthToken, OAuthTokenRefreshable
+from ..protocols import (
+    AsyncRefreshableTokenSource,
+    AsyncTokenSource,
+    RefreshableTokenSource,
+    TokenSource,
+)
+
+CredentialsT = TypeVar("CredentialsT")
+"""A grant's credentials, as the scheme holds them.
+
+Declared here and not beside its contravariant twin in ``protocols``: the four classes below are its
+only consumers."""
+
+_EXPIRY_BUFFER_SECONDS: Final = 30.0
+
+
+@dataclass(frozen=True, slots=True)
+class _CachedToken:
+    """An access token and the monotonic instant it stops being usable.
+
+    One object rather than two fields on the scheme, so the lock-free fast path reads a *single*
+    attribute and can never observe a new token beside a stale deadline."""
+
+    access_token: str = field(repr=False)
+    expires_at: float
+
+    def is_expired(self) -> bool:
+        return time.monotonic() >= self.expires_at
+
+
+def _expires_at(expires_in: int | None) -> float:
+    """The monotonic instant a token issued *now* stops being usable.
+
+    ``time.monotonic``, because ``expires_in`` is a duration and a wall clock an NTP step can move
+    does not measure one. Named for the conversion it performs: a duration in, an instant out.
+
+    Args:
+        expires_in: RFC 6749 §5.1's lifetime in seconds; ``None`` or non-positive means no
+            client-side deadline, and the token is cached until a 401 dislodges it.
+
+    Returns:
+        The monotonic deadline, or ``inf`` when there is none."""
+    if expires_in is None or expires_in <= 0:
+        return inf
+
+    # ``max``, not a flat subtraction: subtracting outright is non-monotonic near the buffer, so a
+    # longer-lived token would be cached for less time. The two cross at 60 s.
+    return time.monotonic() + max(expires_in - _EXPIRY_BUFFER_SECONDS, expires_in / 2)
+
+
+def _cache(token: OAuthToken) -> _CachedToken:
+    """Deadline a token on the monotonic clock.
+
+    Args:
+        token: The token endpoint's success body.
+
+    Returns:
+        The cache entry: the token, plus the deadline :func:`_expires_at` computes for it."""
+    return _CachedToken(token.access_token, _expires_at(token.expires_in))
+
+
+@dataclass(frozen=True, slots=True)
+class _CachedRefreshableToken:
+    """:class:`_CachedToken` plus the refresh token that outlives it.
+
+    A sibling rather than a third field, so a scheme over a grant that cannot be issued a refresh
+    token has none to read. Frozen and fully built before publication, for its sibling's reason."""
+
+    access_token: str = field(repr=False)
+    expires_at: float
+    refresh_token: str | None = field(repr=False)
+
+    def is_expired(self) -> bool:
+        return time.monotonic() >= self.expires_at
+
+
+def _cache_refreshable(token: OAuthTokenRefreshable, previous: str | None) -> _CachedRefreshableToken:
+    """Deadline a refreshable token, keeping ``previous`` when the response omitted one.
+
+    RFC 6749 §6: a refresh response MAY omit ``refresh_token``, and the previously-issued one stays
+    valid when it does.
+
+    Args:
+        token: The token endpoint's success body.
+        previous: The refresh token that bought this response; ``None`` on a first acquisition.
+
+    Returns:
+        The cache entry, carrying whichever refresh token is still valid."""
+    return _CachedRefreshableToken(
+        token.access_token,
+        _expires_at(token.expires_in),
+        token.refresh_token if token.refresh_token is not None else previous,
+    )
+
+
+class OAuth2Scheme(Generic[CredentialsT]):
+    """A bearer token obtained through a :class:`TokenSource` and cached until it expires.
+
+    Grant-agnostic, and holds no fetching code of its own: it calls ``source.fetch(credentials)``.
+    Acquisition is lazy and one instance serves a client's whole life, so the cache does too. Not
+    frozen -- the token cache is the one thing a scheme legitimately mutates."""
+
+    __slots__ = ("_cached", "_credentials", "_lock", "_source")
+
+    def __init__(self, *, credentials: CredentialsT, source: TokenSource[CredentialsT]) -> None:
+        self._credentials = credentials
+        self._source = source
+        self._lock = threading.Lock()
+        self._cached: _CachedToken | None = None
+
+    def apply(self) -> AuthParams:
+        token = self._get_and_cache_token()
+        return AuthParams(headers=(param[str]("Authorization", f"Bearer {token}"),))
+
+    def invalidate(self) -> None:
+        """Drop the cached token, so the next request obtains a new one."""
+        self._cached = None
+
+    def _get_and_cache_token(self) -> str:
+        """The cached access token, obtaining and caching one when none is fresh.
+
+        Double-checked: the fast path is one lock-free attribute read, and the second check inside
+        the lock is what makes a burst of concurrent requests pay for **one** acquisition.
+
+        Returns:
+            The access token to apply."""
+        cached = self._cached
+        if cached is not None and not cached.is_expired():
+            return cached.access_token
+
+        with self._lock:
+            cached = self._cached
+            if cached is not None and not cached.is_expired():
+                return cached.access_token
+
+            cached = _cache(self._source.fetch(self._credentials))
+            self._cached = cached
+            return cached.access_token
+
+
+class AsyncOAuth2Scheme(Generic[CredentialsT]):
+    """:class:`OAuth2Scheme` for the asynchronous client: the token is awaited.
+
+    The lock is an ``asyncio.Lock``, which binds to the running loop on first *use* rather than at
+    construction, so building the client outside a loop is fine. Thereafter the scheme belongs to
+    one loop -- the same constraint the connection pool beside it already imposes."""
+
+    __slots__ = ("_cached", "_credentials", "_lock", "_source")
+
+    def __init__(self, *, credentials: CredentialsT, source: AsyncTokenSource[CredentialsT]) -> None:
+        self._credentials = credentials
+        self._source = source
+        self._lock = asyncio.Lock()
+        self._cached: _CachedToken | None = None
+
+    async def apply(self) -> AuthParams:
+        token = await self._get_and_cache_token()
+        return AuthParams(headers=(param[str]("Authorization", f"Bearer {token}"),))
+
+    def invalidate(self) -> None:
+        """Drop the cached token, so the next request obtains a new one."""
+        self._cached = None
+
+    async def _get_and_cache_token(self) -> str:
+        """See :meth:`OAuth2Scheme._get_and_cache_token`; the source may need to be awaited.
+
+        Returns:
+            The access token to apply."""
+        cached = self._cached
+        if cached is not None and not cached.is_expired():
+            return cached.access_token
+
+        async with self._lock:
+            cached = self._cached
+            if cached is not None and not cached.is_expired():
+                return cached.access_token
+
+            cached = _cache(await self._source.fetch(self._credentials))
+            self._cached = cached
+            return cached.access_token
+
+
+class OAuth2RefreshableScheme(Generic[CredentialsT]):
+    """:class:`OAuth2Scheme` for a grant whose token endpoint may issue a refresh token.
+
+    **Refreshing is preferred over re-acquiring**, which is the whole value of the tier: for the
+    authorization-code grant a re-acquisition runs the caller's prompt again. :meth:`invalidate`
+    drops the refresh token too, so a 401 is answered by a full re-acquisition."""
+
+    __slots__ = ("_cached", "_credentials", "_lock", "_source")
+
+    def __init__(self, *, credentials: CredentialsT, source: RefreshableTokenSource[CredentialsT]) -> None:
+        self._credentials = credentials
+        self._source = source
+        self._lock = threading.Lock()
+        self._cached: _CachedRefreshableToken | None = None
+
+    def apply(self) -> AuthParams:
+        token = self._get_and_cache_token()
+        return AuthParams(headers=(param[str]("Authorization", f"Bearer {token}"),))
+
+    def invalidate(self) -> None:
+        """Drop the cached token, so the next request acquires a new one from scratch."""
+        self._cached = None
+
+    def _get_and_cache_token(self) -> str:
+        """The cached access token, refreshing or re-acquiring when none is fresh.
+
+        Double-checked as :meth:`OAuth2Scheme._get_and_cache_token` is, with one branch added: a
+        stale entry still carrying a refresh token is worth one attempt first. The fallback calls
+        ``fetch``, which for an interactive grant blocks on a human *while this lock is held*.
+
+        Returns:
+            The access token to apply."""
+        cached = self._cached
+        if cached is not None and not cached.is_expired():
+            return cached.access_token
+
+        with self._lock:
+            cached = self._cached
+            if cached is not None and not cached.is_expired():
+                return cached.access_token
+
+            if cached is not None and cached.refresh_token is not None:
+                refreshed = self._source.refresh(self._credentials, cached.refresh_token)
+                if refreshed is not None:
+                    acquired = _cache_refreshable(refreshed, cached.refresh_token)
+                    self._cached = acquired
+                    return acquired.access_token
+
+            acquired = _cache_refreshable(self._source.fetch(self._credentials), None)
+            self._cached = acquired
+            return acquired.access_token
+
+
+class AsyncOAuth2RefreshableScheme(Generic[CredentialsT]):
+    """:class:`OAuth2RefreshableScheme` for the asynchronous client: both source calls are awaited."""
+
+    __slots__ = ("_cached", "_credentials", "_lock", "_source")
+
+    def __init__(self, *, credentials: CredentialsT, source: AsyncRefreshableTokenSource[CredentialsT]) -> None:
+        self._credentials = credentials
+        self._source = source
+        self._lock = asyncio.Lock()
+        self._cached: _CachedRefreshableToken | None = None
+
+    async def apply(self) -> AuthParams:
+        token = await self._get_and_cache_token()
+        return AuthParams(headers=(param[str]("Authorization", f"Bearer {token}"),))
+
+    def invalidate(self) -> None:
+        """Drop the cached token, so the next request acquires a new one from scratch."""
+        self._cached = None
+
+    async def _get_and_cache_token(self) -> str:
+        """See :meth:`OAuth2RefreshableScheme._get_and_cache_token`; both source calls are awaited.
+
+        Returns:
+            The access token to apply."""
+        cached = self._cached
+        if cached is not None and not cached.is_expired():
+            return cached.access_token
+
+        async with self._lock:
+            cached = self._cached
+            if cached is not None and not cached.is_expired():
+                return cached.access_token
+
+            if cached is not None and cached.refresh_token is not None:
+                refreshed = await self._source.refresh(self._credentials, cached.refresh_token)
+                if refreshed is not None:
+                    acquired = _cache_refreshable(refreshed, cached.refresh_token)
+                    self._cached = acquired
+                    return acquired.access_token
+
+            acquired = _cache_refreshable(await self._source.fetch(self._credentials), None)
+            self._cached = acquired
+            return acquired.access_token

swagger_petstore_open_api_3_0/core/base_raw_response.py

@@ -0,0 +1,49 @@
+"""What the generated per-group raw-response classes share: a raw client, a server, its auth."""
+
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+from .raw_client import RawClientT
+
+ServerT = TypeVar("ServerT")
+"""The generated ``Server`` type a subclass carries.
+
+Unbounded and never touched by the runtime: its only purpose is to let this class hold the server
+without *naming* it, since the runtime is copied verbatim into every generated SDK. A plain
+attribute typed ``Any`` would lose what subclasses need -- that ``self._server.prism(...)``
+type-checks."""
+
+AuthT = TypeVar("AuthT")
+"""The generated scheme holder a *secured* subclass carries.
+
+Unbounded for the same reason as ``ServerT``, so ``self._auth.basic_auth`` type-checks in a
+generated endpoint while the runtime stays free of any upward import. It is also what keeps the two
+flavors' schemes apart, so a scheme that can only work on one transport cannot be handed to the
+other."""
+
+
+class BaseRawResponse(Generic[RawClientT, ServerT]):
+    """Base for the internal per-group raw-response classes.
+
+    Holds the raw client and the server, both type parameters a subclass fixes, so
+    ``self._client.execute(...)`` resolves to the right flavor and ``self._server`` to the concrete
+    generated ``Server``. A group whose operations declare no ``security`` extends **this**, and so
+    has no ``self._auth`` to name; one that does extends :class:`SecuredRawResponse`."""
+
+    def __init__(self, client: RawClientT, server: ServerT) -> None:
+        self._client = client
+        self._server = server
+
+
+class SecuredRawResponse(BaseRawResponse[RawClientT, ServerT], Generic[RawClientT, ServerT, AuthT]):
+    """Base for a group at least one of whose operations declares ``security``.
+
+    Adds the API's security schemes as a third parameter a subclass fixes. Two classes rather than
+    one optional argument, because the split makes the reach of a credential checkable: a group that
+    declares no ``security`` cannot name ``self._auth``, so a generator writing ``auth=self._auth.``
+    into the wrong file fails to type-check instead of shipping a credential."""
+
+    def __init__(self, client: RawClientT, server: ServerT, auth: AuthT) -> None:
+        super().__init__(client, server)
+        self._auth = auth