cliV1 0.0.7__py3-none-any.whl

swagger_petstore_open_api_3_1_0/core/optionality.py

@@ -0,0 +1,144 @@
+"""The unset sentinel and the states it enables: omitted vs ``null`` vs a value.
+
+:data:`UNSET` marks a field the caller never touched and :func:`strip_unset` is where "omitted" is
+recovered at dump time, by dropping any key whose live value is still the sentinel. Two annotations
+admit it, one per spelling a spec can declare: :data:`Optional` for a property that may be omitted,
+:data:`OptionalNullable` for one that may be omitted *or* explicitly ``null``. See
+``docs/designs/optional-nullable-fields.md``.
+
+:data:`Optional` is deliberately **not** ``typing.Optional``. Here it means ``T | UnsetType`` --
+present or absent, with no ``None`` arm -- where ``typing.Optional[T]`` means ``T | None``. They
+differ by exactly the arm that matters: a property the spec does not declare nullable must not be
+able to reach the wire as ``null``, so passing ``None`` to one of these fields is a type error
+rather than a value that serializes. Nothing in a generated SDK imports ``typing.Optional`` -- unions
+are spelled with PEP 604 ``|`` -- so the two never appear in the same module.
+
+Both are plain generic aliases, not ``TypeAliasType``. pydantic substitutes a ``TypeAliasType``'s
+parameter itself and folds ``Any | T`` into ``Any`` while doing so, which would take the sentinel arm
+out of ``Optional[Any]`` -- the spelling of a property with no ``type``. ``typing`` substitutes a
+plain alias and keeps the arm; mypy reads the two forms alike. See ADR-0071."""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar, Final, Literal, TypeAlias, TypeVar, cast, final
+
+from pydantic import BaseModel, GetCoreSchemaHandler
+from pydantic_core import PydanticSerializationUnexpectedValue, core_schema
+
+
+@final
+class UnsetType:
+    """Marks a field the caller never touched, distinct from one set to ``None``.
+
+    Only ever seen as a field's default -- never constructed or passed by a caller. Dumps
+    as plain ``None`` through pydantic's normal fast path (see :func:`strip_unset` for
+    where the tri-state is actually recovered), and dumps nothing else: a value its union's
+    real arm failed to serialize is refused here, so it raises instead of going out as ``null``.
+    See ``docs/designs/optional-nullable-fields.md``.
+
+    A singleton, and identity-stable through every channel that could duplicate it: ``UnsetType()``
+    returns the existing instance, ``copy`` and ``deepcopy`` return it unchanged, and unpickling
+    reduces back through the constructor. Without that, ``model_copy(deep=True)`` would deep-copy
+    the sentinel into a *second* object, and ``field is UNSET`` -- the natural way to test for
+    it -- would start returning ``False`` on the copy. :func:`strip_unset` uses ``isinstance`` and
+    so is immune either way, but callers should not have to know that. ``final`` is the same
+    guarantee stated statically: a subclass would inherit ``_instance`` already set, so its
+    constructor would hand back a ``UnsetType`` rather than an instance of itself."""
+
+    _instance: ClassVar[UnsetType | None] = None
+
+    def __new__(cls) -> UnsetType:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __bool__(self) -> Literal[False]:
+        return False
+
+    def __repr__(self) -> str:
+        return "UNSET"
+
+    def __copy__(self) -> UnsetType:
+        return self
+
+    def __deepcopy__(self, memo: dict[int, Any]) -> UnsetType:
+        return self
+
+    def __reduce__(self) -> tuple[type[UnsetType], tuple[()]]:
+        # Protocols >= 2 reduce via ``cls.__new__(cls)`` and reach the guard above by luck of
+        # protocol; 0 and 1 reconstruct through ``copyreg._reconstructor``, which calls
+        # ``object.__new__`` and bypasses ``__new__`` entirely -- measured, ``restored is UNSET``
+        # was ``False`` at both. Reducing to a plain call makes every protocol uniform.
+        return (UnsetType, ())
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source_type: Any, handler: GetCoreSchemaHandler) -> core_schema.CoreSchema:
+        return core_schema.is_instance_schema(
+            cls, serialization=core_schema.plain_serializer_function_ser_schema(cls._dump)
+        )
+
+    @staticmethod
+    def _dump(value: object) -> None:
+        # pydantic offers a union's value to each arm until one serializes it. Answering None for
+        # anything made this arm the catch-all: a list its own arm failed on went out as null.
+        # PydanticSerializationUnexpectedValue is pydantic's "not this arm" signal.
+        if isinstance(value, UnsetType):
+            return None
+        raise PydanticSerializationUnexpectedValue(f"Expected UNSET, got {type(value).__name__}")
+
+
+UNSET: Final = UnsetType()
+
+T = TypeVar("T")
+Optional: TypeAlias = T | UnsetType
+OptionalNullable: TypeAlias = T | None | UnsetType
+
+DumpedT = TypeVar("DumpedT")
+
+
+def strip_unset(value: object, dumped: DumpedT) -> DumpedT:
+    """Recursively drop any dumped key whose live field value is :class:`UnsetType`.
+
+    Walks ``value`` (the validated model, list or dict, pre-dump) alongside ``dumped`` (its
+    ``mode="json"`` dump) so a field that dumped as ``None`` only because it defaulted to
+    ``UNSET`` is omitted, while one explicitly set to ``None`` stays ``null``.
+
+    The mapping branch pairs the two by *key* rather than by position, because ``mode="json"``
+    renders a non-``str`` key as text (``{1: "x"}`` dumps as ``{"1": "x"}``): an entry the dump
+    renamed keeps its dumped form instead of misaligning the walk. ``list`` and ``dict`` are the
+    whole container set on purpose -- an array and a map are what a spec can express, so they are
+    the only shapes an emitted declared type nests, and they are the same two ``adapters.py``
+    descends. A ``tuple`` or ``set`` passes through like any other value.
+
+    Shape-preserving: a dict in, a dict out; a list in, a list out. The three ``cast`` calls
+    are that invariant, which mypy cannot verify through the rebuild -- they keep the
+    imprecision here rather than returning ``Any`` to every caller.
+
+    Args:
+        value: The validated model, list or dict, before dumping -- the side that still
+            holds the sentinel.
+        dumped: That same value's ``mode="json"`` dump, walked alongside it.
+
+    Returns:
+        ``dumped`` with every never-touched key removed, in the shape it arrived in."""
+    if isinstance(value, BaseModel):
+        result = dict(cast(Any, dumped))
+        for name, field in type(value).model_fields.items():
+            # ``dumped`` may be keyed by wire alias (the default) or by Python name
+            # (``to_dict(by_alias=False)``); prefer whichever spelling is actually there.
+            key = field.alias if field.alias is not None and field.alias in result else name
+            if key not in result:
+                continue
+            attr = getattr(value, name)
+            if isinstance(attr, UnsetType):
+                del result[key]
+            else:
+                result[key] = strip_unset(attr, result[key])
+        return cast(DumpedT, result)
+    if isinstance(value, list) and isinstance(dumped, list):
+        stripped = [strip_unset(item, d) for item, d in zip(value, dumped, strict=True)]
+        return cast(DumpedT, stripped)
+    if isinstance(value, dict) and isinstance(dumped, dict):
+        stripped_values = {key: strip_unset(value[key], item) if key in value else item for key, item in dumped.items()}
+        return cast(DumpedT, stripped_values)
+    return dumped

swagger_petstore_open_api_3_1_0/core/pagination.py

@@ -0,0 +1,452 @@
+"""Pagination: the five paging states, their factories, and the sync and async loops that walk them.
+
+A state holds the value that moves from page to page (an offset, a page number, a cursor, a key, or the next
+page's URL and query) and the selectors the endpoint uses to read the next move off a response. After each
+successful page the loop calls ``advance``, which returns the next state, or ``None`` to stop.
+
+States are frozen. ``advance`` returns a copy made with ``dataclasses.replace`` that changes only the moving
+value, so the selectors stay with the walk. The stop rules, and the order they are checked in, match the C#
+SDK. A state never advances to the value it just sent, so a server that keeps returning the same page ends
+the walk instead of looping forever. A selector over an ``OptionalNullable`` field may return ``UNSET``;
+every stop rule treats that as no answer.
+
+An endpoint never names a state class. It calls a factory with the page model as a subscript, such as
+``offset_state[Products](…)``. The subscript types the selectors, so a mistake inside one fails the build.
+The factory returns the class itself, because Python 3.10 cannot construct a frozen, slotted dataclass
+through a ``typing`` subscript. Calling a factory without its subscript fails the build.
+
+``paginate`` and ``async_paginate`` run the loop: fetch the page for the current state, yield the result,
+stop after a ``Failure``, then ask ``advance`` for the next state. The result is yielded before it is
+checked, so a ``Failure`` is the last page the caller sees rather than one that is dropped. Each page is a
+full ``execute``, so auth, retries, the idempotency key and ``request_options`` apply to every page.
+Building a paginator sends nothing; the first request goes out when iteration starts, which is why neither
+function is a coroutine.
+
+Each function has one ``@overload`` per state class. The overload keeps the state's own class inside the
+endpoint's ``fetch_page`` lambda, so ``state.offset`` resolves, and ties the state's page type to the
+decoder's, so a mismatch fails the build. The implementation takes the union of all five states and mypy
+checks it against every overload. A new strategy needs a new state, factory, pair of overloads and
+``PagingState`` arm, and nothing else.
+
+``results.unwrap`` turns a paginator of results into a paginator of payloads; that is the parsed mode."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator, Mapping, Sequence
+from dataclasses import dataclass, replace
+from typing import Any, Final, Generic, TypeAlias, TypeVar, overload
+from urllib.parse import parse_qsl, urljoin, urlsplit
+
+from typing_extensions import TypeForm
+
+from ._internal.subscripts import SubscriptOnly
+from ._internal.urls import build_url
+from .optionality import OptionalNullable, UnsetType
+from .paginator import AsyncPaginator, Paginator
+from .params import Param, SerializationFormat, UrlTemplate, param
+from .results import ApiResult, Success, unwrap
+
+PayloadT = TypeVar("PayloadT")
+E = TypeVar("E")
+ItemT = TypeVar("ItemT")
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class OffsetState(Generic[PayloadT]):
+    """Moves by the number of items each page returned.
+
+    The next offset is the current offset (``None`` counts as ``0``) plus ``item_count``. The walk stops, in
+    this order: when the next offset reaches ``total_items``; when the page was empty; when ``has_more``
+    returns ``False``; or when there is no total and the page has fewer items than ``limit``. If ``has_more``
+    returns ``True``, the walk continues and the last rule is skipped."""
+
+    offset: int | None
+    limit: int | None
+    item_count: Callable[[PayloadT], int]
+    has_more: Callable[[PayloadT, Mapping[str, str]], OptionalNullable[bool]] | None = None
+    total_items: Callable[[PayloadT, Mapping[str, str]], OptionalNullable[int]] | None = None
+
+    def advance(self, *, payload: PayloadT, headers: Mapping[str, str]) -> OffsetState[PayloadT] | None:
+        """Return the next state, or ``None`` when a stop rule applies."""
+        data_count = self.item_count(payload)
+        current_offset = self.offset if self.offset is not None else 0
+        next_offset = current_offset + data_count
+        total_items = self.total_items(payload, headers) if self.total_items is not None else None
+        if isinstance(total_items, int) and next_offset >= total_items:
+            return None
+        if next_offset == current_offset:
+            return None
+        has_more = self.has_more(payload, headers) if self.has_more is not None else None
+        if isinstance(has_more, bool):
+            return replace(self, offset=next_offset) if has_more else None
+        if not isinstance(total_items, int) and self.limit is not None and data_count < self.limit:
+            return None
+        return replace(self, offset=next_offset)
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class PageState(Generic[PayloadT]):
+    """Moves by a 1-based page number.
+
+    The next page is the current page (``None`` counts as ``1``) plus one. The walk stops, in this order: when
+    the current page has reached ``total_pages``; when ``has_more`` returns ``False``; when the page was empty;
+    or when there is no total and the page has fewer items than ``limit``. If ``has_more`` returns ``True``,
+    the walk continues and the last two rules are skipped."""
+
+    page: int | None
+    limit: int | None
+    item_count: Callable[[PayloadT], int]
+    has_more: Callable[[PayloadT, Mapping[str, str]], OptionalNullable[bool]] | None = None
+    total_pages: Callable[[PayloadT, Mapping[str, str]], OptionalNullable[int]] | None = None
+
+    def advance(self, *, payload: PayloadT, headers: Mapping[str, str]) -> PageState[PayloadT] | None:
+        """Return the next state, or ``None`` when a stop rule applies."""
+        total_pages = self.total_pages(payload, headers) if self.total_pages is not None else None
+        current_page = self.page if self.page is not None else 1
+        if isinstance(total_pages, int) and current_page >= total_pages:
+            return None
+        has_more = self.has_more(payload, headers) if self.has_more is not None else None
+        if isinstance(has_more, bool):
+            return replace(self, page=current_page + 1) if has_more else None
+        count = self.item_count(payload)
+        if count == 0:
+            return None
+        if not isinstance(total_pages, int) and self.limit is not None and count < self.limit:
+            return None
+        return replace(self, page=current_page + 1)
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class CursorState(Generic[PayloadT]):
+    """Moves by the cursor each page returns.
+
+    The walk stops when the next cursor is missing, empty or ``UNSET``, when it equals the cursor just sent,
+    or when ``has_more`` returns ``False``. There is no ``count < limit`` rule on purpose: a short page that
+    still has a cursor does not mean the collection has ended."""
+
+    cursor: str | None
+    next_cursor: Callable[[PayloadT, Mapping[str, str]], OptionalNullable[str]]
+    has_more: Callable[[PayloadT, Mapping[str, str]], OptionalNullable[bool]] | None = None
+
+    def advance(self, *, payload: PayloadT, headers: Mapping[str, str]) -> CursorState[PayloadT] | None:
+        """Return the next state, or ``None`` when a stop rule applies."""
+        next_cursor = self.next_cursor(payload, headers)
+        if not next_cursor:
+            return None
+        if next_cursor == self.cursor:
+            return None
+        if self.has_more is not None and self.has_more(payload, headers) is False:
+            return None
+        return replace(self, cursor=next_cursor)
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class KeysetState(Generic[PayloadT]):
+    """Moves by a key read from the page just received, usually the last item's id.
+
+    The walk stops, in this order: when the page was empty; when ``has_more`` returns ``False``; when
+    ``has_more`` gives no answer and the page has fewer items than ``limit``; or when the next key is ``None``,
+    ``UNSET`` or equal to the key just sent. ``""`` is a valid key, not a missing one."""
+
+    key: str | None
+    limit: int | None
+    item_count: Callable[[PayloadT], int]
+    next_key: Callable[[PayloadT, Mapping[str, str]], OptionalNullable[str]]
+    has_more: Callable[[PayloadT, Mapping[str, str]], OptionalNullable[bool]] | None = None
+
+    def advance(self, *, payload: PayloadT, headers: Mapping[str, str]) -> KeysetState[PayloadT] | None:
+        """Return the next state, or ``None`` when a stop rule applies."""
+        count = self.item_count(payload)
+        if count == 0:
+            return None
+        has_more = self.has_more(payload, headers) if self.has_more is not None else None
+        if has_more is False:
+            return None
+        if not isinstance(has_more, bool) and self.limit is not None and count < self.limit:
+            return None
+        next_key = self.next_key(payload, headers)
+        if next_key is None or isinstance(next_key, UnsetType) or next_key == self.key:
+            return None
+        return replace(self, key=next_key)
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class LinkState(Generic[PayloadT]):
+    """Moves by following the next-page link a response gives, in its body or its ``Link`` header.
+
+    ``path_params`` fill the placeholders of the first ``url_template``. Following a link replaces
+    ``url_template`` (with the link's path), ``path_params`` (with none, since that path is literal) and
+    ``query_params`` (with its query). The link is resolved against the URL this state renders and must keep
+    its scheme, host and port; a link to another origin raises instead of being followed. The walk stops when
+    the next link is missing, empty or ``UNSET``, or when it renders to the same URL as this state."""
+
+    url_template: UrlTemplate
+    path_params: Sequence[Param[Any]] = ()
+    query_params: Sequence[Param[Any]]
+    next_link: Callable[[PayloadT, Mapping[str, str]], OptionalNullable[str]]
+
+    def advance(self, *, payload: PayloadT, headers: Mapping[str, str]) -> LinkState[PayloadT] | None:
+        """Return the state for the page's next link, or ``None`` when the walk stops.
+
+        Raises:
+            ValueError: If the link points to another origin, or its port is not a number."""
+        next_link = self.next_link(payload, headers)
+        if not next_link:
+            return None
+        current_url = build_url(self.url_template, path_params=self.path_params, query_params=self.query_params)
+        next_template, link_params = _resolve_next_link(current_url, next_link)
+        if build_url(next_template, query_params=link_params) == current_url:
+            return None
+        return replace(self, url_template=next_template, path_params=(), query_params=link_params)
+
+
+def _resolve_next_link(current_url: str, next_link: str) -> tuple[UrlTemplate, tuple[Param[Any], ...]]:
+    """Resolve ``next_link`` against ``current_url`` and split it into a URL template and query parameters.
+
+    Scheme, host and port are compared as written; default ports are not filled in. Each query key becomes one
+    ``Param[list[str]]`` rendered ``PLAIN``, so a repeated key keeps one pair per value, in the link's order.
+    Blank values are kept. A link with no path gets ``/``.
+
+    Raises:
+        ValueError: If the resolved link's scheme, host or port differs from ``current_url``'s."""
+    current = urlsplit(current_url)
+    resolved = urlsplit(urljoin(current_url, next_link))
+    if resolved.scheme != current.scheme or resolved.hostname != current.hostname or resolved.port != current.port:
+        raise ValueError(
+            f"Cross-origin pagination link '{resolved.scheme}://{resolved.netloc}' does not match the origin of the "
+            f"URL just fetched, '{current.scheme}://{current.netloc}'."
+        )
+    grouped: dict[str, list[str]] = {}
+    for key, value in parse_qsl(resolved.query, keep_blank_values=True):
+        grouped.setdefault(key, []).append(value)
+    link_params = tuple(
+        param[list[str]](key, values, serialization_format=SerializationFormat.PLAIN) for key, values in grouped.items()
+    )
+    return UrlTemplate(base_url=f"{resolved.scheme}://{resolved.netloc}", path=resolved.path or "/"), link_params
+
+
+class _OffsetStateFactory(SubscriptOnly):
+    """``offset_state[PayloadT](…)`` builds a :class:`OffsetState` whose selectors read ``PayloadT``."""
+
+    __slots__ = ()
+    factory_name = "offset_state"
+    spelling = "offset_state[PayloadT](…), e.g. offset_state[Products](offset=offset, limit=limit, item_count=…)"
+
+    def __getitem__(self, declared: TypeForm[PayloadT]) -> type[OffsetState[PayloadT]]:
+        return OffsetState
+
+
+class _PageStateFactory(SubscriptOnly):
+    """``page_state[PayloadT](…)`` builds a :class:`PageState` whose selectors read ``PayloadT``."""
+
+    __slots__ = ()
+    factory_name = "page_state"
+    spelling = "page_state[PayloadT](…), e.g. page_state[Products](page=page, limit=limit, item_count=…)"
+
+    def __getitem__(self, declared: TypeForm[PayloadT]) -> type[PageState[PayloadT]]:
+        return PageState
+
+
+class _CursorStateFactory(SubscriptOnly):
+    """``cursor_state[PayloadT](…)`` builds a :class:`CursorState` whose selectors read ``PayloadT``."""
+
+    __slots__ = ()
+    factory_name = "cursor_state"
+    spelling = "cursor_state[PayloadT](…), e.g. cursor_state[Orders](cursor=cursor, next_cursor=…)"
+
+    def __getitem__(self, declared: TypeForm[PayloadT]) -> type[CursorState[PayloadT]]:
+        return CursorState
+
+
+class _KeysetStateFactory(SubscriptOnly):
+    """``keyset_state[PayloadT](…)`` builds a :class:`KeysetState` whose selectors read ``PayloadT``."""
+
+    __slots__ = ()
+    factory_name = "keyset_state"
+    spelling = "keyset_state[PayloadT](…), e.g. keyset_state[CardTransactions](key=since, …)"
+
+    def __getitem__(self, declared: TypeForm[PayloadT]) -> type[KeysetState[PayloadT]]:
+        return KeysetState
+
+
+class _LinkStateFactory(SubscriptOnly):
+    """``link_state[PayloadT](…)`` builds a :class:`LinkState` whose selectors read ``PayloadT``."""
+
+    __slots__ = ()
+    factory_name = "link_state"
+    spelling = "link_state[PayloadT](…), e.g. link_state[Orders](url_template=…, query_params=…, next_link=…)"
+
+    def __getitem__(self, declared: TypeForm[PayloadT]) -> type[LinkState[PayloadT]]:
+        return LinkState
+
+
+offset_state: Final = _OffsetStateFactory()
+page_state: Final = _PageStateFactory()
+cursor_state: Final = _CursorStateFactory()
+keyset_state: Final = _KeysetStateFactory()
+link_state: Final = _LinkStateFactory()
+
+PagingState: TypeAlias = (
+    OffsetState[PayloadT] | PageState[PayloadT] | CursorState[PayloadT] | KeysetState[PayloadT] | LinkState[PayloadT]
+)
+
+
+@overload
+def paginate(
+    *,
+    initial_state: OffsetState[PayloadT],
+    fetch_page: Callable[[OffsetState[PayloadT]], ApiResult[PayloadT, E]],
+    items_selector: Callable[[PayloadT], Sequence[ItemT]],
+) -> Paginator[ApiResult[PayloadT, E], ItemT]: ...
+
+
+@overload
+def paginate(
+    *,
+    initial_state: PageState[PayloadT],
+    fetch_page: Callable[[PageState[PayloadT]], ApiResult[PayloadT, E]],
+    items_selector: Callable[[PayloadT], Sequence[ItemT]],
+) -> Paginator[ApiResult[PayloadT, E], ItemT]: ...
+
+
+@overload
+def paginate(
+    *,
+    initial_state: CursorState[PayloadT],
+    fetch_page: Callable[[CursorState[PayloadT]], ApiResult[PayloadT, E]],
+    items_selector: Callable[[PayloadT], Sequence[ItemT]],
+) -> Paginator[ApiResult[PayloadT, E], ItemT]: ...
+
+
+@overload
+def paginate(
+    *,
+    initial_state: KeysetState[PayloadT],
+    fetch_page: Callable[[KeysetState[PayloadT]], ApiResult[PayloadT, E]],
+    items_selector: Callable[[PayloadT], Sequence[ItemT]],
+) -> Paginator[ApiResult[PayloadT, E], ItemT]: ...
+
+
+@overload
+def paginate(
+    *,
+    initial_state: LinkState[PayloadT],
+    fetch_page: Callable[[LinkState[PayloadT]], ApiResult[PayloadT, E]],
+    items_selector: Callable[[PayloadT], Sequence[ItemT]],
+) -> Paginator[ApiResult[PayloadT, E], ItemT]: ...
+
+
+def paginate(
+    *,
+    initial_state: PagingState[PayloadT],
+    fetch_page: Callable[[Any], ApiResult[PayloadT, E]],
+    items_selector: Callable[[PayloadT], Sequence[ItemT]],
+) -> Paginator[ApiResult[PayloadT, E], ItemT]:
+    """Walk a paginated operation on the sync client, one ``execute`` per page.
+
+    Args:
+        initial_state: The first page's state, built with a state factory such as
+            ``offset_state[Products](…)``.
+        fetch_page: Sends the request for the state it is given and returns that page's ``ApiResult``.
+        items_selector: Returns one payload's items, in order. Iterating items unwraps each page first, so it
+            raises ``ApiError`` at a failed page.
+
+    Returns:
+        A lazy paginator that can be iterated more than once. Iterating it yields items. ``iter_pages()``
+        yields each ``ApiResult``, stops after a ``Failure`` and never raises."""
+
+    def fetch_pages() -> Iterator[ApiResult[PayloadT, E]]:
+        state = initial_state
+        while True:
+            result = fetch_page(state)
+            yield result
+            if not isinstance(result, Success):
+                return
+            next_state = state.advance(payload=result.payload, headers=result.headers)
+            if next_state is None:
+                return
+            state = next_state
+
+    return Paginator(fetch_pages, lambda result: items_selector(unwrap(result)))
+
+
+@overload
+def async_paginate(
+    *,
+    initial_state: OffsetState[PayloadT],
+    fetch_page: Callable[[OffsetState[PayloadT]], Awaitable[ApiResult[PayloadT, E]]],
+    items_selector: Callable[[PayloadT], Sequence[ItemT]],
+) -> AsyncPaginator[ApiResult[PayloadT, E], ItemT]: ...
+
+
+@overload
+def async_paginate(
+    *,
+    initial_state: PageState[PayloadT],
+    fetch_page: Callable[[PageState[PayloadT]], Awaitable[ApiResult[PayloadT, E]]],
+    items_selector: Callable[[PayloadT], Sequence[ItemT]],
+) -> AsyncPaginator[ApiResult[PayloadT, E], ItemT]: ...
+
+
+@overload
+def async_paginate(
+    *,
+    initial_state: CursorState[PayloadT],
+    fetch_page: Callable[[CursorState[PayloadT]], Awaitable[ApiResult[PayloadT, E]]],
+    items_selector: Callable[[PayloadT], Sequence[ItemT]],
+) -> AsyncPaginator[ApiResult[PayloadT, E], ItemT]: ...
+
+
+@overload
+def async_paginate(
+    *,
+    initial_state: KeysetState[PayloadT],
+    fetch_page: Callable[[KeysetState[PayloadT]], Awaitable[ApiResult[PayloadT, E]]],
+    items_selector: Callable[[PayloadT], Sequence[ItemT]],
+) -> AsyncPaginator[ApiResult[PayloadT, E], ItemT]: ...
+
+
+@overload
+def async_paginate(
+    *,
+    initial_state: LinkState[PayloadT],
+    fetch_page: Callable[[LinkState[PayloadT]], Awaitable[ApiResult[PayloadT, E]]],
+    items_selector: Callable[[PayloadT], Sequence[ItemT]],
+) -> AsyncPaginator[ApiResult[PayloadT, E], ItemT]: ...
+
+
+def async_paginate(
+    *,
+    initial_state: PagingState[PayloadT],
+    fetch_page: Callable[[Any], Awaitable[ApiResult[PayloadT, E]]],
+    items_selector: Callable[[PayloadT], Sequence[ItemT]],
+) -> AsyncPaginator[ApiResult[PayloadT, E], ItemT]:
+    """Walk a paginated operation on the async client, one awaited ``execute`` per page.
+
+    Works like :func:`paginate`, except that ``fetch_page`` returns an awaitable.
+
+    Args:
+        initial_state: The first page's state, built with a state factory such as
+            ``offset_state[Products](…)``.
+        fetch_page: Sends the request for the state it is given and returns an awaitable of that page's
+            ``ApiResult``.
+        items_selector: Returns one payload's items, in order. Iterating items unwraps each page first, so it
+            raises ``ApiError`` at a failed page.
+
+    Returns:
+        A lazy async paginator that can be iterated more than once, with the same item and page views as the
+        sync one."""
+
+    async def fetch_pages() -> AsyncIterator[ApiResult[PayloadT, E]]:
+        state = initial_state
+        while True:
+            result = await fetch_page(state)
+            yield result
+            if not isinstance(result, Success):
+                return
+            next_state = state.advance(payload=result.payload, headers=result.headers)
+            if next_state is None:
+                return
+            state = next_state
+
+    return AsyncPaginator(fetch_pages, lambda result: items_selector(unwrap(result)))

swagger_petstore_open_api_3_1_0/core/paginator.py

@@ -0,0 +1,55 @@
+"""The paginator a paginated endpoint returns: a lazy view over a walk of pages that can be iterated again.
+
+A paginator holds a function that starts a new page iterator, never an iterator itself. So building one sends
+nothing, the first request goes out when iteration starts, and each new iteration starts again from the
+first page. Iterating yields items; ``iter_pages()`` yields pages.
+
+``results`` imports this module, so this module must not import ``results``."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable, Iterator, Sequence
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+PageT = TypeVar("PageT")
+ItemT = TypeVar("ItemT")
+
+
+@dataclass(frozen=True, slots=True)
+class Paginator(Generic[PageT, ItemT]):
+    """A walk over a paginated operation. Iterate it for items, or call ``iter_pages()`` for pages.
+
+    Nothing is sent until iteration starts. Each iteration starts again from the first page, and a ``break``
+    stops it with no further request."""
+
+    _fetch_pages: Callable[[], Iterator[PageT]]
+    _items_selector: Callable[[PageT], Sequence[ItemT]]
+
+    def __iter__(self) -> Iterator[ItemT]:
+        for page in self._fetch_pages():
+            yield from self._items_selector(page)
+
+    def iter_pages(self) -> Iterator[PageT]:
+        """Start a new walk and yield each page as it arrives."""
+        return self._fetch_pages()
+
+
+@dataclass(frozen=True, slots=True)
+class AsyncPaginator(Generic[PageT, ItemT]):
+    """An async walk over a paginated operation. Use ``async for`` for items, or ``iter_pages()`` for pages.
+
+    Nothing is sent until iteration starts. Each iteration starts again from the first page, and a ``break``
+    stops it with no further request."""
+
+    _fetch_pages: Callable[[], AsyncIterator[PageT]]
+    _items_selector: Callable[[PageT], Sequence[ItemT]]
+
+    async def __aiter__(self) -> AsyncIterator[ItemT]:
+        async for page in self._fetch_pages():
+            for item in self._items_selector(page):
+                yield item
+
+    def iter_pages(self) -> AsyncIterator[PageT]:
+        """Start a new walk and yield each page as it arrives."""
+        return self._fetch_pages()