feat(paginators): expose max_pages on every public *_all() method

Plumb max_pages: int | None = None through all 19 public *_all()
paginator methods (sync + async, 38 signatures) so callers can cap
fetch depth from outside without subclassing the resource. Previously
the cap existed only on the internal _list_all and silently defaulted
to 1000 pages.

- _list_all: accept max_pages=None (default 1000), positive int caps
  page fetches at that count.
- _validate_max_pages: rejects max_pages <= 0 with ValueError at the
  public boundary; None and positive ints pass through.
- Add "client_only" ExclusionKind for kwargs that have no wire
  counterpart (max_pages is purely a client-side knob). EXCLUSIONS
  registers max_pages for every *_all FQN so TestRequestParamDrift
  doesn't flag the new kwarg as REMOVE drift.
- Tests cover the bare numeric cap (cap=1 / cap=3 with a fresh-cursor
  side effect so cursor-loop detection can't trip), empty-cursor
  termination (F-Q-17 regression), and ValueError on max_pages=0 at
  the public list_all boundary (markets).

Closes #98

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: TexasCoding

kalshi/resources/_base.py

@@ -44,6 +44,19 @@ def _check_request_exclusive(request: Any, **kwargs: Any) -> None:
         )
 
 
+def _validate_max_pages(max_pages: int | None) -> None:
+    """Reject ``max_pages <= 0`` at the public ``*_all()`` boundary.
+
+    ``None`` (use default cap) and positive integers are valid. Zero or
+    negative would silently produce an empty iterator deep inside
+    ``_list_all``; surfacing the misuse here is friendlier.
+    """
+    if max_pages is not None and max_pages <= 0:
+        raise ValueError(
+            f"max_pages must be positive or None, got {max_pages}"
+        )
+
+
 def _join_tickers(value: list[str] | tuple[str, ...] | str | None) -> str | None:
     """Serialize the `tickers` query param (spec: comma-joined string, not explode:true).
 
@@ -151,7 +164,7 @@ def _list_all(
         items_key: str,
         *,
         params: dict[str, Any] | None = None,
-        max_pages: int = 1000,
+        max_pages: int | None = None,
         cursor_key: str = "cursor",
     ) -> Iterator[T]:
         """Auto-paginate through all pages, yielding items.
@@ -160,13 +173,19 @@ def _list_all(
         convention). ``cursor_key`` only affects how the response envelope
         is parsed.
 
+        ``max_pages`` caps the number of pages fetched as a safety net for
+        servers that never repeat a cursor but never return empty either.
+        ``None`` (default) means the built-in ceiling of 1000. Callers that
+        need a tighter cap (e.g. a quick preview) pass it explicitly.
+
         Raises ``KalshiError`` if a cursor value repeats, which indicates
         a server-side pagination bug that would otherwise cause the safety
         cap to silently issue ``max_pages`` duplicate requests.
         """
+        page_cap = 1000 if max_pages is None else max_pages
         current_params = dict(params) if params else {}
         seen_cursors: set[str] = set()
-        for _ in range(max_pages):
+        for _ in range(page_cap):
             page = self._list(
                 path, model_cls, items_key,
                 params=current_params, cursor_key=cursor_key,
@@ -264,15 +283,17 @@ async def _list_all(
         items_key: str,
         *,
         params: dict[str, Any] | None = None,
-        max_pages: int = 1000,
+        max_pages: int | None = None,
         cursor_key: str = "cursor",
     ) -> AsyncIterator[T]:
-        """Async counterpart of ``SyncResource._list_all``. Raises
-        ``KalshiError`` on repeated cursor; see sync docstring.
+        """Async counterpart of ``SyncResource._list_all``. ``max_pages``
+        semantics mirror the sync version (``None`` -> 1000 default).
+        Raises ``KalshiError`` on repeated cursor; see sync docstring.
         """
+        page_cap = 1000 if max_pages is None else max_pages
         current_params = dict(params) if params else {}
         seen_cursors: set[str] = set()
-        for _ in range(max_pages):
+        for _ in range(page_cap):
             page = await self._list(
                 path, model_cls, items_key,
                 params=current_params, cursor_key=cursor_key,

kalshi/resources/communications.py

@@ -24,6 +24,7 @@
     SyncResource,
     _check_request_exclusive,
     _params,
+    _validate_max_pages,
 )
 
 
@@ -212,14 +213,19 @@ def list_all_rfqs(
         subaccount: int | None = None,
         status: str | None = None,
         creator_user_id: str | None = None,
+        max_pages: int | None = None,
     ) -> Iterator[RFQ]:
         self._require_auth()
+        _validate_max_pages(max_pages)
         params = _list_rfqs_params(
             cursor=None, limit=limit, event_ticker=event_ticker,
             market_ticker=market_ticker, subaccount=subaccount,
             status=status, creator_user_id=creator_user_id,
         )
-        yield from self._list_all("/communications/rfqs", RFQ, "rfqs", params=params)
+        yield from self._list_all(
+            "/communications/rfqs", RFQ, "rfqs",
+            params=params, max_pages=max_pages,
+        )
 
     def get_rfq(self, rfq_id: str) -> GetRFQResponse:
         self._require_auth()
@@ -303,9 +309,11 @@ def list_all_quotes(
         rfq_creator_user_id: str | None = None,
         rfq_creator_subtrader_id: str | None = None,
         rfq_id: str | None = None,
+        max_pages: int | None = None,
     ) -> Iterator[Quote]:
         self._require_auth()
         _require_quote_filter(quote_creator_user_id, rfq_creator_user_id)
+        _validate_max_pages(max_pages)
         params = _list_quotes_params(
             cursor=None, limit=limit, event_ticker=event_ticker,
             market_ticker=market_ticker, status=status,
@@ -315,7 +323,8 @@ def list_all_quotes(
             rfq_id=rfq_id,
         )
         return self._list_all(
-            "/communications/quotes", Quote, "quotes", params=params,
+            "/communications/quotes", Quote, "quotes",
+            params=params, max_pages=max_pages,
         )
 
     def get_quote(self, quote_id: str) -> GetQuoteResponse:
@@ -418,15 +427,18 @@ async def list_all_rfqs(
         subaccount: int | None = None,
         status: str | None = None,
         creator_user_id: str | None = None,
+        max_pages: int | None = None,
     ) -> AsyncIterator[RFQ]:
         self._require_auth()
+        _validate_max_pages(max_pages)
         params = _list_rfqs_params(
             cursor=None, limit=limit, event_ticker=event_ticker,
             market_ticker=market_ticker, subaccount=subaccount,
             status=status, creator_user_id=creator_user_id,
         )
         async for item in self._list_all(
-            "/communications/rfqs", RFQ, "rfqs", params=params,
+            "/communications/rfqs", RFQ, "rfqs",
+            params=params, max_pages=max_pages,
         ):
             yield item
 
@@ -514,9 +526,11 @@ def list_all_quotes(
         rfq_creator_user_id: str | None = None,
         rfq_creator_subtrader_id: str | None = None,
         rfq_id: str | None = None,
+        max_pages: int | None = None,
     ) -> AsyncIterator[Quote]:
         self._require_auth()
         _require_quote_filter(quote_creator_user_id, rfq_creator_user_id)
+        _validate_max_pages(max_pages)
         params = _list_quotes_params(
             cursor=None, limit=limit, event_ticker=event_ticker,
             market_ticker=market_ticker, status=status,
@@ -526,7 +540,8 @@ def list_all_quotes(
             rfq_id=rfq_id,
         )
         return self._list_all(
-            "/communications/quotes", Quote, "quotes", params=params,
+            "/communications/quotes", Quote, "quotes",
+            params=params, max_pages=max_pages,
         )
 
     async def get_quote(self, quote_id: str) -> GetQuoteResponse:

kalshi/resources/events.py

@@ -7,7 +7,13 @@
 
 from kalshi.models.common import Page
 from kalshi.models.events import Event, EventMetadata, EventStatusLiteral
-from kalshi.resources._base import AsyncResource, SyncResource, _bool_param, _params
+from kalshi.resources._base import (
+    AsyncResource,
+    SyncResource,
+    _bool_param,
+    _params,
+    _validate_max_pages,
+)
 
 # Shared param builders (issue #46).
 
@@ -86,15 +92,19 @@ def list_all(
         min_close_ts: int | None = None,
         min_updated_ts: int | None = None,
         limit: int | None = None,
+        max_pages: int | None = None,
     ) -> Iterator[Event]:
+        _validate_max_pages(max_pages)
         params = _list_events_params(
             status=status, series_ticker=series_ticker,
             with_nested_markets=with_nested_markets,
             with_milestones=with_milestones,
             min_close_ts=min_close_ts, min_updated_ts=min_updated_ts,
             limit=limit, cursor=None,
         )
-        return self._list_all("/events", Event, "events", params=params)
+        return self._list_all(
+            "/events", Event, "events", params=params, max_pages=max_pages,
+        )
 
     def list_multivariate(
         self,
@@ -120,14 +130,19 @@ def list_all_multivariate(
         collection_ticker: str | None = None,
         with_nested_markets: bool | None = None,
         limit: int | None = None,
+        max_pages: int | None = None,
     ) -> Iterator[Event]:
+        _validate_max_pages(max_pages)
         params = _list_multivariate_events_params(
             series_ticker=series_ticker,
             collection_ticker=collection_ticker,
             with_nested_markets=with_nested_markets,
             limit=limit, cursor=None,
         )
-        return self._list_all("/events/multivariate", Event, "events", params=params)
+        return self._list_all(
+            "/events/multivariate", Event, "events",
+            params=params, max_pages=max_pages,
+        )
 
     def get(
         self,
@@ -180,15 +195,19 @@ def list_all(
         min_close_ts: int | None = None,
         min_updated_ts: int | None = None,
         limit: int | None = None,
+        max_pages: int | None = None,
     ) -> AsyncIterator[Event]:
+        _validate_max_pages(max_pages)
         params = _list_events_params(
             status=status, series_ticker=series_ticker,
             with_nested_markets=with_nested_markets,
             with_milestones=with_milestones,
             min_close_ts=min_close_ts, min_updated_ts=min_updated_ts,
             limit=limit, cursor=None,
         )
-        return self._list_all("/events", Event, "events", params=params)
+        return self._list_all(
+            "/events", Event, "events", params=params, max_pages=max_pages,
+        )
 
     async def list_multivariate(
         self,
@@ -214,14 +233,19 @@ def list_all_multivariate(
         collection_ticker: str | None = None,
         with_nested_markets: bool | None = None,
         limit: int | None = None,
+        max_pages: int | None = None,
     ) -> AsyncIterator[Event]:
+        _validate_max_pages(max_pages)
         params = _list_multivariate_events_params(
             series_ticker=series_ticker,
             collection_ticker=collection_ticker,
             with_nested_markets=with_nested_markets,
             limit=limit, cursor=None,
         )
-        return self._list_all("/events/multivariate", Event, "events", params=params)
+        return self._list_all(
+            "/events/multivariate", Event, "events",
+            params=params, max_pages=max_pages,
+        )
 
     async def get(
         self,

kalshi/resources/fcm.py

@@ -18,7 +18,12 @@
 from kalshi.models.common import Page
 from kalshi.models.orders import Order, OrderStatusLiteral
 from kalshi.models.portfolio import PositionsResponse, SettlementStatusLiteral
-from kalshi.resources._base import AsyncResource, SyncResource, _params
+from kalshi.resources._base import (
+    AsyncResource,
+    SyncResource,
+    _params,
+    _validate_max_pages,
+)
 
 # Shared param builders (issue #46).
 
@@ -100,14 +105,19 @@ def orders_all(
         min_ts: int | None = None,
         max_ts: int | None = None,
         limit: int | None = None,
+        max_pages: int | None = None,
     ) -> Iterator[Order]:
         self._require_auth()
+        _validate_max_pages(max_pages)
         params = _fcm_orders_params(
             subtrader_id=subtrader_id, ticker=ticker,
             event_ticker=event_ticker, status=status,
             min_ts=min_ts, max_ts=max_ts, limit=limit, cursor=None,
         )
-        return self._list_all("/fcm/orders", Order, "orders", params=params)
+        return self._list_all(
+            "/fcm/orders", Order, "orders",
+            params=params, max_pages=max_pages,
+        )
 
     def positions(
         self,
@@ -164,15 +174,20 @@ def orders_all(
         min_ts: int | None = None,
         max_ts: int | None = None,
         limit: int | None = None,
+        max_pages: int | None = None,
     ) -> AsyncIterator[Order]:
         """Returns an async iterator — use ``async for``."""
         self._require_auth()
+        _validate_max_pages(max_pages)
         params = _fcm_orders_params(
             subtrader_id=subtrader_id, ticker=ticker,
             event_ticker=event_ticker, status=status,
             min_ts=min_ts, max_ts=max_ts, limit=limit, cursor=None,
         )
-        return self._list_all("/fcm/orders", Order, "orders", params=params)
+        return self._list_all(
+            "/fcm/orders", Order, "orders",
+            params=params, max_pages=max_pages,
+        )
 
     async def positions(
         self,