feat!: iterate only the current page when looping over a list response

[tribble]

I found that looping over a list response silently fetched every remaining page.

• for x in page / async for x in page now yield only the current page's items and make no further requests.
• page.auto_paging_iter() remains the explicit way to iterate across all pages.

Migration: replace for x in page with for x in page.auto_paging_iter() (likewise async for) to keep iterating across pages.

Test plan

• Red: this PR's tests run against main's pagination implementation at 9bbc82d — mise x uv -- uv run pytest -q tests/test_pagination.py -k PageLocalIteration — both the sync and async test fail with WorkOSTimeoutError, because plain iteration issues a second HTTP request the mock has no response queued for.
• Green on this branch: the same command passes — both tests assert the page yields its two items in order and that exactly one HTTP request was made, even with list_metadata.after set.

[greptile-apps]

Confidence Score: 4/5

[Critical risk] Changes how iteration over paginated results works.

The PR appears safe to merge, but the v11 iteration migration instruction should be made easier for upgrading users to find.

Findings

1.  V11 guidance is hard to find ▶

Fix with agent prompt

### Issue 1
docs/V6_MIGRATION_GUIDE.md:283
The instruction for upgrading page iteration to v11 appears only in this v5-to-v6 migration guide. Developers upgrading from v10 may miss the need to use `auto_paging_iter()` and silently process only the first page. Please put the instruction somewhere v11 users are likely to look.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

The PR makes direct sync and async page iteration yield only the current page’s items, while retaining cross-page traversal through auto_paging_iter().

• Adds tests confirming direct iteration makes no follow-up request.
• Updates existing pagination examples and tests to request auto-pagination explicitly.
• Documents the breaking change, though its upgrade instruction is placed in the v6 guide.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  P[Page returned by list request] --> D{Iteration method}
  D -->|Direct iteration| C[Yield current page data only]
  D -->|auto_paging_iter| A[Yield page data]
  A --> H{After cursor?}
  H -->|Yes| F[Fetch next page]
  F --> A
  H -->|No| E[Stop]

Loading

_{Reviews (1) · Last reviewed commit: "feat!: iterate only the current page whe..."}

[greptile-apps]

V11 guidance is hard to find The instruction for upgrading page iteration to v11 appears only in this v5-to-v6 migration guide. Developers upgrading from v10 may miss the need to use auto_paging_iter() and silently process only the first page. Please put the instruction somewhere v11 users are likely to look.

Prompt To Fix With AI

This is a comment left during a code review.
Path: docs/V6_MIGRATION_GUIDE.md
Line: 283

Comment:
**V11 guidance is hard to find** The instruction for upgrading page iteration to v11 appears only in this v5-to-v6 migration guide. Developers upgrading from v10 may miss the need to use `auto_paging_iter()` and silently process only the first page. Please put the instruction somewhere v11 users are likely to look.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!