nanosdk.pagination

Pagination: the Page record and the built-in next-page strategies.

Make a route iterable with Route.paginate, passing a strategy that picks the next request from the current page:

list_posts = nanosdk.get("/posts", request=ListPosts, response=list[Post]).paginate(
    nanosdk.Offset("offset", limit="limit")
)
for post in api.list_posts.iter(limit=50): ...

A strategy is any callable (Page) -> next, where next is one of:

• a new request model: sent through the route as usual;
• an httpx.URL: the same request re-sent to that URL, whose query string replaces the model's query fields (for APIs that hand you a "next" link);
• None: stop.

Strategies that change a request field refer to it by its Python field name and need the route to have a request model.

Page dataclass

Page(
    request: ReqT,
    data: RespT,
    items: list[ItemT],
    response: Response,
)

One fetched page, as passed to strategies and yielded by .pages().

Attributes:

Name	Type	Description
request	ReqT	The request model that produced this page (None for routes without one).
data	RespT	The decoded response body, after any map.
items	list[ItemT]	The page's items, as extracted by the route's items function.
response	Response	The raw httpx.Response, for headers such as Link or rate limits.

NextPage

NextPage = Callable[
    [Page[ReqT, RespT, ItemT]], ReqT | URL | None
]

A pagination strategy: given the current page, the next request model, URL or None.

Strategies

Cursor dataclass

Cursor(
    field: str | Callable[[Any], Any], param: str = "cursor"
)

Read a cursor from each response and send it back in a request field.

Stops when the cursor is missing, None or empty.

Example

# {"data": [...], "meta": {"next_cursor": "abc"}}  ->  ?cursor=abc
nanosdk.Cursor("meta.next_cursor", param="cursor")
nanosdk.Cursor(lambda body: body.paging.next, param="after")

Parameters:

Name	Type	Description	Default
field	str | Callable[[Any], Any]	Where the cursor is in the decoded response: a dotted path through attributes or dict keys, or a function of the response.	required
param	str	The request-model field to put the cursor in.	'cursor'

Methods:

Name	Description
__call__	Return the request for the page after page, or None when done.

__call__

__call__(page: Page[Any, Any, Any]) -> Any

Return the request for the page after page, or None when done.

Offset dataclass

Offset(param: str = 'offset', limit: str | None = 'limit')

Advance an offset request field by the number of items received.

Stops on an empty page, or on one shorter than the page size.

Example

# ?offset=0&limit=50, ?offset=50&limit=50, ...
nanosdk.Offset("offset", limit="limit")

Parameters:

Name	Type	Description	Default
param	str	The request-model field holding the offset (missing or None means 0).	'offset'
limit	str | None	The request-model field holding the page size, used to detect a short last page; None to rely on empty pages only.	'limit'

Methods:

Name	Description
__call__	Return the request for the page after page, or None when done.

__call__

__call__(page: Page[Any, Any, Any]) -> Any

Return the request for the page after page, or None when done.

PageNumber dataclass

PageNumber(
    param: str = "page",
    start: int = 1,
    size: str | None = None,
)

Increment a page-number request field.

Stops on an empty page, or on one shorter than the page size.

Example

# ?page=1&per_page=100, ?page=2&per_page=100, ...
nanosdk.PageNumber("page", size="per_page")

Parameters:

Name	Type	Description	Default
param	str	The request-model field holding the page number.	'page'
start	int	The number of the first page, assumed when the field is unset or None.	1
size	str | None	The request-model field holding the page size, used to detect a short last page; None to rely on empty pages only.	None

Methods:

Name	Description
__call__	Return the request for the page after page, or None when done.

__call__

__call__(page: Page[Any, Any, Any]) -> Any

Return the request for the page after page, or None when done.

LinkHeader dataclass

LinkHeader(rel: str = 'next')

Follow the Link: <url>; rel="next" response header (RFC 8288).

Used by GitHub, GitLab and many others. The linked URL (resolved against the response URL) replaces the query string; the route needs no request model.

Parameters:

Name	Type	Description	Default
rel	str	The link relation to follow.	'next'

Methods:

Name	Description
__call__	Return the URL of the page after page, or None when there's no link.

__call__

__call__(page: Page[Any, Any, Any]) -> URL | None

Return the URL of the page after page, or None when there's no link.