Skip to content

Add modeled pagination design - #970

Open
jonathan343 wants to merge 2 commits into
developfrom
docs/pagination
Open

jonathan343 wants to merge 2 commits into
developfrom
docs/pagination

Conversation

@jonathan343

Copy link
Copy Markdown
Contributor

Summary

Adds a design proposal for typed paginate_<operation> methods that iterate over complete response pages, with an optional .items() helper when the model identifies a collection.

The proposal covers synchronous and asynchronous usage, lazy requests, iterator lifetime, and continuation behavior. It also explains the choice of page-first, single-use iteration and the alternatives considered.

This PR contains only the design document, so the interface can be reviewed independently of the implementation.


By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

@jonathan343
jonathan343 marked this pull request as ready for review November 20, 2026 13:37
@jonathan343
jonathan343 requested a review from a team as a code owner November 20, 2026 13:37

@stobrien89 stobrien89 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good. Similar to PHP's design with <operation>Paginated. Could the doc say what codegen does with the @paginated trait itself?

  • Does it merge service-level defaults with the operation's trait?
  • Does it fail generation when inputToken, outputToken, pageSize or items don't resolve, or items isn't a list or map? We load JSON ASTs, so Smithy's validator may not have run.
  • DynamoDB's tokens are maps (ExclusiveStartKey). How are "empty" and "repeated" defined for map tokens?

Comment thread designs/pagination.md

## Proposal

### Response pages

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How will maxItems be handled?

@jonathan343 jonathan343 Nov 20, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Modeled page-size inputs stay as-is and apply per-request. Total-item limits are something boto offers. I should think about if we should add that here Gonna leave this our for now

Comment thread designs/pagination.md Outdated
### 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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what happens when a second loop gets nothing?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Once exhausted, it yields nothing and makes no requests. You'd create a new paginator for another pass.

Comment thread designs/pagination.md

### Iterator lifetime

This proposal uses single-use iterators. Pages and `.items()` consume the same

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Iterators, yes. Generators?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, generators can be used in the implementation. We will need a wrapper for the .items() feature.

Comment thread designs/pagination.md
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you'll want to define the termination condition. There are two customers may want.

  1. the "next token" field is empty.
  2. the "next token" field returned the same value as the previous page.

Without the 2nd option, it's difficult to terminate a tail operation that assumes you are trying to live-tail.

I recommend stop_on_same_token: bool:

client.paginate_live_tail(log_group="orders", stop_on_same_token: True)

if it can be merged into the kwargs.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added stop_on_same_token, defaulting to True, to a new paginator configuration section in the doc. It ends normally after yielding the page. Setting it to False allows continued polling.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants