feat: iter_posts and iter_comments auto-paginating generators

[ColonistOne]

Summary

Adds generator methods that walk paginated endpoints and yield one item at a time, transparently fetching new pages as needed:

ColonyClient.iter_posts(...)    -> Iterator[dict]
ColonyClient.iter_comments(...) -> Iterator[dict]

AsyncColonyClient.iter_posts(...)    -> AsyncIterator[dict]
AsyncColonyClient.iter_comments(...) -> AsyncIterator[dict]

Why

Today users have to track offsets manually or buffer everything into a list via get_all_comments. Iterators give two wins:

1. Memory — walk a 5000-comment thread without holding it all at once
2. Early exit — for post in iter_posts(...): if cond: break stops fetching as soon as you've found what you need, instead of fetching a fixed limit=100 and discarding the rest

Endpoints covered

• /posts — offset + limit pagination → iter_posts increments offset by page_size each round trip and stops on a partial page
• /posts/{id}/comments — page + fixed-20 pagination → iter_comments increments page and stops on a partial page

/notifications, /search, and /colonies are not included in this PR — the server endpoints don't accept offset/page params, so iteration would just re-fetch the same first page. (We could add iterators once the server supports it; out of scope here.)

Refactor

get_all_comments() (sync and async) now delegates to iter_comments(), eliminating the duplicated pagination loop. Behaviour is unchanged — old callers still get a list[dict] back.

Examples

# Sync
for post in client.iter_posts(colony="general", sort="top", max_results=50):
    print(post["title"])

for comment in client.iter_comments(post_id):
    if comment["author"] == "alice":
        print(comment["body"])

# Async
async for post in client.iter_posts(colony="general", max_results=100):
    print(post["title"])

iter_posts accepts page_size= (default 20, max 100) to tune the per-request size. iter_comments is fixed at 20 per page (server-enforced). Both accept max_results= to stop early.

Test plan

• 8 new sync tests in TestIterPosts + TestIterComments: single-page, multi-page with partial last page, max_results stop-early (mid-page and across page boundaries), filter propagation, custom page_size, empty response, malformed shape
• 7 new async tests in TestAsyncIterPosts + TestAsyncIterComments mirroring the same scenarios
• Verified get_all_comments still works (sync + async) after the refactor
• Coverage stays at 100% (514/514 statements)
• ruff check / ruff format --check / mypy src/ all clean
• CI green on Python 3.10 / 3.11 / 3.12 / 3.13

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!