pager___asyncpager

Chapter 6: Pager / AsyncPager

In Chapter 5: Function Calling Utilities, we explored how the SDK facilitates interactions with external tools. Now, let's turn our attention to another common API interaction pattern: handling large lists of results that the API returns in chunks, or pages. This chapter introduces the Pager and AsyncPager classes, which abstract the complexities of pagination.

Motivation and Use Case

When you request a list of resources from an API (like available models using models.list, uploaded files using files.list, or tuning jobs using tunings.list), the total number of items might be very large. Returning the entire list in a single response could be inefficient or even infeasible due to size limits.

To handle this, APIs often implement pagination. The API returns a manageable subset of the list (a page) along with a next_page_token. To get the next subset of results, you make another API request, including this token. This process repeats until all items have been retrieved (indicated by the absence of a next_page_token in the response).

Managing this token passing and repeated request cycle manually adds boilerplate code to your application. The Pager (for synchronous operations) and AsyncPager (for asynchronous operations) classes implement the Pager design pattern to hide this complexity. They act as iterators that automatically fetch subsequent pages when needed.

Central Use Case: You want to process all available generative models, potentially hundreds, without worrying about fetching page by page.

# Assuming 'client' is configured (e.g., using genai.Client(api_key=...))
from google import genai

# models.list() returns a Pager object
model_pager = client.models.list()

# Iterate directly over the pager
print("Processing all available models:")
count = 0
for model in model_pager:
    # The pager automatically fetches the next page when the current one is exhausted
    # We only print basic info here for brevity
    if "generateContent" in model.supported_generation_methods:
        print(f"- Found model: {model.name} ({model.display_name})")
        count += 1
print(f"\nTotal models processed: {count}")

# The pager transparently handled fetching multiple pages if necessary.

This example demonstrates how the Pager allows simple iteration over potentially large result sets without explicit pagination logic.