From 6183c6d274ef75ac0d95176d9e40788d3aa3c444 Mon Sep 17 00:00:00 2001 From: jonathan343 Date: Fri, 20 Nov 2026 07:57:01 -0500 Subject: [PATCH 1/2] Propose modeled pagination --- designs/pagination.md | 129 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 designs/pagination.md diff --git a/designs/pagination.md b/designs/pagination.md new file mode 100644 index 000000000..b8400f038 --- /dev/null +++ b/designs/pagination.md @@ -0,0 +1,129 @@ +# Pagination + +## Summary + +This document proposes generating a `paginate_` method for each +operation with Smithy's `@paginated` trait. These methods return lazy, typed +iterators over complete response pages. When the model identifies an item +collection, the paginator also provides `.items()` to iterate over that +collection across pages. Ordinary operation methods continue to make a single +request. + +## Motivation + +Customers currently have to read continuation tokens and pass them into +subsequent requests. Each loop must preserve the original parameters, handle +the service's token type, and continue through empty pages when a token is +present. For example, paginating a DynamoDB scan requires: + +```python +start_key = None +while True: + page = await client.scan( + table_name="orders", + exclusive_start_key=start_key, + ) + for item in page.items or []: + process(item) + start_key = page.last_evaluated_key + if not start_key: + break +``` + +The model already describes how to make the next request. Generated pagination +methods remove this repeated code without changing response models or requiring +customers to look up an operation by name. + +## Proposal + +### Response pages + +Each paginated operation gets a method with a `paginate_` prefix. It accepts the +same input parameters and per-call plugins as the ordinary operation: + +```python +async for page in client.paginate_scan(table_name="orders", limit=100): + for item in page.items or []: + process(item) + print(page.response_metadata.request_id) +``` + +Each page is the operation's output model, including response metadata and any +additional result collections. Requests run through the normal client pipeline, +so authentication, retries, interceptors, and operation plugins apply to each +page. + +The factory validates the input but sends no request. The first request is sent +when iteration starts, and subsequent pages are fetched only as needed. Neither +`paginate_scan()` nor `.items()` is awaited; `async for` awaits each advance. + +### Items + +When the model identifies an item collection, customers can iterate over its +items directly: + +```python +async for item in client.paginate_scan(table_name="orders", limit=100).items(): + process(item) +``` + +The iterator's item type is available to type checkers. Lists yield their +elements; maps yield `(key, value)` pairs. Items are not merged or deduplicated +across pages. + +Some operations do not identify an item collection. These paginators have no +`.items()` method, and type checkers flag attempts to call it. Page iteration +still works. Customers select the collection they want rather than the SDK +choosing one: + +```python +async for page in s3.paginate_list_objects_v2(bucket="reports"): + for obj in page.contents or []: + process(obj) +``` + +### Synchronous clients + +Synchronous clients expose the same methods, consumed with `for`: + +```python +for item in client.paginate_scan(table_name="orders").items(): + process(item) +``` + +### Iterator lifetime + +This proposal uses single-use iterators. Pages and `.items()` consume the same +traversal; a second loop does not restart it. Customers create a new paginator +for another pass. Responses are not cached. + +Breaking out of a loop sends no further requests. The paginator does not own or +close the client, which must remain open during iteration. Service errors and +cancellation propagate to the caller and end the traversal. + +### Page size and continuation + +Page-size and starting-token parameters retain their modeled names. DynamoDB's +`limit`, for example, is a per-request limit, not a total item limit. Customers +can start from a saved service token using the ordinary input parameter. The +paginator does not modify caller-owned inputs or yielded responses. + +An empty item collection does not end pagination while a continuation token +remains. Pagination ends when the output token is absent or empty. Consecutive +repeated output tokens raise `PaginationError` after yielding the repeated page. + +This proposal does not add total-item limits, combined results, or encoded SDK +resume tokens. AWS-specific termination flags and other pagination rules not +represented by the Smithy trait require separate customization. + +### Alternatives considered + +* `iter_` is shorter, but does not distinguish page iteration from + item iteration. `paginate_` names the additional behavior without adding a + second method family. +* Item-first iteration makes the common item case shorter, but the model does + not always identify a collection. Page-first iteration has the same meaning + for every paginated operation and preserves all response fields. +* Reusable iterables could start independent requests on each pass. This + proposal instead uses an explicit new factory call to restart, avoiding + repeated network requests from looping over the same object again. From 5760f8cb8b9a30ecd9cef18205edbdae8c22bda5 Mon Sep 17 00:00:00 2001 From: jonathan343 Date: Fri, 20 Nov 2026 14:10:09 -0500 Subject: [PATCH 2/2] Clarify pagination configuration and behavior --- designs/pagination.md | 41 ++++++++++++++++++++++++++++++++--------- 1 file changed, 32 insertions(+), 9 deletions(-) diff --git a/designs/pagination.md b/designs/pagination.md index b8400f038..b9356db0a 100644 --- a/designs/pagination.md +++ b/designs/pagination.md @@ -36,10 +36,20 @@ customers to look up an operation by name. ## Proposal +### Modeled pagination + +Operations opt into pagination through Smithy's `@paginated` trait. Operation +settings override service-level defaults. + +The generator uses these settings to identify continuation tokens, the page-size +parameter, and an optional item collection. Generation fails when configured +members cannot be resolved or have unsupported types. + ### Response pages Each paginated operation gets a method with a `paginate_` prefix. It accepts the -same input parameters and per-call plugins as the ordinary operation: +ordinary operation's input parameters and per-call plugins, along with the +`stop_on_same_token` option described below: ```python async for page in client.paginate_scan(table_name="orders", limit=100): @@ -94,8 +104,9 @@ for item in client.paginate_scan(table_name="orders").items(): ### Iterator lifetime This proposal uses single-use iterators. Pages and `.items()` consume the same -traversal; a second loop does not restart it. Customers create a new paginator -for another pass. Responses are not cached. +traversal. Once exhausted, further iteration yields nothing and sends no +requests. Customers create a new paginator to start another traversal. Responses +are not cached. Breaking out of a loop sends no further requests. The paginator does not own or close the client, which must remain open during iteration. Service errors and @@ -103,18 +114,30 @@ cancellation propagate to the caller and end the traversal. ### Page size and continuation -Page-size and starting-token parameters retain their modeled names. DynamoDB's -`limit`, for example, is a per-request limit, not a total item limit. Customers +Page-size parameters retain their modeled names, such as `limit` or `max_items`. +They control individual requests, not the total number of items yielded across +pages. Starting-token parameters also retain their modeled names, so customers can start from a saved service token using the ordinary input parameter. The paginator does not modify caller-owned inputs or yielded responses. An empty item collection does not end pagination while a continuation token -remains. Pagination ends when the output token is absent or empty. Consecutive -repeated output tokens raise `PaginationError` after yielding the repeated page. +remains. An absent or empty output token always ends pagination. A map token is +empty when it contains no entries. This proposal does not add total-item limits, combined results, or encoded SDK -resume tokens. AWS-specific termination flags and other pagination rules not -represented by the Smithy trait require separate customization. +resume tokens. Other service-specific pagination rules, including termination +flags not represented by the Smithy trait, require separate customization. + +### Paginator configuration + +Paginator methods accept SDK-specific options in addition to the operation's +inputs. These options control iteration and are not sent to the service. + +* `stop_on_same_token` defaults to `True`. When a response returns the same + token used for that request, including a supplied starting token, the paginator + yields the page and ends normally. Tokens are compared by value. Set + `stop_on_same_token=False` to continue requesting pages when tokens repeat, + such as when polling for new results. ### Alternatives considered