release: 2.5.0 — post-v2.4 multi-reviewer SDK audit closure (#273)

[TexasCoding]

Cuts v2.5.0.

What ships

34 audit issues closed across 4 sequential waves:

• W0 docs — Docs: migration guide is missing the v2.3 → v2.4 section that documents #194 batch breaking shape #246 Docs: orders.md batch_create example crashes under the v2.4 return type #247 Docs: README pagination quickstart references non-existent Page.has_more (should be has_next) #248 Docs: breaking-change docstrings tag the change as v3.0.0 but it shipped in v2.4.0 #265 (PRs docs(orders): correct breaking-change version tags v3.0.0 → v2.4.0 #274–docs(migration): add v2.3→v2.4 section #277)
• W1 money-risk — Config: demo=True + base_url override silently produces split REST/WS environment #239 Transport: httpx network errors (ConnectError/NetworkError/etc.) never retry, even for GET/HEAD/OPTIONS #240 WS: validation failure on sequenced frame advances seq watermark — silent orderbook desync #241 orders.create() silently defaults count=1 and action="buy" on the kwarg path #242 Orders: CreateOrderRequest.buy_max_cost validator accepts bool — silently becomes 1 cent #243 WS perf: subscribe_book iterator re-materializes the entire orderbook on every delta #244 WS perf: per-frame asyncio.Task + asyncio.shield allocation in WS recv loop #245 (PRs fix+perf(ws): seq rollback on pre-validation failure; drop per-frame shield; cache materialized orderbook #278–fix(orders): require count+action on create() kwarg path; reject bool in buy_max_cost #281)
• W2.1 medium — Auth: conflicting key inputs (constructor + env) silently prefer one without warning #249 Config: unknown base_url host only warns — typo silently signs to attacker #250 Errors: 408 and 504 do not map to KalshiTimeoutError #251 Errors: content-length cap on error body drops the typed-exception class #252 WS: resubscribe_one stash is never drained — frames captured during gap recovery are dropped #254 WS: stale orderbook frames mutate local book before subscription-existence check #255 WS: KalshiBackpressureError lacks structured channel/sid/client_id fields #256 WS: _OrderbookIterator yields silently-empty Orderbook when manager has no book #257 Models: WS payloads use raw str for _fp / _dollars fields (OrderGroup, Ticker) #258 Models: Strike + fee-multiplier fields use bare Decimal/float, bypass #225 coercion #259 Perf: _normalize_percent_encoding runs a regex on every signed path even when no % is present #261 Perf: header merge allocates a fresh 4-way dict per retry attempt #262 Perf: snapshot apply walks the level list twice (validate tuples, then rebuild dict) #263 Perf: Page.to_dataframe / to_polars goes through per-row Pydantic dumps #264 Types: KalshiClient.from_env(**kwargs: object) leaks Any-equivalent typing into a public constructor #266 (PRs perf(ws): collapse snapshot apply into a single dict walk (#263) #282–feat(auth+config): defense-in-depth (#249, #266, #261, #250) #287)
• W2.2 REST DX — Transport: per-request extra_headers is unreachable through any resource method #253 Perf: REST has no pluggable JSON loader — orjson cannot speed up list parsing #260 (PR feat(rest): pluggable JSON loader + plumb extra_headers through resources (#260, #253) #288)
• W3 polish — Polish bundle: auth + transport small items (sign-executor race, Retry-After negative) #267 Polish bundle: WS small items (cancelled mid-subscribe leak, snapshot empty-array default) #268 Polish bundle: REST resource small items (positions *_all(), enum validation, deprecation, list helpers, stale comment) #269 Polish bundle: model small items (AwareDatetime in WS, V1 Literal, default=None, timestamp typing, Decimal NaN) #270 Polish bundle: perf + testing small items (asyncio import, MessageQueue._size, http2 test, iterator/dataframe bench) #271 Polish bundle: docs cleanup (stale ROADMAP entry, missing PyPI classifiers) #272 (PRs polish(auth+transport): sign-executor race, Retry-After parity, MessageQueue, http2 test, benches #289–polish(ws): release orphan subscribe acks; require snapshot yes/no #293)

20 PRs total; main is mypy strict clean, ruff clean, 2742 unit tests passing (3 skipped — tests/test_http2.py skipif when h2 extra not installed).

Breaking changes (justify v2.5.0 minor bump)

1. orders.create() silently defaults count=1 and action="buy" on the kwarg path #242 — orders.create() requires count and action explicitly on the kwarg path (no silent 1-contract buy).
2. Models: WS payloads use raw str for _fp / _dollars fields (OrderGroup, Ticker) #258 + Models: Strike + fee-multiplier fields use bare Decimal/float, bypass #225 coercion #259 — six REST model fields + three WS payload fields widened from str/float to Decimal. Wire format unchanged.

Migration guide: docs/migration.md v2.4 → v2.5 section (this PR).

Release procedure (post-merge)

Per docs/RELEASING.md:

1. Merge this PR.
2. git tag v2.5.0 && git push origin v2.5.0 — .github/workflows/release.yml will build + publish to PyPI via trusted publishing + create the GitHub Release.

Verification

• pyproject.toml + kalshi/__init__.py __version__ both bumped to 2.5.0 (release workflow asserts they match the tag).
• CHANGELOG section is in the format the release workflow extracts (## 2.5.0 — 2026-05-21 heading; awk extracts up to the next ## ).
• ROADMAP Shipped section updated.

Closes #273.

[claude]

Code Review — PR #294: release v2.5.0

This is a release/documentation PR (version bumps + CHANGELOG + ROADMAP + migration guide). The actual code changes landed across 20 prior PRs; I'll review what's in this diff and flag anything worth discussing before merge.

---

Overview

The diff is small and focused:

• kalshi/__init__.py + pyproject.toml — 2.4.0 → 2.5.0
• CHANGELOG.md — new ## 2.5.0 — 2026-05-21 section
• ROADMAP.md — shipped entry for v2.5.0
• docs/migration.md — new v2.4 → v2.5 section

No application code changes are in this PR, which is the correct pattern for a release cut.

---

What looks good

• Version consistency. Both pyproject.toml and kalshi/__init__.py are bumped to 2.5.0. The release workflow asserts they match the tag — no drift here.
• CHANGELOG format. The ## 2.5.0 — 2026-05-21 heading matches the awk extraction pattern documented in the release procedure. No format surprises for the workflow.
• Migration guide quality. The v2.4 → v2.5 section is the strongest migration doc in the file. Every breaking change has a before/after code snippet, every additive feature has a usage example, and the "Observable but not breaking" section gives consumers a heads-up on type shape changes without overstating the impact.
• Breaking changes are front-and-center. Both the PR description and the CHANGELOG lead with the two breakages (orders.create() silently defaults count=1 and action="buy" on the kwarg path #242, Models: WS payloads use raw str for _fp / _dollars fields (OrderGroup, Ticker) #258/Models: Strike + fee-multiplier fields use bare Decimal/float, bypass #225 coercion #259), which is good hygiene for a minor version bump.
• Security improvements documented clearly. #239 (split-env guard), #250 (unknown-host default-fail), and #249 (conflicting key inputs) are all called out with rationale. The migration guide explains the opt-out path for allow_unknown_host.

---

Issues / things to verify before merge

1. OrderbookSnapshotPayload.yes/no type change is arguably breaking

The "Observable but not breaking" section in docs/migration.md lists:

OrderbookSnapshotPayload.yes and .no are now dict[Decimal, Decimal] rather than list[tuple[Decimal, Decimal]]

For any consumer reading those fields directly (not just through subscribe_book), this is a type-breaking change — dict and list[tuple] have different iteration contracts. It's worth either moving this to the "Breaking changes" section or adding a one-line note acknowledging that direct consumers of those fields are affected. The current framing may give users false confidence that no code review is needed on their side.

2. v2.4.0 and v2.5.0 share the same release date (2026-05-21)

Both CHANGELOG entries are dated 2026-05-21. This is technically fine, but it may confuse users scanning the changelog for "what changed since my version." If time permits, it could be worth noting in the CHANGELOG that v2.5 was released on the same day as v2.4 (e.g., a parenthetical like "released same-day as v2.4"). Low priority — the issue-reference trail makes the relationship clear.

3. KalshiNetworkError — verify it's exported from kalshi/__init__.py

The CHANGELOG introduces KalshiNetworkError as a new typed exception. This diff doesn't include kalshi/__init__.py changes to the __all__ list (only __version__ changed). If KalshiNetworkError was added in a prior PR (#240), verify it's already exported from the public surface — consumers catching it by name will get ImportError otherwise.

4. ConnectError retry on POST — documentation clarity

The CHANGELOG says:

ConnectError on POST/DELETE is also safe (request never reached the wire)

This is correct for TCP-level connect failures. However, some proxies or TLS termination points can establish the TCP connection but fail before the request bytes are sent — ConnectError can fire at the TLS handshake stage where the server may have partially seen the request. The migration guide doesn't mention this nuance. Given that this is a financial API, worth adding a one-liner like "callers should still reconcile POST outcomes via client_order_id when KalshiNetworkError is caught" to set expectations correctly.

---

Minor suggestions

• The ROADMAP entry for v2.5.0 is well-written but references parenthetical issue numbers densely. Consider splitting the performance and DX bullets into two sentences for readability — purely cosmetic.
• The migration guide's "Observable but not breaking" section correctly calls out Retry-After: -5 clamping. It would be helpful to note whether this changes behavior for users who were relying on the old fallback-to-backoff behavior (i.e., they now retry faster than before). Minor, but relevant for anyone with tight rate-limit tolerance.

---

Summary

The release artifacts look correct and the documentation is thorough. Three things worth a quick confirmation before merging:

1. Verify KalshiNetworkError is already in kalshi/__init__.py's __all__ (from a prior PR).
2. Consider whether OrderbookSnapshotPayload.yes/no dict-vs-list change belongs in the breaking changes section.
3. Add a reconciliation note on ConnectError-on-POST retry for financial safety clarity.

Everything else looks merge-ready.