paginate¶

Gmail API Pagination Utilities

This module provides pagination utilities for Gmail API list operations. It abstracts the complexity of handling pageToken and nextPageToken to provide a simple iterator interface for paginated API responses.

The module follows the adapter pattern to handle different Gmail API endpoints (messages, threads) with a unified pagination mechanism.

pythonic_gmail.paginate.default_set_page_size(request_kwargs: dict[str, Any], page_size: int)[source]¶

Set maxResults in request parameters for page size.

Default implementation for Gmail API’s pagination mechanism where page size is controlled by the maxResults parameter.

Parameters:

request_kwargs – Request parameters dictionary to modify
page_size – Number of items to request per page

pythonic_gmail.paginate.default_get_next_token(response: dict[str, Any]) → str | None[source]¶

Extract nextPageToken from Gmail API response.

Default implementation for Gmail API’s pagination mechanism where the next page token is provided in the nextPageToken field.

Parameters:: response – API response dictionary
Returns:: Next page token if available, None if no more pages

pythonic_gmail.paginate.default_set_next_token(request_kwargs: dict[str, Any], next_token: str)[source]¶

Set pageToken in request parameters for next API call.

Default implementation for Gmail API’s pagination mechanism where the page token is passed via the pageToken parameter.

Parameters:

request_kwargs – Request parameters dictionary to modify
next_token – Token for the next page to retrieve

pythonic_gmail.paginate.paginate(method: ~typing.Callable, items_field: str, page_size: int, max_items: int, kwargs: dict[str, ~typing.Any] | None = None, set_page_size: ~typing.Callable[[dict[str, ~typing.Any], int], None] = <function default_set_page_size>, get_next_token: ~typing.Callable[[dict[str, ~typing.Any]], str | None] = <function default_get_next_token>, set_next_token: ~typing.Callable[[dict[str, ~typing.Any], str], None] = <function default_set_next_token>) → Iterator[dict[str, Any]][source]¶

Core pagination engine for Gmail API list methods.

Provides the underlying pagination mechanism used by pagi_list_messages() and pagi_list_threads(). Handles nextPageToken management and respects item count limits across multiple API calls.

Parameters:

method – Gmail API method that returns a Resource for execution
items_field – Field name in API response containing the list of items
page_size – Number of items per API request (sets maxResults)
max_items – Maximum total items to return across all pages
kwargs – Initial parameters for the API call
set_page_size – Function to set page size in request parameters
get_next_token – Function to extract nextPageToken from API response
set_next_token – Function to set pageToken in request parameters

Yields:

API response dictionaries containing paginated results

Examples:

Direct usage with messages list API:

for response in paginate(
    method=gmail_client.users().messages().list,
    items_field="messages",
    page_size=50,
    max_items=100,
    kwargs={"userId": "me"}
):
    messages = response.get("messages", [])
    print(f"Got {len(messages)} messages")

Direct usage with threads list API:

for response in paginate(
    method=gmail_client.users().threads().list,
    items_field="threads",
    page_size=25,
    max_items=75,
    kwargs={"userId": "me"}
):
    threads = response.get("threads", [])
    print(f"Got {len(threads)} threads")

Note

This is a low-level function. Most users should use pagi_list_messages() or pagi_list_threads() instead.