[bablukumar5xx]

Who this helps

Teams and coding agents that audit one pull request's review history — to compare reruns, find the run that introduced a finding, or export every run to a dashboard — currently have to hand-roll cursor continuation, page/item bounds and cursor-loop detection around list_pull_request_reviews(). iter_reviews() is not a substitute: it lists the latest run of each pull request, not every run of a specific pull request. The sibling TypeScript SDK has an open request for the same iterator (prooflinedev/sdk-typescript#26), so this also closes the parity gap for Python callers.

Both facades now expose iter_pull_request_reviews(...), so the same loop works with ProoflineClient and AsyncProoflineClient:

for review in client.iter_pull_request_reviews(
    organization_id, "owner/name", 42,
    page_size=50, filters={"status": "COMPLETED"},
):
    print(review.id, review.status)

Decisions

• Accept the same page_size / max_pages / max_items controls and ReviewFilters as iter_reviews, with the same defaults (100 pages, 10,000 items) and 1..100 / 1..1000 / 1..100000 validation.
• Reuse the existing _next_cursor() guard so missing, non-advancing, repeated or malformed continuation cursors raise the existing urn:proofline:sdk:invalid-pagination error, and reaching either bound raises urn:proofline:sdk:pagination-limit.
• Extract _iteration_params() for the shared limit/filter/cursor-seed setup instead of duplicating the loop setup. Existing iter_reviews() behavior is unchanged.
• Fetch lazily: leaving the loop after the first item makes no further request.
• Add iter_pull_request_reviews to the helper list in scripts/contracts.py. That contract keeps the sync and async facades in lockstep and already exempts iter_reviews as a helper.
• Document the distinction from iter_reviews and the bounds in the README.

Verification

• python3 scripts/check.py passes end to end: generation check, operation/vocabulary contracts, ruff check, ruff format --check, mypy, the full pytest suite, wheel/sdist build, and the installed-artifact HTTP smoke test.
• New loopback HTTP tests cover, for both sync and async:
  • three pages using the same repo/name + pull request path, with the status filter and initial/continuation cursors preserved;
  • repeated, missing and non-advancing cursors, max_pages, max_items, and invalid page_size;
  • lazy fetching (exactly one request when iteration stops after the first item).
• The existing iter_reviews pagination tests continue to pass, covering the shared helper.