Async *_all iterator-factory methods inconsistently document their non-awaitable return contract #334

Problem

All async *_all methods share the same shape: plain def returning AsyncIterator[T], eagerly running _require_auth() / _validate_max_pages() before delegating to an async def _list_all generator. The docstring warning that the method itself is NOT awaitable is present on some (AsyncOrdersResource.list_all, AsyncMarketsResource.list_trades_all, AsyncPortfolioResource.deposits_all / withdrawals_all / positions_all) and absent on others.

Concrete trigger: a user, primed by await client.orders.list(...), types it = await client.orders.fills_all(...) and gets TypeError: object AsyncIterator can't be used in 'await' expression. The same mistake against list_all is caught by IDE hover / Sphinx docs because the method has a marker docstring; against fills_all it is not. The sync side has no such trap because sync iterators iterate either way.

Evidence

• kalshi/resources/orders.py:1041-1054 — AsyncOrdersResource.list_all has the marker docstring:

def list_all(
    self,
    ...
) -> AsyncIterator[Order]:
    """Non-async method that returns an async iterator for direct use with `async for`."""
    self._require_auth()

• kalshi/resources/orders.py:1153-1166 — AsyncOrdersResource.fills_all has none:

def fills_all(
    self,
    ...
) -> AsyncIterator[Fill]:
    self._require_auth()
    _validate_max_pages(max_pages)

• kalshi/resources/portfolio.py:388-400 — AsyncPortfolioResource.settlements_all has none either:

def settlements_all(
    self,
    ...
) -> AsyncIterator[Settlement]:
    self._require_auth()

Suggested fix

Standardize on the one-line marker docstring across every async *_all (e.g. """Returns an async iterator — use ``async for``, do not ``await``."""). Same pattern Sphinx already picks up on the methods that have it today. Apply to at minimum AsyncOrdersResource.fills_all and AsyncPortfolioResource.settlements_all; sweep all async *_all methods for parity.

Source

Round-3 independent audit (reviewer: sync_async_parity).