Polish bundle: REST resource small items (positions *_all(), enum validation, deprecation, list helpers, stale comment) #269

Summary

Small REST resource quality + consistency improvements bundled for a single PR.

Item 1 — portfolio.positions and fcm.positions ship no *_all() iterator

Every other cursor-paginated endpoint in the SDK yields a *_all() iterator. These two break the convention: callers walking the full position book must hand-roll the cursor loop and re-derive the _validate_max_pages / cursor-loop guard.

Location: kalshi/resources/portfolio.py:79-95, kalshi/resources/portfolio.py:215-231, kalshi/resources/fcm.py:125-144, kalshi/resources/fcm.py:195-214.

Fix: Add positions_all(...) on Portfolio + FCM, following the settlements_all pattern.

Item 2 — lookup_history skips client-side validation of lookback_seconds enum

Spec restricts lookback_seconds to {10, 60, 300, 3600}. Passing any other int costs a network round trip for a 400 — the exact ergonomic regression #229 closed for limit bounds.

Location: kalshi/resources/multivariate.py:229-241 (sync) + :366-378 (async); spec specs/openapi.yaml:3324-3337.

Fix: Raise ValueError when lookback_seconds not in {10, 60, 300, 3600} before issuing the GET.

Item 3 — Three deprecated multivariate endpoints exposed without any deprecation signal

Spec marks lookup_tickers, lookup_history, and the multivariate create_market family with deprecated: true and "DEPRECATED: This endpoint predates RFQs and should not be used for new integrations." The SDK re-exports them with no warning.

Location: kalshi/resources/multivariate.py:176-241, :312-378; spec specs/openapi.yaml:3239,3302.

Fix: Add .. deprecated:: notes to each docstring and emit warnings.warn(..., DeprecationWarning) on first call (or annotate with @typing_extensions.deprecated).

Item 4 — event_ticker / market_tickers kwargs accept only str on order-family endpoints

MarketsResource.list(tickers=[...]) works with a Python list via _join_tickers; OrdersResource.list(event_ticker=[...]) only accepts str and lacks the spec's max-10 client-side guard. Same on historical.markets(event_ticker=...) and fcm.orders(event_ticker=...).

Location: kalshi/resources/orders.py:243-264, historical.py:30-47, fcm.py:32-53; spec specs/openapi.yaml:3961-3967.

Fix: Widen to list[str] | str | None, run through _join_tickers(..., max_items=10), apply uniformly.

Item 5 — Stale contract-map note claims SDK still sends {event_ticker}

# tests/_contract_support.py
    # NOTE: SDK currently sends {event_ticker} but spec uses {ticker}.
    # Map stores the SPEC path (source of truth); SDK is RENAME target in AUDIT.

The rename it forecasts is already done; the SDK now uses ticker and the path_template matches the spec.

Location: tests/_contract_support.py:640-646.

Fix: Delete the stale NOTE block.

Severity & category

low / polish