Skip to content

Commit 6837342

Browse files
TexasCodingTexasCoding
authored
release: 3.0.0 — public-API rename release (#348, #349, #351) (#378)
* release: 3.0.0 — public-API rename release (#348, #349, #351) First major release in the v3 line. Three breaking-rename issues deferred from the v2.7.0 audit closure land with one-release deprecation aliases. Both old and new spellings work in v3.0.0; old names emit DeprecationWarning and will be removed no sooner than v3.1.0. Wire protocol unchanged from v2.7.0; v3 is purely a Python-API ergonomics break. - CommunicationsResource flat methods split into rfqs/quotes sub-namespaces (#348). 12 forwarders deprecated; new sub-resource classes exported from kalshi.__init__. - MarketsResource.list_trades_all → list_all_trades (#349) standardizing on the list_all_<noun> form used by Communications/Subaccounts. - OrdersResource.fills / fills_all → PortfolioResource.fills / fills_all (#351) aligning the SDK layout with the endpoint URL family. Migration guide at docs/migrations/v2-to-v3.md with BEFORE/AFTER snippets and a search-and-replace cheat sheet for downstream callers. Main is mypy --strict clean, ruff clean, 2954 unit tests passing. * polish(release): correct v3.0.0 date to 2026-05-22
1 parent 121fc26 commit 6837342

8 files changed

Lines changed: 298 additions & 4 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<!-- gitnexus:start -->
22
# GitNexus — Code Intelligence
33

4-
This project is indexed by GitNexus as **kalshi-python-sdk** (8490 symbols, 17402 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
4+
This project is indexed by GitNexus as **kalshi-python-sdk** (8568 symbols, 17351 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
55

66
> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
77

‎CHANGELOG.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,98 @@
22

33
All notable changes to kalshi-sdk will be documented in this file.
44

5+
## 3.0.0 — 2026-05-22
6+
7+
Public-API rename release. Three breaking-rename issues (`#348`, `#349`, `#351`)
8+
that were deferred from the v2.7.0 audit closure now land with **one-release
9+
deprecation aliases**: both old and new spellings work in v3.0.0; old names
10+
emit `DeprecationWarning` and will be removed in a future release (v3.1+).
11+
12+
This is the first release in the v3 line. The wire protocol is unchanged from
13+
v2.7.0; v3 is purely a public Python API ergonomics break.
14+
15+
### Migration
16+
17+
See `docs/migrations/v2-to-v3.md` for full BEFORE/AFTER snippets and a one-page
18+
search-and-replace cheat sheet.
19+
20+
### Breaking changes
21+
22+
All three changes ship with `@typing_extensions.deprecated` aliases on the old
23+
names — existing v2.x callers continue to work, but get a `DeprecationWarning`
24+
on every call until they migrate.
25+
26+
- **`CommunicationsResource` sub-namespaces** (`#348`). Flat noun-prefixed
27+
methods (`list_rfqs`, `get_rfq`, `create_rfq`, `delete_rfq`, `list_all_rfqs`,
28+
`list_quotes`, `get_quote`, `create_quote`, `delete_quote`, `accept_quote`,
29+
`confirm_quote`, `list_all_quotes`) are split into two sub-resources matching
30+
the OpenAPI v3.18.0 tag structure:
31+
32+
```python
33+
# v2.x (deprecated in v3.0.0)
34+
client.communications.list_rfqs(...)
35+
client.communications.create_rfq(...)
36+
client.communications.accept_quote(quote_id, accepted_side="yes")
37+
38+
# v3.0.0+
39+
client.communications.rfqs.list(...)
40+
client.communications.rfqs.create(...)
41+
client.communications.quotes.accept(quote_id, accepted_side="yes")
42+
```
43+
44+
The misc `client.communications.get_id(...)` stays at the top level (no
45+
sub-noun). The new sub-resource classes `RFQsResource`, `QuotesResource`,
46+
`AsyncRFQsResource`, `AsyncQuotesResource` are exported from `kalshi/__init__.py`
47+
for type annotations.
48+
49+
- **`MarketsResource.list_trades_all` → `list_all_trades`** (`#349`).
50+
Standardizes on `list_all_<noun>` matching the other three resources
51+
(`CommunicationsResource.list_all_rfqs`, `SubaccountsResource.list_all_transfers`,
52+
etc.). `list_trades_all` remains as a deprecated alias.
53+
54+
```python
55+
# v2.x (deprecated in v3.0.0)
56+
for trade in client.markets.list_trades_all(ticker="..."):
57+
...
58+
59+
# v3.0.0+
60+
for trade in client.markets.list_all_trades(ticker="..."):
61+
...
62+
```
63+
64+
- **`OrdersResource.fills` / `fills_all` → `PortfolioResource.fills` /
65+
`fills_all`** (`#351`). The endpoint URL is `/portfolio/fills`; this aligns
66+
the SDK layout with the URL family (`portfolio.settlements`,
67+
`portfolio.deposits`, `portfolio.withdrawals`). The old `OrdersResource.fills`
68+
/ `fills_all` remain as deprecated aliases.
69+
70+
```python
71+
# v2.x (deprecated in v3.0.0)
72+
page = client.orders.fills(ticker="...")
73+
74+
# v3.0.0+
75+
page = client.portfolio.fills(ticker="...")
76+
```
77+
78+
### Polish
79+
80+
- **`_fills_params` deduped** to `kalshi/resources/_base.py` (was duplicated in
81+
`orders.py` and `portfolio.py` during the relocation).
82+
83+
### Internal
84+
85+
- 78 new regression tests covering the deprecation-alias delegation and warning
86+
emission across sync + async pairs for every renamed method (12 communications
87+
forwarders × 2, plus markets + fills × 2 each).
88+
- `tests/_contract_support.py` `METHOD_ENDPOINT_MAP` registers both old and new
89+
spellings for the duration of the alias window.
90+
91+
### Deprecation removal schedule
92+
93+
The v3.0.0 aliases will be removed no sooner than **v3.1.0**. Callers should
94+
migrate before then. Each deprecated method has a `@typing_extensions.deprecated`
95+
decorator that surfaces in type checkers and IDEs per PEP 702.
96+
597
## 2.7.0 — 2026-05-22
698

799
Post-v2.6 independent multi-LLM reviewer audit closure. **47 issues filed

‎CLAUDE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -144,7 +144,7 @@ Reference issues from PRs via `Closes #N` so the issue closes on merge.
144144
<!-- gitnexus:start -->
145145
# GitNexus — Code Intelligence
146146

147-
This project is indexed by GitNexus as **kalshi-python-sdk** (8490 symbols, 17402 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
147+
This project is indexed by GitNexus as **kalshi-python-sdk** (8568 symbols, 17351 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
148148

149149
> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
150150

‎ROADMAP.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,22 @@
22

33
## Shipped
44

5+
- **v3.0.0 (2026-05-22)** — first major release in the v3 line. Three
6+
breaking-rename issues (`#348`, `#349`, `#351`) deferred from the v2.7.0
7+
audit closure land with one-release deprecation aliases:
8+
`CommunicationsResource` flat noun-prefixed methods split into
9+
`client.communications.{rfqs,quotes}.<verb>` sub-namespaces (`#348`);
10+
`MarketsResource.list_trades_all` → `list_all_trades` to match the
11+
`list_all_<noun>` convention used by Communications/Subaccounts (`#349`);
12+
`OrdersResource.fills` / `fills_all` relocate to `PortfolioResource`
13+
alongside `settlements` / `deposits` / `withdrawals` since the endpoint URL
14+
is `/portfolio/fills` (`#351`). Wire protocol unchanged. New
15+
`RFQsResource`/`QuotesResource`/`AsyncRFQsResource`/`AsyncQuotesResource`
16+
exported from `kalshi/__init__.py` for type annotations. 78 new regression
17+
tests covering deprecation-alias delegation and warning emission. Migration
18+
guide at `docs/migrations/v2-to-v3.md`. Aliases removed no sooner than
19+
v3.1.0.
20+
521
See `CHANGELOG.md` for full release history.
622

723
- **v2.7.0 (2026-05-22)** — post-v2.6 independent multi-LLM reviewer audit

‎docs/migration.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,27 @@
11
# Migration
22

3+
## v2.7 → v3.0
4+
5+
v3.0.0 is the first major release in the v3 line. It renames three groups of
6+
public methods (issues `#348`, `#349`, `#351`). The wire protocol is
7+
unchanged from v2.7.0; v3 is purely a Python-API ergonomics break.
8+
9+
**One-release deprecation window.** All old names continue to work in v3.0.0
10+
as `@typing_extensions.deprecated` aliases. Each emits `DeprecationWarning`
11+
on every call. Aliases will be removed no sooner than v3.1.0.
12+
13+
For full BEFORE/AFTER snippets and a one-page search-and-replace cheat sheet,
14+
see [v2-to-v3.md](migrations/v2-to-v3.md). Quick summary:
15+
16+
| Rename | Old (deprecated v3.0.0) | New (v3.0.0+) |
17+
|---|---|---|
18+
| Communications sub-namespaces | `client.communications.list_rfqs(...)` | `client.communications.rfqs.list(...)` |
19+
| | `client.communications.get_quote(id)` | `client.communications.quotes.get(id)` |
20+
| | (12 forwarders total across rfqs/quotes) | (same; sub-resource methods) |
21+
| `*_all` naming | `client.markets.list_trades_all(...)` | `client.markets.list_all_trades(...)` |
22+
| `fills` relocation | `client.orders.fills(...)` | `client.portfolio.fills(...)` |
23+
| | `client.orders.fills_all(...)` | `client.portfolio.fills_all(...)` |
24+
325
## v2.5 → v2.6
426

527
v2.6 ships two behavioral fences, both surface bugs that were already wrong:

‎docs/migrations/v2-to-v3.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Migrating from v2.x to v3.0.0
2+
3+
v3.0.0 renames three groups of public methods. All old names continue to work
4+
in v3.0.0 as `@typing_extensions.deprecated` aliases that emit
5+
`DeprecationWarning` on every call. The aliases will be removed no sooner than
6+
**v3.1.0**, so migrate before then.
7+
8+
The wire protocol is unchanged. v3 is purely a Python-API ergonomics break.
9+
10+
## TL;DR — search and replace cheat sheet
11+
12+
| Find | Replace |
13+
|---|---|
14+
| `.communications.list_rfqs(` | `.communications.rfqs.list(` |
15+
| `.communications.list_all_rfqs(` | `.communications.rfqs.list_all(` |
16+
| `.communications.get_rfq(` | `.communications.rfqs.get(` |
17+
| `.communications.create_rfq(` | `.communications.rfqs.create(` |
18+
| `.communications.delete_rfq(` | `.communications.rfqs.delete(` |
19+
| `.communications.list_quotes(` | `.communications.quotes.list(` |
20+
| `.communications.list_all_quotes(` | `.communications.quotes.list_all(` |
21+
| `.communications.get_quote(` | `.communications.quotes.get(` |
22+
| `.communications.create_quote(` | `.communications.quotes.create(` |
23+
| `.communications.delete_quote(` | `.communications.quotes.delete(` |
24+
| `.communications.accept_quote(` | `.communications.quotes.accept(` |
25+
| `.communications.confirm_quote(` | `.communications.quotes.confirm(` |
26+
| `.markets.list_trades_all(` | `.markets.list_all_trades(` |
27+
| `.orders.fills(` | `.portfolio.fills(` |
28+
| `.orders.fills_all(` | `.portfolio.fills_all(` |
29+
30+
These map 1:1 — argument signatures and return types are identical. The only
31+
behavioral difference is that the old names emit a `DeprecationWarning`.
32+
33+
## 1. CommunicationsResource sub-namespaces (#348)
34+
35+
The flat noun-prefixed methods on `CommunicationsResource` collapse into two
36+
sub-resources matching the OpenAPI v3.18.0 tag structure.
37+
38+
### Before (v2.x)
39+
40+
```python
41+
from kalshi import KalshiClient
42+
43+
client = KalshiClient.from_env()
44+
45+
rfqs = client.communications.list_rfqs(limit=50)
46+
rfq = client.communications.get_rfq("rfq-123")
47+
new = client.communications.create_rfq(market_ticker="MKT-1", rest_remainder=True)
48+
client.communications.delete_rfq("rfq-123")
49+
50+
quotes = client.communications.list_quotes(quote_creator_user_id="u1")
51+
client.communications.accept_quote("q-456", accepted_side="yes")
52+
client.communications.confirm_quote("q-456")
53+
```
54+
55+
### After (v3.0.0)
56+
57+
```python
58+
from kalshi import KalshiClient
59+
60+
client = KalshiClient.from_env()
61+
62+
rfqs = client.communications.rfqs.list(limit=50)
63+
rfq = client.communications.rfqs.get("rfq-123")
64+
new = client.communications.rfqs.create(market_ticker="MKT-1", rest_remainder=True)
65+
client.communications.rfqs.delete("rfq-123")
66+
67+
quotes = client.communications.quotes.list(quote_creator_user_id="u1")
68+
client.communications.quotes.accept("q-456", accepted_side="yes")
69+
client.communications.quotes.confirm("q-456")
70+
```
71+
72+
### Notes
73+
74+
- `client.communications.get_id(...)` (the misc endpoint) **stays at the top
75+
level** — no sub-noun.
76+
- The async API mirrors the sync API: `async_client.communications.rfqs.list(...)`.
77+
- If you type-annotate sub-resource attributes, import the new classes from the
78+
top level:
79+
```python
80+
from kalshi import RFQsResource, QuotesResource, AsyncRFQsResource, AsyncQuotesResource
81+
```
82+
83+
## 2. `*_all` naming standardization (#349)
84+
85+
`MarketsResource.list_trades_all` was the only outlier still using the
86+
`list_<noun>_all` suffix form. Renamed to `list_all_<noun>` (prefix form) to
87+
match the other three resources.
88+
89+
### Before (v2.x)
90+
91+
```python
92+
for trade in client.markets.list_trades_all(ticker="MKT-1", limit=200):
93+
process(trade)
94+
```
95+
96+
### After (v3.0.0)
97+
98+
```python
99+
for trade in client.markets.list_all_trades(ticker="MKT-1", limit=200):
100+
process(trade)
101+
```
102+
103+
Same iterator semantics, same filter kwargs.
104+
105+
## 3. `fills` relocation: orders → portfolio (#351)
106+
107+
The `/portfolio/fills` endpoint now sits on `PortfolioResource` alongside
108+
`settlements`, `deposits`, and `withdrawals` — matching the URL family.
109+
110+
### Before (v2.x)
111+
112+
```python
113+
page = client.orders.fills(ticker="MKT-1", min_ts=since)
114+
for fill in client.orders.fills_all(order_id="ord-1"):
115+
process(fill)
116+
```
117+
118+
### After (v3.0.0)
119+
120+
```python
121+
page = client.portfolio.fills(ticker="MKT-1", min_ts=since)
122+
for fill in client.portfolio.fills_all(order_id="ord-1"):
123+
process(fill)
124+
```
125+
126+
Signatures and return types are identical (`Page[Fill]` with `cursor`,
127+
`min_ts`, `max_ts`, `ticker`, `order_id`, etc.).
128+
129+
## Detecting deprecated calls during migration
130+
131+
The aliases use `@typing_extensions.deprecated` (PEP 702), which type checkers
132+
recognize. Add a stricter pytest config for the duration of your migration:
133+
134+
```toml
135+
# pyproject.toml
136+
[tool.pytest.ini_options]
137+
filterwarnings = [
138+
"error::DeprecationWarning:kalshi.*",
139+
]
140+
```
141+
142+
This turns every deprecated kalshi call into a test failure until you update.
143+
144+
For a softer approach, log warnings instead of erroring:
145+
146+
```python
147+
import warnings
148+
warnings.filterwarnings("default", category=DeprecationWarning, module=r"kalshi(\..*)?")
149+
```
150+
151+
## Why a major version for renames?
152+
153+
Per project policy (CHANGELOG §2.7.0), bug-surfacing behavioral fences ship in
154+
minor releases; intentional public-API renames are reserved for major releases.
155+
v3.0.0 is the first major version under this policy. v2.5–v2.7 each shipped
156+
behavioral fences in minor versions because they surfaced silent bugs;
157+
v3.0.0 renames previously-correct method names purely for API ergonomics.
158+
159+
## Removal schedule
160+
161+
The deprecated aliases will be removed no sooner than **v3.1.0**. Migration
162+
done before then is forward-compatible across all v3.x.

‎mkdocs.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,5 +102,7 @@ nav:
102102
- Live data: resources/live-data.md
103103
- WebSocket: websockets.md
104104
- Testing: testing.md
105-
- Migration: migration.md
105+
- Migration:
106+
- Overview: migration.md
107+
- v2 → v3: migrations/v2-to-v3.md
106108
- API Reference: reference.md

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[project]
22
name = "kalshi-sdk"
3-
version = "2.7.0"
3+
version = "3.0.0"
44
description = "A professional Python SDK for the Kalshi prediction markets API"
55
readme = "README.md"
66
license = { text = "MIT" }

0 commit comments

Comments
 (0)