quantpad-data 0.9.0__tar.gz → 0.10.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (25) hide show
  1. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/PKG-INFO +82 -18
  2. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/README.md +81 -17
  3. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/pyproject.toml +1 -1
  4. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/quantpad_data/__init__.py +14 -2
  5. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/quantpad_data/client.py +229 -1
  6. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/quantpad_data/errors.py +14 -0
  7. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/quantpad_data/v2.py +68 -5
  8. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/tests/test_client.py +155 -0
  9. quantpad_data-0.10.1/tests/test_in_app_only.py +62 -0
  10. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/tests/test_v2.py +51 -0
  11. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/.gitignore +0 -0
  12. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/quantpad_data/cache.py +0 -0
  13. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/quantpad_data/lean.py +0 -0
  14. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/quantpad_data/memory.py +0 -0
  15. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/quantpad_data/py.typed +0 -0
  16. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/quantpad_data/rth.py +0 -0
  17. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/tests/conftest.py +0 -0
  18. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/tests/test_lean.py +0 -0
  19. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/tests/test_message_encoding.py +0 -0
  20. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/tests/test_packaging.py +0 -0
  21. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/tests/test_refusal_hint.py +0 -0
  22. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/tests/test_rth.py +0 -0
  23. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/tests/test_v2_cache.py +0 -0
  24. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/tests/test_v2_gate.py +0 -0
  25. {quantpad_data-0.9.0 → quantpad_data-0.10.1}/tests/test_version.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: quantpad-data
3
- Version: 0.9.0
3
+ Version: 0.10.1
4
4
  Summary: Official Python client for the QuantPad market-data API
5
5
  Project-URL: Documentation, https://api.quantpad.ai/external/docs
6
6
  Author: QuantPad
@@ -49,7 +49,7 @@ import time
49
49
  import quantpad_data as qpd
50
50
 
51
51
  end = int(time.time() * 1000)
52
- bars = qpd.get_bars("ES.FUT", "1m", end - 86_400_000, end)
52
+ bars = qpd.get_bars("SPY", "1m", end - 86_400_000, end)
53
53
 
54
54
  for chunk in qpd.get_ticks(
55
55
  "AAPL", "trades", end - 3_600_000, end, columns=["t", "price", "size"]
@@ -59,7 +59,7 @@ for chunk in qpd.get_ticks(
59
59
  # 10-level L2 market-by-price order-book depth. This streams chunks;
60
60
  # project columns to avoid materializing all 60+ book fields when unnecessary.
61
61
  for chunk in qpd.get_mbp10(
62
- "ES.FUT",
62
+ "AAPL",
63
63
  end - 3_600_000,
64
64
  end,
65
65
  columns=["t", "bid_px_00", "ask_px_00", "bid_sz_00", "ask_sz_00"],
@@ -80,16 +80,33 @@ connect timeouts are still retried, because failing to reach the service
80
80
  costs the service nothing.
81
81
  QuantPad notebooks remain compatible through `QUANTPAD_NOTEBOOK_DATA_TOKEN`.
82
82
 
83
+ ### CME futures data
84
+
85
+ CME futures data (dataset `GLBX.MDP3`: ES, NQ, CL and every other CME future
86
+ and option on futures) is available inside QuantPad only. With an API key the
87
+ SDK raises `InAppOnlyError` (a `PermissionDeniedError`) for it, with a message
88
+ saying so; `get_universe()` and `get_coverage()` still answer for CME
89
+ symbols. To work with CME data, create a new project at https://quantpad.ai
90
+ and run your code there: inside a project the same calls return it, and no
91
+ API key is needed.
92
+
93
+ ```python
94
+ try:
95
+ qpd.get_bars("ES.v.0", "1m", end - 86_400_000, end)
96
+ except qpd.InAppOnlyError as exc:
97
+ print(exc) # available inside QuantPad only; create a project to use it
98
+ ```
99
+
83
100
  Bars preserve the notebook helper's OHLCV aliases and smart futures
84
101
  back-adjustment default. Tick timestamps are epoch nanoseconds.
85
102
 
86
103
  `mbp-10` is true L2 depth with bid/ask price, size, and order-count fields at
87
- levels 0-9. It is available for supported CME futures, individual CME
88
- options-on-futures contracts, and US equities, subject to `get_coverage()` and
89
- the plan lookback window (currently 30 days).
104
+ levels 0-9. With an API key it is available for US equities, subject to
105
+ `get_coverage()` and the plan lookback window (currently 30 days).
90
106
 
91
107
  This SDK intentionally exposes only bars, ticks, universe, coverage,
92
- symbology, and SEC insider transactions. It does not proxy FRED or SEC EDGAR.
108
+ symbology, SEC insider transactions, and company fundamentals and earnings
109
+ events from SEC filings. It does not proxy FRED or SEC EDGAR.
93
110
 
94
111
  ## SEC insider transactions
95
112
 
@@ -122,6 +139,44 @@ current, counted once, and sanely priced. For a backtest, use `accepted_at`
122
139
  (UTC), or the end of `filed_date` where it is null, as the event time; never
123
140
  `trans_date`, because insiders have two business days to file.
124
141
 
142
+ ## Company fundamentals and earnings
143
+
144
+ `get_fundamentals` returns 32 standard fields (revenue, net income, EPS,
145
+ total assets, operating cash flow, ...) for US companies that file 10-Ks and
146
+ 10-Qs, from SEC filings since 2009, refreshed nightly. Every value keeps the
147
+ time it became public, and restatements are kept as later versions, so a
148
+ backtest can see exactly what was known on a given day.
149
+
150
+ ```python
151
+ # quarters, one column per field
152
+ df = qpd.get_fundamentals("AAPL", fields=["revenue", "eps_diluted", "total_assets"],
153
+ start="2020-01-01")
154
+
155
+ # fiscal years
156
+ df = qpd.get_fundamentals("AAPL", period="annual")
157
+
158
+ # what a reader had on a day: the newest restatement known by then
159
+ df = qpd.get_fundamentals("AAPL", version="latest", as_of="2024-06-01")
160
+
161
+ # one row per value, with when it became public and which filing carried it
162
+ df = qpd.get_fundamentals("AAPL", wide=False)
163
+ ```
164
+
165
+ A fourth quarter the company did not file on its own is the year less nine
166
+ months, marked `derived` in the long form. Per-share values are never derived,
167
+ so such a quarter has no EPS.
168
+
169
+ `get_earnings` returns one row per period a company reported: when the results
170
+ went public (`announced_at`, UTC to the second, from the 8-K that released them
171
+ or else the 10-Q/10-K), before, during or after the session, and the filed
172
+ figures with the same quarter a year earlier. Upcoming dates and analyst
173
+ estimates are not included.
174
+
175
+ ```python
176
+ df = qpd.get_earnings("AAPL")
177
+ week = qpd.get_earnings(start="2026-10-26", end="2026-11-07") # every company
178
+ ```
179
+
125
180
  ## Explicit addressing: `qpd.v2`
126
181
 
127
182
  > **Not open yet.** `/v2` is limited to a small allowlist while it is
@@ -134,7 +189,7 @@ current, counted once, and sanely priced. For a backtest, use `accepted_at`
134
189
 
135
190
  The helpers above infer which dataset a symbol lives in and what kind of
136
191
  symbol it is. That is convenient until it is wrong, and when it is wrong it
137
- fails quietly — asking for a specific futures contract returns an empty frame
192
+ fails quietly: a symbol looked up on the wrong venue returns an empty frame
138
193
  that looks exactly like a coverage gap.
139
194
 
140
195
  `qpd.v2.Historical` removes the inference. Every call names its dataset and
@@ -146,18 +201,18 @@ import quantpad_data as qpd
146
201
  client = qpd.v2.Historical()
147
202
 
148
203
  bars = client.timeseries.get_range(
149
- dataset="GLBX.MDP3", # required — never guessed
150
- symbols="ESZ6", # a specific contract month
204
+ dataset="XNAS.ITCH", # required, never guessed
205
+ symbols="AAPL",
151
206
  stype_in="raw_symbol", # raw_symbol | instrument_id | parent | continuous
152
207
  schema="ohlcv-1m",
153
208
  start="2026-01-05",
154
209
  end="2026-01-06",
155
210
  )
156
211
 
157
- # What actually answered, so you can confirm it was the contract you meant.
212
+ # What actually answered, so you can confirm it was the instrument you meant.
158
213
  print(bars.attrs["quantpad"])
159
- # {'dataset': 'GLBX.MDP3', 'stype_in': 'raw_symbol',
160
- # 'resolved': 'ESZ6=651968', 'clamped': False, ...}
214
+ # {'dataset': 'XNAS.ITCH', 'stype_in': 'raw_symbol',
215
+ # 'resolved': 'AAPL=<instrument_id>', 'clamped': False, ...}
161
216
  ```
162
217
 
163
218
  Every response reports the address it used, and a window that had to be
@@ -185,7 +240,7 @@ delivery path with `mode="interactive"` or `mode="bulk"`, or stream day by day:
185
240
 
186
241
  ```python
187
242
  for day in client.timeseries.iter_range(
188
- dataset="GLBX.MDP3", symbols="ESZ6", schema="mbp-10",
243
+ dataset="XNAS.ITCH", symbols="AAPL", schema="trades",
189
244
  start="2026-01-05", end="2026-02-05",
190
245
  ):
191
246
  process(day)
@@ -200,13 +255,22 @@ For ranges too large even for that, submit a batch job, then hydrate it into
200
255
  the cache so ordinary `get_range` calls serve it from storage:
201
256
 
202
257
  ```python
203
- job = client.batch.submit(
204
- dataset="GLBX.MDP3", symbols="ESZ6", schema="mbp-10",
205
- start="2026-01-05", end="2026-02-05", hydrate=True,
258
+ submitted = client.batch.submit(
259
+ dataset="XNAS.ITCH", symbols="AAPL", schema="trades",
260
+ start="2026-01-05", end="2026-02-05",
206
261
  )
207
- client.batch.hydrate(job["job_id"])
262
+ job_id = submitted["job"]["job_id"]
263
+ # ...once client.batch.list_jobs() shows the job as "done":
264
+ result = client.batch.hydrate(job_id) # waits; returns written/empty/skipped
208
265
  ```
209
266
 
267
+ The hydrate runs on the service, not in your process. `hydrate()` polls it
268
+ until it finishes (pass `timeout=` to bound the wait, or `wait=False` to return
269
+ at once), and `client.batch.hydrate_status(job_id)` reports `state`,
270
+ `files_done` and `files_total` at any time. If it is `interrupted`, call
271
+ `hydrate()` again: it resumes after the days already written. Submitting with
272
+ `hydrate=True` instead starts the hydrate as soon as the job has rendered.
273
+
210
274
  ### Regular trading hours
211
275
 
212
276
  `get_range` returns the whole published session, which for US equities includes
@@ -27,7 +27,7 @@ import time
27
27
  import quantpad_data as qpd
28
28
 
29
29
  end = int(time.time() * 1000)
30
- bars = qpd.get_bars("ES.FUT", "1m", end - 86_400_000, end)
30
+ bars = qpd.get_bars("SPY", "1m", end - 86_400_000, end)
31
31
 
32
32
  for chunk in qpd.get_ticks(
33
33
  "AAPL", "trades", end - 3_600_000, end, columns=["t", "price", "size"]
@@ -37,7 +37,7 @@ for chunk in qpd.get_ticks(
37
37
  # 10-level L2 market-by-price order-book depth. This streams chunks;
38
38
  # project columns to avoid materializing all 60+ book fields when unnecessary.
39
39
  for chunk in qpd.get_mbp10(
40
- "ES.FUT",
40
+ "AAPL",
41
41
  end - 3_600_000,
42
42
  end,
43
43
  columns=["t", "bid_px_00", "ask_px_00", "bid_sz_00", "ask_sz_00"],
@@ -58,16 +58,33 @@ connect timeouts are still retried, because failing to reach the service
58
58
  costs the service nothing.
59
59
  QuantPad notebooks remain compatible through `QUANTPAD_NOTEBOOK_DATA_TOKEN`.
60
60
 
61
+ ### CME futures data
62
+
63
+ CME futures data (dataset `GLBX.MDP3`: ES, NQ, CL and every other CME future
64
+ and option on futures) is available inside QuantPad only. With an API key the
65
+ SDK raises `InAppOnlyError` (a `PermissionDeniedError`) for it, with a message
66
+ saying so; `get_universe()` and `get_coverage()` still answer for CME
67
+ symbols. To work with CME data, create a new project at https://quantpad.ai
68
+ and run your code there: inside a project the same calls return it, and no
69
+ API key is needed.
70
+
71
+ ```python
72
+ try:
73
+ qpd.get_bars("ES.v.0", "1m", end - 86_400_000, end)
74
+ except qpd.InAppOnlyError as exc:
75
+ print(exc) # available inside QuantPad only; create a project to use it
76
+ ```
77
+
61
78
  Bars preserve the notebook helper's OHLCV aliases and smart futures
62
79
  back-adjustment default. Tick timestamps are epoch nanoseconds.
63
80
 
64
81
  `mbp-10` is true L2 depth with bid/ask price, size, and order-count fields at
65
- levels 0-9. It is available for supported CME futures, individual CME
66
- options-on-futures contracts, and US equities, subject to `get_coverage()` and
67
- the plan lookback window (currently 30 days).
82
+ levels 0-9. With an API key it is available for US equities, subject to
83
+ `get_coverage()` and the plan lookback window (currently 30 days).
68
84
 
69
85
  This SDK intentionally exposes only bars, ticks, universe, coverage,
70
- symbology, and SEC insider transactions. It does not proxy FRED or SEC EDGAR.
86
+ symbology, SEC insider transactions, and company fundamentals and earnings
87
+ events from SEC filings. It does not proxy FRED or SEC EDGAR.
71
88
 
72
89
  ## SEC insider transactions
73
90
 
@@ -100,6 +117,44 @@ current, counted once, and sanely priced. For a backtest, use `accepted_at`
100
117
  (UTC), or the end of `filed_date` where it is null, as the event time; never
101
118
  `trans_date`, because insiders have two business days to file.
102
119
 
120
+ ## Company fundamentals and earnings
121
+
122
+ `get_fundamentals` returns 32 standard fields (revenue, net income, EPS,
123
+ total assets, operating cash flow, ...) for US companies that file 10-Ks and
124
+ 10-Qs, from SEC filings since 2009, refreshed nightly. Every value keeps the
125
+ time it became public, and restatements are kept as later versions, so a
126
+ backtest can see exactly what was known on a given day.
127
+
128
+ ```python
129
+ # quarters, one column per field
130
+ df = qpd.get_fundamentals("AAPL", fields=["revenue", "eps_diluted", "total_assets"],
131
+ start="2020-01-01")
132
+
133
+ # fiscal years
134
+ df = qpd.get_fundamentals("AAPL", period="annual")
135
+
136
+ # what a reader had on a day: the newest restatement known by then
137
+ df = qpd.get_fundamentals("AAPL", version="latest", as_of="2024-06-01")
138
+
139
+ # one row per value, with when it became public and which filing carried it
140
+ df = qpd.get_fundamentals("AAPL", wide=False)
141
+ ```
142
+
143
+ A fourth quarter the company did not file on its own is the year less nine
144
+ months, marked `derived` in the long form. Per-share values are never derived,
145
+ so such a quarter has no EPS.
146
+
147
+ `get_earnings` returns one row per period a company reported: when the results
148
+ went public (`announced_at`, UTC to the second, from the 8-K that released them
149
+ or else the 10-Q/10-K), before, during or after the session, and the filed
150
+ figures with the same quarter a year earlier. Upcoming dates and analyst
151
+ estimates are not included.
152
+
153
+ ```python
154
+ df = qpd.get_earnings("AAPL")
155
+ week = qpd.get_earnings(start="2026-10-26", end="2026-11-07") # every company
156
+ ```
157
+
103
158
  ## Explicit addressing: `qpd.v2`
104
159
 
105
160
  > **Not open yet.** `/v2` is limited to a small allowlist while it is
@@ -112,7 +167,7 @@ current, counted once, and sanely priced. For a backtest, use `accepted_at`
112
167
 
113
168
  The helpers above infer which dataset a symbol lives in and what kind of
114
169
  symbol it is. That is convenient until it is wrong, and when it is wrong it
115
- fails quietly — asking for a specific futures contract returns an empty frame
170
+ fails quietly: a symbol looked up on the wrong venue returns an empty frame
116
171
  that looks exactly like a coverage gap.
117
172
 
118
173
  `qpd.v2.Historical` removes the inference. Every call names its dataset and
@@ -124,18 +179,18 @@ import quantpad_data as qpd
124
179
  client = qpd.v2.Historical()
125
180
 
126
181
  bars = client.timeseries.get_range(
127
- dataset="GLBX.MDP3", # required — never guessed
128
- symbols="ESZ6", # a specific contract month
182
+ dataset="XNAS.ITCH", # required, never guessed
183
+ symbols="AAPL",
129
184
  stype_in="raw_symbol", # raw_symbol | instrument_id | parent | continuous
130
185
  schema="ohlcv-1m",
131
186
  start="2026-01-05",
132
187
  end="2026-01-06",
133
188
  )
134
189
 
135
- # What actually answered, so you can confirm it was the contract you meant.
190
+ # What actually answered, so you can confirm it was the instrument you meant.
136
191
  print(bars.attrs["quantpad"])
137
- # {'dataset': 'GLBX.MDP3', 'stype_in': 'raw_symbol',
138
- # 'resolved': 'ESZ6=651968', 'clamped': False, ...}
192
+ # {'dataset': 'XNAS.ITCH', 'stype_in': 'raw_symbol',
193
+ # 'resolved': 'AAPL=<instrument_id>', 'clamped': False, ...}
139
194
  ```
140
195
 
141
196
  Every response reports the address it used, and a window that had to be
@@ -163,7 +218,7 @@ delivery path with `mode="interactive"` or `mode="bulk"`, or stream day by day:
163
218
 
164
219
  ```python
165
220
  for day in client.timeseries.iter_range(
166
- dataset="GLBX.MDP3", symbols="ESZ6", schema="mbp-10",
221
+ dataset="XNAS.ITCH", symbols="AAPL", schema="trades",
167
222
  start="2026-01-05", end="2026-02-05",
168
223
  ):
169
224
  process(day)
@@ -178,13 +233,22 @@ For ranges too large even for that, submit a batch job, then hydrate it into
178
233
  the cache so ordinary `get_range` calls serve it from storage:
179
234
 
180
235
  ```python
181
- job = client.batch.submit(
182
- dataset="GLBX.MDP3", symbols="ESZ6", schema="mbp-10",
183
- start="2026-01-05", end="2026-02-05", hydrate=True,
236
+ submitted = client.batch.submit(
237
+ dataset="XNAS.ITCH", symbols="AAPL", schema="trades",
238
+ start="2026-01-05", end="2026-02-05",
184
239
  )
185
- client.batch.hydrate(job["job_id"])
240
+ job_id = submitted["job"]["job_id"]
241
+ # ...once client.batch.list_jobs() shows the job as "done":
242
+ result = client.batch.hydrate(job_id) # waits; returns written/empty/skipped
186
243
  ```
187
244
 
245
+ The hydrate runs on the service, not in your process. `hydrate()` polls it
246
+ until it finishes (pass `timeout=` to bound the wait, or `wait=False` to return
247
+ at once), and `client.batch.hydrate_status(job_id)` reports `state`,
248
+ `files_done` and `files_total` at any time. If it is `interrupted`, call
249
+ `hydrate()` again: it resumes after the days already written. Submitting with
250
+ `hydrate=True` instead starts the hydrate as soon as the job has rendered.
251
+
188
252
  ### Regular trading hours
189
253
 
190
254
  `get_range` returns the whole published session, which for US equities includes
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "quantpad-data"
7
- version = "0.9.0"
7
+ version = "0.10.1"
8
8
  description = "Official Python client for the QuantPad market-data API"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -11,6 +11,7 @@ import pyarrow as pa
11
11
  from .client import Client, ROLL_ADJUST_MODES, TICK_SCHEMAS, USER_AGENT, VERSION
12
12
  from .errors import (
13
13
  AuthenticationError,
14
+ InAppOnlyError,
14
15
  IncompleteResponseError,
15
16
  NotFoundError,
16
17
  PermissionDeniedError,
@@ -89,6 +90,17 @@ def get_coverage(symbol: str):
89
90
  return _client().get_coverage(symbol)
90
91
 
91
92
 
93
+ def get_fundamentals(ticker=None, **kwargs):
94
+ """Company fundamentals from SEC filings, point in time; see
95
+ :meth:`Client.get_fundamentals`."""
96
+ return _client().get_fundamentals(ticker, **kwargs)
97
+
98
+
99
+ def get_earnings(ticker=None, **kwargs):
100
+ """Earnings events from SEC filings; see :meth:`Client.get_earnings`."""
101
+ return _client().get_earnings(ticker, **kwargs)
102
+
103
+
92
104
  def get_insider_transactions(ticker=None, **kwargs):
93
105
  """SEC insider transactions (Forms 3/4/5); see
94
106
  :meth:`Client.get_insider_transactions`."""
@@ -218,13 +230,13 @@ TruncatedChainWarning = v2.TruncatedChainWarning
218
230
 
219
231
  __all__ = [
220
232
  "Client", "QuantPadClient", "QuantPadDataError", "QuantPadDataNotReady", "AuthenticationError",
221
- "PermissionDeniedError", "RateLimitError", "QuotaExceededError",
233
+ "PermissionDeniedError", "InAppOnlyError", "RateLimitError", "QuotaExceededError",
222
234
  "NotFoundError", "V2NotAvailableError", "ValidationError", "UpstreamError",
223
235
  "IncompleteResponseError", "ResponseTooLargeError", "TruncatedChainWarning", "TICK_SCHEMAS",
224
236
  "ROLL_ADJUST_MODES", "get_bars", "get_bars_with_retry", "get_ticks",
225
237
  "get_trades", "get_mbp1", "get_mbp10", "get_trades_rth", "get_mbp1_rth",
226
238
  "get_mbp10_rth", "get_spread_1m_rth", "symbology_resolve", "get_universe",
227
- "get_coverage", "get_insider_transactions", "iter_trades", "iter_mbp1", "iter_l1_df_chunks",
239
+ "get_coverage", "get_earnings", "get_fundamentals", "get_insider_transactions", "iter_trades", "iter_mbp1", "iter_l1_df_chunks",
228
240
  "iter_l1_trades_df_chunks", "iter_l1_mbp1_df_chunks", "cache", "lean",
229
241
  "v2", "Historical", "np", "pd", "pa",
230
242
  ]
@@ -6,6 +6,7 @@ import io
6
6
  import os
7
7
  import random
8
8
  import time
9
+ import warnings
9
10
  from datetime import date
10
11
  from typing import Iterator, Sequence
11
12
 
@@ -19,6 +20,7 @@ from .errors import (
19
20
  AuthenticationError,
20
21
  IncompleteResponseError,
21
22
  NotFoundError,
23
+ InAppOnlyError,
22
24
  PermissionDeniedError,
23
25
  QuantPadDataError,
24
26
  QuotaExceededError,
@@ -87,7 +89,7 @@ V2_NOT_AVAILABLE = (
87
89
  "QuantPad support about /v2 access."
88
90
  )
89
91
 
90
- VERSION = "0.9.0"
92
+ VERSION = "0.10.1"
91
93
  USER_AGENT = f"quantpad-data-python/{VERSION}"
92
94
  TICK_SCHEMAS = (
93
95
  "trades", "mbp-1", "mbp-10", "cmbp-1", "tcbbo", "cbbo-1s",
@@ -233,6 +235,94 @@ def _insider_frame(rows: list[dict]) -> pd.DataFrame:
233
235
  return df
234
236
 
235
237
 
238
+ _EARNINGS_TIME_COLS = ("announced_at", "report_accepted_at", "candidate_accepted_at")
239
+ _EARNINGS_NUMERIC_COLS = (
240
+ "revenue", "net_income", "eps_basic", "eps_diluted",
241
+ "fy_revenue", "fy_net_income", "fy_eps_basic", "fy_eps_diluted",
242
+ "revenue_year_ago", "net_income_year_ago", "eps_basic_year_ago", "eps_diluted_year_ago",
243
+ )
244
+
245
+
246
+ def _year_windows(start: str | None, end: str | None) -> list[tuple[str | None, str | None]]:
247
+ """``[start, end)`` cut into windows of at most a year, for a market-wide
248
+ pull; a single open window when there is nothing to cut."""
249
+ if not (start and end):
250
+ return [(start, end)]
251
+ s, e = pd.Timestamp(start), pd.Timestamp(end)
252
+ out = []
253
+ while s < e:
254
+ n = min(s + pd.DateOffset(years=1), e)
255
+ out.append((s.strftime("%Y-%m-%d"), n.strftime("%Y-%m-%d")))
256
+ s = n
257
+ return out
258
+
259
+
260
+ def _fundamentals_long(rows: list[dict]) -> pd.DataFrame:
261
+ df = pd.DataFrame(rows)
262
+ if df.empty:
263
+ return df
264
+ for c in ("period_start", "period_end", "filed_date"):
265
+ if c in df:
266
+ df[c] = pd.to_datetime(df[c], errors="coerce")
267
+ for c in ("accepted_at", "known_at"):
268
+ if c in df:
269
+ df[c] = pd.to_datetime(df[c], utc=True, errors="coerce")
270
+ df["value"] = pd.to_numeric(df["value"], errors="coerce")
271
+ return df
272
+
273
+
274
+ def _fundamentals_wide(long: pd.DataFrame, period: str = "quarter") -> pd.DataFrame:
275
+ """One row per company and period end, one column per field, plus
276
+ ``known_at``: when the last of the row's values became public.
277
+
278
+ A balance-sheet value and a flow for the same period end share a row.
279
+ ``fiscal_quarter`` is left out of an annual frame: there the year's rows
280
+ carry none and the year-end balance sheet carries 4.
281
+ """
282
+ if long.empty:
283
+ return long
284
+ index = [c for c in ("cik", "ticker", "period_end") if c in long]
285
+ values = long.groupby(index + ["field"], dropna=False)["value"].first().unstack("field")
286
+ values.columns.name = None
287
+ grouped = long.groupby(index, dropna=False)
288
+ extra = {"known_at": grouped["known_at"].max(), "fiscal_year": grouped["fiscal_year"].max()}
289
+ if period != "annual":
290
+ extra["fiscal_quarter"] = grouped["fiscal_quarter"].max()
291
+ for name, series in extra.items():
292
+ values[name] = series.reindex(values.index)
293
+ wide = values.reset_index()
294
+ head = index + [c for c in ("fiscal_year", "fiscal_quarter") if c in wide]
295
+ fields = sorted(c for c in wide.columns if c not in head and c != "known_at")
296
+ return wide[head + fields + ["known_at"]].sort_values(["period_end", "cik"]).reset_index(drop=True)
297
+
298
+
299
+ #: Shown when events come back with announcement times but no figures.
300
+ EARNINGS_NO_FIGURES_NOTE = (
301
+ "{n} of {total} earnings events have no figures: their reports were not "
302
+ "machine-readable (SEC filings were tagged from mid-2009 for large companies "
303
+ "and mid-2011 for smaller ones). Announcement times are exact."
304
+ )
305
+
306
+
307
+ def _earnings_frame(rows: list[dict]) -> pd.DataFrame:
308
+ df = pd.DataFrame(rows)
309
+ if df.empty:
310
+ return df
311
+ df["period_end"] = pd.to_datetime(df["period_end"], errors="coerce")
312
+ for c in _EARNINGS_TIME_COLS:
313
+ if c in df:
314
+ df[c] = pd.to_datetime(df[c], utc=True, errors="coerce")
315
+ for c in _EARNINGS_NUMERIC_COLS:
316
+ if c in df:
317
+ df[c] = pd.to_numeric(df[c], errors="coerce")
318
+ figures = [c for c in _EARNINGS_NUMERIC_COLS if c in df and not c.endswith("_year_ago")]
319
+ if figures:
320
+ empty = int(df[figures].isna().all(axis=1).sum())
321
+ if empty:
322
+ warnings.warn(EARNINGS_NO_FIGURES_NOTE.format(n=empty, total=len(df)), stacklevel=3)
323
+ return df
324
+
325
+
236
326
  class Client:
237
327
  def __init__(
238
328
  self,
@@ -328,6 +418,8 @@ class Client:
328
418
  if status == 401:
329
419
  raise AuthenticationError(message, status)
330
420
  if status == 403:
421
+ if isinstance(detail, dict) and detail.get("code") == InAppOnlyError.CODE:
422
+ raise InAppOnlyError(message, status, detail)
331
423
  raise PermissionDeniedError(message, status)
332
424
  if status == 404:
333
425
  raise NotFoundError(message)
@@ -651,3 +743,139 @@ class Client:
651
743
  if len(rows) >= max_rows:
652
744
  break
653
745
  return _insider_frame(rows)
746
+
747
+ def _pages(self, path: str, base: dict, windows, max_rows: int) -> tuple[list[dict], bool]:
748
+ """Every row of every window, up to ``max_rows``. Returns the rows
749
+ and whether the cap stopped the read inside a window (the last rows
750
+ may then be part of a company's period). A capped read warns."""
751
+ rows: list[dict] = []
752
+ for i, (ws, we) in enumerate(windows):
753
+ after = None
754
+ while True:
755
+ params = {**base, "start": ws, "end": we, "after": after,
756
+ "limit": min(20_000, max_rows - len(rows))}
757
+ page = self._request(
758
+ "GET", path, params={k: v for k, v in params.items() if v is not None},
759
+ ).json()
760
+ rows.extend(page.get("rows") or [])
761
+ after = page.get("next_cursor")
762
+ if not after:
763
+ break
764
+ if len(rows) >= max_rows:
765
+ warnings.warn(f"{path}: stopped at max_rows={max_rows}; raise it for the rest",
766
+ stacklevel=3)
767
+ return rows, True
768
+ if len(rows) >= max_rows and i + 1 < len(windows):
769
+ warnings.warn(f"{path}: stopped at max_rows={max_rows}; raise it for the rest",
770
+ stacklevel=3)
771
+ return rows, False
772
+ return rows, False
773
+
774
+ def get_fundamentals(
775
+ self,
776
+ ticker: str | None = None,
777
+ *,
778
+ cik: int | None = None,
779
+ fields: list[str] | str | None = None,
780
+ period: str = "quarter",
781
+ start: str | None = None,
782
+ end: str | None = None,
783
+ as_of: str | None = None,
784
+ version: str = "first",
785
+ wide: bool = True,
786
+ max_rows: int = 2_000_000,
787
+ ) -> pd.DataFrame:
788
+ """Company fundamentals from SEC filings, point in time.
789
+
790
+ 32 standard fields (revenue, net_income, eps_diluted, total_assets,
791
+ operating_cash_flow, ...) for US companies that file 10-Ks and 10-Qs,
792
+ from 2009 on, refreshed nightly.
793
+
794
+ Examples::
795
+
796
+ client.get_fundamentals("AAPL", fields=["revenue", "eps_diluted"], start="2020-01-01")
797
+ client.get_fundamentals("AAPL", period="annual")
798
+ client.get_fundamentals(start="2025-01-01", end="2025-04-01", fields="revenue,net_income")
799
+
800
+ ``period`` is "quarter" (fiscal quarters, with the balance sheet at
801
+ each quarter end) or "annual". ``start`` is inclusive and ``end``
802
+ exclusive, on ``period_end``. A market-wide pull (no ticker or
803
+ cik) needs both and is fetched a year at a time.
804
+
805
+ ``version="first"`` (default) gives each value as first reported;
806
+ "latest" gives the newest restatement. ``as_of`` keeps only values
807
+ public by that moment: ``version="latest", as_of=...`` is what a
808
+ reader had then, which is what a backtest should use.
809
+
810
+ ``wide=True`` (default) returns one row per company and period end
811
+ with a column per field, and ``known_at``: when the last of the
812
+ row's values became public (UTC). ``wide=False`` returns one row
813
+ per value, with its own ``known_at``, filing, SEC tag, and whether
814
+ it was ``derived`` (a fourth quarter as the year less nine months,
815
+ a cash-flow quarter from year-to-date figures). Per-share values
816
+ are never derived: a fourth quarter the company did not file on its
817
+ own has none.
818
+
819
+ ``max_rows`` caps the values read, not wide rows. A capped read
820
+ warns, and the wide frame then leaves out the company-period the cap
821
+ cut short.
822
+ """
823
+ if isinstance(fields, (list, tuple)):
824
+ fields = ",".join(fields)
825
+ windows = [(start, end)]
826
+ if ticker is None and cik is None:
827
+ if not (start and end):
828
+ raise ValueError("a market-wide pull needs start and end")
829
+ windows = _year_windows(start, end)
830
+ base = {"ticker": ticker, "cik": cik, "fields": fields, "period": period,
831
+ "as_of": as_of, "version": version}
832
+ rows, split = self._pages("/v1/fundamentals", base, windows, max_rows)
833
+ if split and wide:
834
+ # rows come in (period_end, cik, field) order: the cap may have cut
835
+ # the last company-period short, and a wide row needs all its fields
836
+ last = (rows[-1].get("period_end"), rows[-1].get("cik"))
837
+ rows = [r for r in rows if (r.get("period_end"), r.get("cik")) != last]
838
+ long = _fundamentals_long(rows)
839
+ return _fundamentals_wide(long, period) if wide else long
840
+
841
+ def get_earnings(
842
+ self,
843
+ ticker: str | None = None,
844
+ *,
845
+ cik: int | None = None,
846
+ start: str | None = None,
847
+ end: str | None = None,
848
+ date_field: str = "announced",
849
+ include_candidates: bool = False,
850
+ max_rows: int = 1_000_000,
851
+ ) -> pd.DataFrame:
852
+ """Earnings events from SEC filings: one row per period a company
853
+ reported, oldest first.
854
+
855
+ ``announced_at`` is when the results went public (UTC, to the
856
+ second): the acceptance time of the 8-K that released them, or of the
857
+ 10-Q/10-K itself when there was none (``announcement_source``).
858
+ ``session`` is "pre", "regular" or "post" by New York clock time.
859
+ The figures (``revenue``, ``eps_diluted``, ...) are the report's own,
860
+ as public when it was accepted, with the same quarter a year earlier;
861
+ most reports from before 2011 were not machine-readable and have
862
+ times but no figures (the call warns). Upcoming dates and analyst
863
+ estimates are not included.
864
+
865
+ Examples::
866
+
867
+ client.get_earnings("AAPL")
868
+ client.get_earnings(start="2026-10-26", end="2026-11-07") # a market-wide window
869
+
870
+ ``start``/``end`` bound ``date_field``: "announced" (New York dates)
871
+ or "period" (the period end). A market-wide pull needs both and is
872
+ fetched a year at a time.
873
+ """
874
+ windows = [(start, end)]
875
+ if ticker is None and cik is None:
876
+ if not (start and end):
877
+ raise ValueError("a market-wide pull needs start and end")
878
+ windows = _year_windows(start, end)
879
+ base = {"ticker": ticker, "cik": cik, "date_field": date_field,
880
+ "include_candidates": str(bool(include_candidates)).lower()}
881
+ return _earnings_frame(self._pages("/v1/earnings", base, windows, max_rows)[0])
@@ -42,6 +42,20 @@ class PermissionDeniedError(QuantPadDataError):
42
42
  pass
43
43
 
44
44
 
45
+ class InAppOnlyError(PermissionDeniedError):
46
+ """The data asked for is available inside QuantPad only.
47
+
48
+ CME futures data (``GLBX.MDP3``) is licensed for use inside the
49
+ QuantPad app, so the API refuses it to API keys with a 403 whose body
50
+ carries ``code: "cme_in_app_only"``. The message says where to work
51
+ with it instead. A subclass of :class:`PermissionDeniedError`, so an
52
+ existing ``except PermissionDeniedError`` still catches it.
53
+ """
54
+
55
+ #: The refusal code the service sends for this case.
56
+ CODE = "cme_in_app_only"
57
+
58
+
45
59
  class RateLimitError(QuantPadDataError):
46
60
  def __init__(
47
61
  self,
@@ -3,8 +3,8 @@
3
3
  The v1 helpers take QuantPad's own arguments and infer the rest: which
4
4
  dataset a symbol lives in, what kind of symbol it is, how far back to
5
5
  look. That inference is convenient right up until it is wrong, and when
6
- it is wrong it fails quietly — a specific futures contract returns an
7
- empty frame that looks exactly like a coverage gap.
6
+ it is wrong it fails quietly: a symbol looked up on the wrong venue
7
+ returns an empty frame that looks exactly like a coverage gap.
8
8
 
9
9
  This module removes the inference. Every call names its dataset and its
10
10
  symbology type, and every response reports the address it actually used:
@@ -12,10 +12,13 @@ symbology type, and every response reports the address it actually used:
12
12
  import quantpad_data as qpd
13
13
  client = qpd.v2.Historical()
14
14
  df = client.timeseries.get_range(
15
- dataset="GLBX.MDP3", symbols="ESZ6", schema="ohlcv-1m",
15
+ dataset="XNAS.ITCH", symbols="AAPL", schema="ohlcv-1m",
16
16
  start="2026-01-05", end="2026-01-06",
17
17
  )
18
18
 
19
+ CME futures (``GLBX.MDP3``) are served inside QuantPad only: with an API
20
+ key they raise :class:`~quantpad_data.errors.InAppOnlyError`.
21
+
19
22
  A DataFrame comes back directly, and there is no cost or billing surface,
20
23
  because data is included in the QuantPad plan rather than metered per
21
24
  request.
@@ -30,6 +33,7 @@ import json
30
33
  import os
31
34
  import tempfile
32
35
  import threading
36
+ import time
33
37
  import warnings
34
38
  from datetime import date, timedelta
35
39
  from typing import Any, Iterator, Sequence
@@ -1124,15 +1128,74 @@ class Batch(_Namespace):
1124
1128
  "GET", f"/v2/batch/{job_id}/files"
1125
1129
  ).json()["files"]
1126
1130
 
1127
- def hydrate(self, job_id: str) -> dict:
1131
+ def hydrate(
1132
+ self,
1133
+ job_id: str,
1134
+ *,
1135
+ wait: bool = True,
1136
+ poll_seconds: float = 15.0,
1137
+ timeout: float | None = None,
1138
+ ) -> dict:
1128
1139
  """Pull a finished extract into the cache.
1129
1140
 
1130
1141
  After this, the same days are served by ``get_range`` from
1131
1142
  storage — the job is a one-time cost, not a per-read one.
1143
+
1144
+ The service hydrates in the background and this returns its
1145
+ progress record. With ``wait`` (the default) it polls every
1146
+ ``poll_seconds`` until the hydrate is ``done`` and returns the
1147
+ final record (``written``, ``empty``, ``skipped``); a hydrate
1148
+ that ``failed`` or was ``interrupted`` raises. ``timeout``
1149
+ bounds the wait in seconds (default: none). With ``wait=False``
1150
+ it returns at once; poll :meth:`hydrate_status` yourself.
1151
+ Calling it again while one is running is harmless and reports
1152
+ that one.
1132
1153
  """
1133
- return self._client._request(
1154
+ # The full data timeout, as before 0.10.1, not the short one the
1155
+ # polls use: a service from before background hydrate still runs
1156
+ # the hydrate inside this request. A current one answers at once.
1157
+ status = self._client._request(
1134
1158
  "POST", f"/v2/batch/{job_id}/hydrate", timeout=V2_DATA_TIMEOUT,
1135
1159
  ).json()
1160
+ if not wait or "state" not in status:
1161
+ # A service from before background hydrate answers with the
1162
+ # finished report and no ``state``.
1163
+ return status
1164
+ deadline = None if timeout is None else time.monotonic() + float(timeout)
1165
+ while True:
1166
+ state = status.get("state")
1167
+ if state == "done":
1168
+ return status
1169
+ if state in ("failed", "interrupted"):
1170
+ raise QuantPadDataError(
1171
+ f"hydrate of {job_id} {state}: "
1172
+ f"{status.get('error') or 'call hydrate() again to resume'}",
1173
+ None,
1174
+ status,
1175
+ )
1176
+ if deadline is not None and time.monotonic() >= deadline:
1177
+ raise TimeoutError(
1178
+ f"hydrate of {job_id} still {state} after {timeout}s "
1179
+ f"({status.get('files_done')}/{status.get('files_total')} "
1180
+ "files); it keeps running on the service -- poll "
1181
+ "hydrate_status()"
1182
+ )
1183
+ time.sleep(max(1.0, float(poll_seconds)))
1184
+ status = self.hydrate_status(job_id)
1185
+
1186
+ def hydrate_status(self, job_id: str) -> dict:
1187
+ """Where this job's hydrate stands: ``state`` is
1188
+ ``waiting_for_job``, ``running``, ``done``, ``failed`` or
1189
+ ``interrupted``, with ``files_done`` / ``files_total`` and the
1190
+ counts so far."""
1191
+ return self._client._request(
1192
+ "GET", f"/v2/batch/{job_id}/hydrate", timeout=_HYDRATE_STATUS_TIMEOUT,
1193
+ ).json()
1194
+
1195
+
1196
+ #: (connect, read) for a hydrate status poll, which the service answers at
1197
+ #: once. Short so one stalled poll cannot outlast the caller's ``timeout``.
1198
+ _HYDRATE_STATUS_TIMEOUT = (10, 120)
1136
1199
 
1137
1200
 
1138
1201
  class Historical:
@@ -392,3 +392,158 @@ def test_module_level_insider_alias(monkeypatch):
392
392
 
393
393
  def test_insider_helper_is_public():
394
394
  assert "get_insider_transactions" in quantpad_data.__all__
395
+
396
+
397
+ def _fact(cik, ticker, field, end, value, known, kind="Q", fq=1, fy=2026):
398
+ return {"cik": cik, "ticker": ticker, "field": field, "period_kind": kind, "period_start": None,
399
+ "period_end": end, "fiscal_year": fy, "fiscal_quarter": fq, "value": value, "unit": "USD",
400
+ "version": 1, "derived": False, "source_tag": "T", "accession": "a", "form": "10-Q",
401
+ "filed_date": known[:10], "accepted_at": known, "known_at": known}
402
+
403
+
404
+ def test_get_fundamentals_pages_and_pivots_to_a_column_per_field():
405
+ import json
406
+
407
+ page1 = {"rows": [_fact(320193, "AAPL", "revenue", "2025-12-27", 143756000000, "2026-01-30T11:01:32+00:00"),
408
+ _fact(320193, "AAPL", "total_assets", "2025-12-27", "379297000000", "2026-01-30T11:01:32+00:00",
409
+ kind="I")],
410
+ "next_cursor": "2025-12-27|320193|total_assets"}
411
+ page2 = {"rows": [_fact(320193, "AAPL", "eps_diluted", "2026-03-28", 2.01, "2026-05-01T10:01:00+00:00", fq=2),
412
+ _fact(320193, "AAPL", "revenue", "2026-03-28", 111184000000, "2026-05-01T10:01:00+00:00", fq=2)],
413
+ "next_cursor": None}
414
+ session = FakeSession([response(body=json.dumps(page1).encode()), response(body=json.dumps(page2).encode())])
415
+ client = Client(api_key="secret", session=session)
416
+
417
+ df = client.get_fundamentals("aapl", fields=["revenue", "eps_diluted", "total_assets"], start="2025-10-01")
418
+
419
+ assert list(df["period_end"].dt.strftime("%Y-%m-%d")) == ["2025-12-27", "2026-03-28"]
420
+ assert df.loc[0, "revenue"] == 143756000000 and df.loc[0, "total_assets"] == 379297000000
421
+ assert pd.isna(df.loc[0, "eps_diluted"]) and df.loc[1, "eps_diluted"] == 2.01
422
+ assert str(df["known_at"].dt.tz) == "UTC" and df.loc[1, "known_at"] == pd.Timestamp("2026-05-01T10:01:00Z")
423
+ assert list(df.columns) == ["cik", "ticker", "period_end", "fiscal_year", "fiscal_quarter",
424
+ "eps_diluted", "revenue", "total_assets", "known_at"]
425
+ method, url, kwargs = session.calls[0]
426
+ assert method == "GET" and url.endswith("/v1/fundamentals")
427
+ params = kwargs["params"]
428
+ assert params["ticker"] == "aapl" and params["fields"] == "revenue,eps_diluted,total_assets"
429
+ assert params["period"] == "quarter" and params["version"] == "first" and params["start"] == "2025-10-01"
430
+ assert "end" not in params and "after" not in params and "as_of" not in params
431
+ assert session.calls[1][2]["params"]["after"] == "2025-12-27|320193|total_assets"
432
+
433
+
434
+ def test_an_annual_frame_keeps_the_year_and_its_balance_sheet_on_one_row():
435
+ import json
436
+
437
+ rows = [_fact(320193, "AAPL", "revenue", "2025-09-27", 416161000000, "2025-10-31T10:01:26+00:00", kind="FY", fq=None, fy=2025),
438
+ _fact(320193, "AAPL", "total_assets", "2025-09-27", 359241000000, "2025-10-31T10:01:26+00:00", kind="I", fq=4, fy=2025),
439
+ _fact(None, None, "revenue", "2025-09-27", 5, "2025-12-01T00:00:00+00:00", kind="FY", fq=None, fy=2025)]
440
+ rows[2]["cik"] = 999
441
+ session = FakeSession([response(body=json.dumps({"rows": rows, "next_cursor": None}).encode())])
442
+ df = Client(api_key="secret", session=session).get_fundamentals(start="2025-01-01", end="2026-01-01", period="annual")
443
+ assert len(df) == 2 and "fiscal_quarter" not in df
444
+ apple = df[df["cik"] == 320193].iloc[0]
445
+ assert apple["revenue"] == 416161000000 and apple["total_assets"] == 359241000000 and apple["fiscal_year"] == 2025
446
+ other = df[df["cik"] == 999].iloc[0]
447
+ assert pd.isna(other["ticker"]) and other["revenue"] == 5
448
+
449
+
450
+ def test_get_fundamentals_long_keeps_one_row_per_value():
451
+ import json
452
+
453
+ rows = [_fact(320193, "AAPL", "revenue", "2025-12-27", 1, "2026-01-30T11:01:32+00:00")]
454
+ session = FakeSession([response(body=json.dumps({"rows": rows, "next_cursor": None}).encode())])
455
+ df = Client(api_key="secret", session=session).get_fundamentals(
456
+ cik=320193, version="latest", as_of="2026-02-01T00:00:00Z", wide=False)
457
+ assert list(df.columns)[:3] == ["cik", "ticker", "field"] and len(df) == 1
458
+ params = session.calls[0][2]["params"]
459
+ assert params["cik"] == 320193 and params["version"] == "latest" and params["as_of"] == "2026-02-01T00:00:00Z"
460
+
461
+
462
+ def test_get_fundamentals_market_wide_needs_a_window_and_splits_by_year():
463
+ import json
464
+
465
+ with pytest.raises(ValueError):
466
+ Client(api_key="secret", session=FakeSession([])).get_fundamentals(fields="revenue")
467
+ empty = json.dumps({"rows": [], "next_cursor": None}).encode()
468
+ session = FakeSession([response(body=empty), response(body=empty)])
469
+ df = Client(api_key="secret", session=session).get_fundamentals(start="2024-01-01", end="2025-06-01")
470
+ assert df.empty
471
+ assert [(c[2]["params"]["start"], c[2]["params"]["end"]) for c in session.calls] == [
472
+ ("2024-01-01", "2025-01-01"), ("2025-01-01", "2025-06-01")]
473
+
474
+
475
+ def test_a_capped_wide_read_leaves_out_the_period_it_cut_short():
476
+ import json
477
+
478
+ rows = [_fact(1, "A", "revenue", "2025-06-28", 1, "2025-08-01T10:00:00+00:00"),
479
+ _fact(1, "A", "total_assets", "2025-06-28", 2, "2025-08-01T10:00:00+00:00", kind="I"),
480
+ _fact(1, "A", "revenue", "2025-09-27", 3, "2025-10-31T10:00:00+00:00")]
481
+ page = json.dumps({"rows": rows, "next_cursor": "2025-09-27|1|revenue"}).encode()
482
+ session = FakeSession([response(body=page)])
483
+ with pytest.warns(UserWarning, match="max_rows=3"):
484
+ df = Client(api_key="secret", session=session).get_fundamentals(cik=1, max_rows=3)
485
+ assert len(session.calls) == 1 and session.calls[0][2]["params"]["limit"] == 3
486
+ assert list(df["period_end"].dt.strftime("%Y-%m-%d")) == ["2025-06-28"] and df.loc[0, "total_assets"] == 2
487
+
488
+ session = FakeSession([response(body=page)])
489
+ with pytest.warns(UserWarning):
490
+ long = Client(api_key="secret", session=session).get_fundamentals(cik=1, max_rows=3, wide=False)
491
+ assert len(long) == 3
492
+
493
+
494
+ def test_an_exact_fit_does_not_warn(recwarn):
495
+ import json
496
+
497
+ rows = [_fact(1, "A", "revenue", "2025-06-28", 1, "2025-08-01T10:00:00+00:00")]
498
+ session = FakeSession([response(body=json.dumps({"rows": rows, "next_cursor": None}).encode())])
499
+ assert len(Client(api_key="secret", session=session).get_fundamentals(cik=1, max_rows=1)) == 1
500
+ assert not [w for w in recwarn if "max_rows" in str(w.message)]
501
+
502
+
503
+ def test_get_earnings_parses_times_and_figures():
504
+ import json
505
+
506
+ row = {"cik": 320193, "ticker": "AAPL", "period_end": "2026-09-26", "fiscal_year": 2026, "fiscal_quarter": 4,
507
+ "announced_at": "2026-11-02T21:30:23+00:00", "report_accepted_at": "2026-11-03T13:05:15+00:00",
508
+ "session": "post", "announcement_source": "8-K 2.02", "revenue": 114477000000, "eps_diluted": None,
509
+ "fy_eps_diluted": "8.98", "eps_diluted_year_ago": None}
510
+ session = FakeSession([response(body=json.dumps({"rows": [row], "next_cursor": None}).encode())])
511
+ df = Client(api_key="secret", session=session).get_earnings("AAPL", include_candidates=True)
512
+ assert df.loc[0, "announced_at"] == pd.Timestamp("2026-11-02T21:30:23Z")
513
+ assert df.loc[0, "fy_eps_diluted"] == 8.98 and pd.isna(df.loc[0, "eps_diluted"])
514
+ method, url, kwargs = session.calls[0]
515
+ assert url.endswith("/v1/earnings")
516
+ assert kwargs["params"]["include_candidates"] == "true" and kwargs["params"]["date_field"] == "announced"
517
+ with pytest.raises(ValueError):
518
+ Client(api_key="secret", session=FakeSession([])).get_earnings()
519
+
520
+
521
+ def test_events_without_figures_say_why():
522
+ import json
523
+
524
+ rows = [{"cik": 1, "period_end": "2006-03-31", "announced_at": "2006-04-20T20:05:00+00:00",
525
+ "revenue": None, "eps_diluted": None, "revenue_year_ago": None},
526
+ {"cik": 1, "period_end": "2012-03-31", "announced_at": "2012-04-20T20:05:00+00:00",
527
+ "revenue": "100", "eps_diluted": "0.5", "revenue_year_ago": None}]
528
+ session = FakeSession([response(body=json.dumps({"rows": rows, "next_cursor": None}).encode())])
529
+ with pytest.warns(UserWarning, match="1 of 2 earnings events have no figures"):
530
+ Client(api_key="secret", session=session).get_earnings(cik=1)
531
+
532
+
533
+ def test_fundamentals_helpers_are_public(monkeypatch):
534
+ captured = {}
535
+
536
+ class Stub:
537
+ def get_fundamentals(self, ticker, **kwargs):
538
+ captured["f"] = (ticker, kwargs)
539
+ return "f"
540
+
541
+ def get_earnings(self, ticker, **kwargs):
542
+ captured["e"] = (ticker, kwargs)
543
+ return "e"
544
+
545
+ monkeypatch.setattr(quantpad_data, "_client", lambda **kwargs: Stub())
546
+ assert quantpad_data.get_fundamentals("AAPL", period="annual") == "f"
547
+ assert quantpad_data.get_earnings("AAPL") == "e"
548
+ assert captured == {"f": ("AAPL", {"period": "annual"}), "e": ("AAPL", {})}
549
+ assert {"get_fundamentals", "get_earnings"} <= set(quantpad_data.__all__)
@@ -0,0 +1,62 @@
1
+ """CME data refused to an API key raises InAppOnlyError with the full text."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+
7
+ import pytest
8
+ import requests
9
+
10
+ import quantpad_data
11
+ from quantpad_data.client import Client
12
+ from quantpad_data.errors import InAppOnlyError, PermissionDeniedError
13
+
14
+ BODY = {
15
+ "code": "cme_in_app_only",
16
+ "message": (
17
+ "CME futures data (GLBX.MDP3) is available inside QuantPad only, so it "
18
+ "can’t be downloaded through the API, Python SDK or MCP."
19
+ ),
20
+ "hint": "To work with it, create a new project at https://quantpad.ai.",
21
+ "dataset": "GLBX.MDP3",
22
+ }
23
+
24
+
25
+ def _response(body: dict, status: int = 403) -> requests.Response:
26
+ response = requests.Response()
27
+ response.status_code = status
28
+ response.url = "https://example.test/v1/bars"
29
+ response._content = json.dumps({"error": body}).encode()
30
+ response.headers["Content-Type"] = "application/json"
31
+ return response
32
+
33
+
34
+ def _raise(body, path="/v1/bars"):
35
+ Client(api_key="k", base_url="https://example.test")._raise_for_status(
36
+ _response(body), path
37
+ )
38
+
39
+
40
+ @pytest.mark.parametrize("path", ["/v1/bars", "/v2/timeseries/get_range"])
41
+ def test_the_cme_refusal_is_its_own_error_with_message_and_hint(path):
42
+ with pytest.raises(InAppOnlyError) as caught:
43
+ _raise(BODY, path)
44
+ assert str(caught.value) == f"{BODY['message']} {BODY['hint']}"
45
+ assert caught.value.status_code == 403
46
+ assert caught.value.detail["dataset"] == "GLBX.MDP3"
47
+
48
+
49
+ def test_existing_permission_handlers_still_catch_it():
50
+ with pytest.raises(PermissionDeniedError):
51
+ _raise(BODY)
52
+
53
+
54
+ def test_other_403s_are_unchanged():
55
+ with pytest.raises(PermissionDeniedError) as caught:
56
+ _raise({"message": "API key is inactive"})
57
+ assert not isinstance(caught.value, InAppOnlyError)
58
+
59
+
60
+ def test_it_is_exported():
61
+ assert quantpad_data.InAppOnlyError is InAppOnlyError
62
+ assert "InAppOnlyError" in quantpad_data.__all__
@@ -2615,3 +2615,54 @@ class TestExpiredUrlsAreResigned:
2615
2615
  assert "sig=hydrated" in frames[2]["url"][0]
2616
2616
  single = session.calls[3][2]["json"]
2617
2617
  assert (single["start"], single["hydrate"]) == ("2026-01-07", True)
2618
+
2619
+
2620
+ class TestBatchHydrate:
2621
+ """2026-11-20: hydrate ran inside one request, and a two-hour options
2622
+ hydrate timed out at thirty minutes while the service carried on."""
2623
+
2624
+ def _no_sleep(self, monkeypatch):
2625
+ import quantpad_data.v2 as v2
2626
+
2627
+ monkeypatch.setattr(v2.time, "sleep", lambda _s: None)
2628
+
2629
+ def test_it_polls_until_the_hydrate_is_done(self, monkeypatch):
2630
+ self._no_sleep(monkeypatch)
2631
+ api, session = client_with([
2632
+ json_response({"job_id": "j", "state": "running"}, status=202),
2633
+ json_response({"job_id": "j", "state": "running", "files_done": 1}),
2634
+ json_response({"job_id": "j", "state": "done", "written": 3}),
2635
+ ])
2636
+ result = api.batch.hydrate("j")
2637
+ assert result["written"] == 3
2638
+ assert [(m, u.rsplit("/v2", 1)[1]) for m, u, _ in session.calls] == [
2639
+ ("POST", "/batch/j/hydrate"),
2640
+ ("GET", "/batch/j/hydrate"),
2641
+ ("GET", "/batch/j/hydrate"),
2642
+ ]
2643
+ # An older service hydrates inside the POST, so it keeps the full
2644
+ # budget; the polls are short.
2645
+ from quantpad_data.client import V2_DATA_TIMEOUT
2646
+
2647
+ assert session.calls[0][2]["timeout"] == V2_DATA_TIMEOUT
2648
+ assert [c[2]["timeout"] for c in session.calls[1:]] == [(10, 120)] * 2
2649
+
2650
+ def test_without_wait_it_returns_the_first_record(self):
2651
+ api, session = client_with([
2652
+ json_response({"job_id": "j", "state": "running"}, status=202),
2653
+ ])
2654
+ assert api.batch.hydrate("j", wait=False)["state"] == "running"
2655
+ assert len(session.calls) == 1
2656
+
2657
+ def test_a_failed_hydrate_raises_with_its_reason(self, monkeypatch):
2658
+ self._no_sleep(monkeypatch)
2659
+ api, _ = client_with([
2660
+ json_response({"job_id": "j", "state": "running"}, status=202),
2661
+ json_response({"job_id": "j", "state": "failed", "error": "boom"}),
2662
+ ])
2663
+ with pytest.raises(QuantPadDataError, match="boom"):
2664
+ api.batch.hydrate("j")
2665
+
2666
+ def test_an_older_service_s_finished_report_is_returned_as_it_is(self):
2667
+ api, _ = client_with([json_response({"job_id": "j", "written": 2})])
2668
+ assert api.batch.hydrate("j") == {"job_id": "j", "written": 2}
File without changes