quantpad-data 0.9.0__tar.gz → 0.10.0__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.0}/PKG-INFO +30 -14
  2. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/README.md +29 -13
  3. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/pyproject.toml +1 -1
  4. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/quantpad_data/__init__.py +2 -1
  5. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/quantpad_data/client.py +4 -1
  6. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/quantpad_data/errors.py +14 -0
  7. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/quantpad_data/v2.py +6 -3
  8. quantpad_data-0.10.0/tests/test_in_app_only.py +62 -0
  9. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/.gitignore +0 -0
  10. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/quantpad_data/cache.py +0 -0
  11. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/quantpad_data/lean.py +0 -0
  12. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/quantpad_data/memory.py +0 -0
  13. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/quantpad_data/py.typed +0 -0
  14. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/quantpad_data/rth.py +0 -0
  15. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/tests/conftest.py +0 -0
  16. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/tests/test_client.py +0 -0
  17. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/tests/test_lean.py +0 -0
  18. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/tests/test_message_encoding.py +0 -0
  19. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/tests/test_packaging.py +0 -0
  20. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/tests/test_refusal_hint.py +0 -0
  21. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/tests/test_rth.py +0 -0
  22. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/tests/test_v2.py +0 -0
  23. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/tests/test_v2_cache.py +0 -0
  24. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/tests/test_v2_gate.py +0 -0
  25. {quantpad_data-0.9.0 → quantpad_data-0.10.0}/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.0
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,13 +80,29 @@ 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
108
  symbology, and SEC insider transactions. It does not proxy FRED or SEC EDGAR.
@@ -134,7 +150,7 @@ current, counted once, and sanely priced. For a backtest, use `accepted_at`
134
150
 
135
151
  The helpers above infer which dataset a symbol lives in and what kind of
136
152
  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
153
+ fails quietly: a symbol looked up on the wrong venue returns an empty frame
138
154
  that looks exactly like a coverage gap.
139
155
 
140
156
  `qpd.v2.Historical` removes the inference. Every call names its dataset and
@@ -146,18 +162,18 @@ import quantpad_data as qpd
146
162
  client = qpd.v2.Historical()
147
163
 
148
164
  bars = client.timeseries.get_range(
149
- dataset="GLBX.MDP3", # required — never guessed
150
- symbols="ESZ6", # a specific contract month
165
+ dataset="XNAS.ITCH", # required, never guessed
166
+ symbols="AAPL",
151
167
  stype_in="raw_symbol", # raw_symbol | instrument_id | parent | continuous
152
168
  schema="ohlcv-1m",
153
169
  start="2026-01-05",
154
170
  end="2026-01-06",
155
171
  )
156
172
 
157
- # What actually answered, so you can confirm it was the contract you meant.
173
+ # What actually answered, so you can confirm it was the instrument you meant.
158
174
  print(bars.attrs["quantpad"])
159
- # {'dataset': 'GLBX.MDP3', 'stype_in': 'raw_symbol',
160
- # 'resolved': 'ESZ6=651968', 'clamped': False, ...}
175
+ # {'dataset': 'XNAS.ITCH', 'stype_in': 'raw_symbol',
176
+ # 'resolved': 'AAPL=<instrument_id>', 'clamped': False, ...}
161
177
  ```
162
178
 
163
179
  Every response reports the address it used, and a window that had to be
@@ -185,7 +201,7 @@ delivery path with `mode="interactive"` or `mode="bulk"`, or stream day by day:
185
201
 
186
202
  ```python
187
203
  for day in client.timeseries.iter_range(
188
- dataset="GLBX.MDP3", symbols="ESZ6", schema="mbp-10",
204
+ dataset="XNAS.ITCH", symbols="AAPL", schema="trades",
189
205
  start="2026-01-05", end="2026-02-05",
190
206
  ):
191
207
  process(day)
@@ -201,7 +217,7 @@ the cache so ordinary `get_range` calls serve it from storage:
201
217
 
202
218
  ```python
203
219
  job = client.batch.submit(
204
- dataset="GLBX.MDP3", symbols="ESZ6", schema="mbp-10",
220
+ dataset="XNAS.ITCH", symbols="AAPL", schema="trades",
205
221
  start="2026-01-05", end="2026-02-05", hydrate=True,
206
222
  )
207
223
  client.batch.hydrate(job["job_id"])
@@ -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,13 +58,29 @@ 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
86
  symbology, and SEC insider transactions. It does not proxy FRED or SEC EDGAR.
@@ -112,7 +128,7 @@ current, counted once, and sanely priced. For a backtest, use `accepted_at`
112
128
 
113
129
  The helpers above infer which dataset a symbol lives in and what kind of
114
130
  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
131
+ fails quietly: a symbol looked up on the wrong venue returns an empty frame
116
132
  that looks exactly like a coverage gap.
117
133
 
118
134
  `qpd.v2.Historical` removes the inference. Every call names its dataset and
@@ -124,18 +140,18 @@ import quantpad_data as qpd
124
140
  client = qpd.v2.Historical()
125
141
 
126
142
  bars = client.timeseries.get_range(
127
- dataset="GLBX.MDP3", # required — never guessed
128
- symbols="ESZ6", # a specific contract month
143
+ dataset="XNAS.ITCH", # required, never guessed
144
+ symbols="AAPL",
129
145
  stype_in="raw_symbol", # raw_symbol | instrument_id | parent | continuous
130
146
  schema="ohlcv-1m",
131
147
  start="2026-01-05",
132
148
  end="2026-01-06",
133
149
  )
134
150
 
135
- # What actually answered, so you can confirm it was the contract you meant.
151
+ # What actually answered, so you can confirm it was the instrument you meant.
136
152
  print(bars.attrs["quantpad"])
137
- # {'dataset': 'GLBX.MDP3', 'stype_in': 'raw_symbol',
138
- # 'resolved': 'ESZ6=651968', 'clamped': False, ...}
153
+ # {'dataset': 'XNAS.ITCH', 'stype_in': 'raw_symbol',
154
+ # 'resolved': 'AAPL=<instrument_id>', 'clamped': False, ...}
139
155
  ```
140
156
 
141
157
  Every response reports the address it used, and a window that had to be
@@ -163,7 +179,7 @@ delivery path with `mode="interactive"` or `mode="bulk"`, or stream day by day:
163
179
 
164
180
  ```python
165
181
  for day in client.timeseries.iter_range(
166
- dataset="GLBX.MDP3", symbols="ESZ6", schema="mbp-10",
182
+ dataset="XNAS.ITCH", symbols="AAPL", schema="trades",
167
183
  start="2026-01-05", end="2026-02-05",
168
184
  ):
169
185
  process(day)
@@ -179,7 +195,7 @@ the cache so ordinary `get_range` calls serve it from storage:
179
195
 
180
196
  ```python
181
197
  job = client.batch.submit(
182
- dataset="GLBX.MDP3", symbols="ESZ6", schema="mbp-10",
198
+ dataset="XNAS.ITCH", symbols="AAPL", schema="trades",
183
199
  start="2026-01-05", end="2026-02-05", hydrate=True,
184
200
  )
185
201
  client.batch.hydrate(job["job_id"])
@@ -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.0"
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,
@@ -218,7 +219,7 @@ TruncatedChainWarning = v2.TruncatedChainWarning
218
219
 
219
220
  __all__ = [
220
221
  "Client", "QuantPadClient", "QuantPadDataError", "QuantPadDataNotReady", "AuthenticationError",
221
- "PermissionDeniedError", "RateLimitError", "QuotaExceededError",
222
+ "PermissionDeniedError", "InAppOnlyError", "RateLimitError", "QuotaExceededError",
222
223
  "NotFoundError", "V2NotAvailableError", "ValidationError", "UpstreamError",
223
224
  "IncompleteResponseError", "ResponseTooLargeError", "TruncatedChainWarning", "TICK_SCHEMAS",
224
225
  "ROLL_ADJUST_MODES", "get_bars", "get_bars_with_retry", "get_ticks",
@@ -19,6 +19,7 @@ from .errors import (
19
19
  AuthenticationError,
20
20
  IncompleteResponseError,
21
21
  NotFoundError,
22
+ InAppOnlyError,
22
23
  PermissionDeniedError,
23
24
  QuantPadDataError,
24
25
  QuotaExceededError,
@@ -87,7 +88,7 @@ V2_NOT_AVAILABLE = (
87
88
  "QuantPad support about /v2 access."
88
89
  )
89
90
 
90
- VERSION = "0.9.0"
91
+ VERSION = "0.10.0"
91
92
  USER_AGENT = f"quantpad-data-python/{VERSION}"
92
93
  TICK_SCHEMAS = (
93
94
  "trades", "mbp-1", "mbp-10", "cmbp-1", "tcbbo", "cbbo-1s",
@@ -328,6 +329,8 @@ class Client:
328
329
  if status == 401:
329
330
  raise AuthenticationError(message, status)
330
331
  if status == 403:
332
+ if isinstance(detail, dict) and detail.get("code") == InAppOnlyError.CODE:
333
+ raise InAppOnlyError(message, status, detail)
331
334
  raise PermissionDeniedError(message, status)
332
335
  if status == 404:
333
336
  raise NotFoundError(message)
@@ -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.
@@ -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__
File without changes