quantpad-data 0.4.2__tar.gz → 0.5.1__tar.gz

quantpad_data-0.5.1/.gitignore

@@ -0,0 +1,34 @@
+__pycache__/
+*.py[cod]
+*$py.class
+.env
+.env.local
+.venv/
+venv/
+# Any suffixed venv too. .venv141 (fastapi 0.141, the version the image builds --
+# see pinfastapi) was NOT matched by the pattern above and a `git add -A` swallowed
+# all ~4,000 files of it into a commit.
+.venv*/
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# Throwaway investigation probes. Named so they sort together and are
+# obviously not part of the service; there are usually a lot of them
+# mid-investigation and none of them should ever be committed.
+_qp_*
+
+# Scratch: commit-message and one-off investigation files.
+_*.txt
+_*.md
+_*.py
+
+# A DUNDER FILE IS NOT A SCRATCH FILE. `_*.py` matches `__init__.py`, and while
+# git keeps an already-tracked file regardless, HATCHLING APPLIES THESE PATTERNS
+# WHEN SELECTING WHAT GOES IN THE WHEEL -- so from 2026-09-14 every published
+# quantpad-data release shipped without its `__init__.py`, i.e. without Client,
+# Historical, get_bars and every other documented name. `pip install
+# quantpad-data` gave a namespace package that answered AttributeError to the
+# README's first example. Verified against the artifact on PyPI, not inferred.
+!__*.py

{quantpad_data-0.4.2 → quantpad_data-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quantpad-data
-Version: 0.4.2
+Version: 0.5.1
 Summary: Official Python client for the QuantPad market-data API
 Project-URL: Documentation, https://api.quantpad.ai/external/docs
 Author: QuantPad
@@ -16,6 +16,7 @@ Provides-Extra: rth
 Requires-Dist: exchange-calendars>=4.5; extra == 'rth'
 Provides-Extra: test
 Requires-Dist: build>=1.2; extra == 'test'
+Requires-Dist: exchange-calendars>=4.5; extra == 'test'
 Requires-Dist: pytest>=8; extra == 'test'
 Description-Content-Type: text/markdown
 
@@ -75,8 +76,7 @@ client honors `Retry-After` and uses exponential backoff for transient failures.
 QuantPad notebooks remain compatible through `QUANTPAD_NOTEBOOK_DATA_TOKEN`.
 
 Bars preserve the notebook helper's OHLCV aliases and smart futures
-back-adjustment default. Tick timestamps are epoch nanoseconds. Install
-`quantpad-data[rth]` for XNYS regular-session helpers.
+back-adjustment default. Tick timestamps are epoch nanoseconds.
 
 `mbp-10` is true L2 depth with bid/ask price, size, and order-count fields at
 levels 0-9. It is available for supported CME futures, individual CME
@@ -172,6 +172,66 @@ job = client.batch.submit(
 client.batch.hydrate(job["job_id"])
 ```
 
+### Regular trading hours
+
+`get_range` returns the whole published session, which for US equities includes
+pre- and post-market. That is what the upstream feed publishes, and it is more
+data than QuantPad's older `/v1` tick endpoints returned: those enumerated
+exchange sessions, and the XNYS calendar's open and close *are* regular hours,
+so `/v1` excluded the extended session without saying so — around 7% of the
+rows on a liquid name.
+
+If you want that narrower scope, ask for it:
+
+```python
+df = client.timeseries.get_range_rth(
+    dataset="XNAS.ITCH", symbols="BA", schema="trades",
+    start="2026-09-16", end="2026-09-17",
+)
+```
+
+`iter_range_rth` is the streaming form. Both follow the exchange calendar, so
+half-days close early and holidays are skipped, and both filter on `ts_event`
+— the clock `/v1` presented as its `t` column — so the numbers are comparable
+with a `/v1` result. Requires the calendar extra: `pip install
+'quantpad-data[rth]'`.
+
+The window sent to the service is still the whole range; the narrowing happens
+here. So the size budget applies to the full session either way, and a window
+too large unfiltered is too large for `get_range_rth` too — use
+`iter_range_rth` for those.
+
+### The disk cache
+
+Settled `/v2` answers are cached on disk, so asking twice costs the network
+once. Measured against production on a day of `BA` `mbp-10` (237,916 rows):
+1.30s cold, 0.04s warm for `get_range`, and 1.01s to 0.14s for `iter_range`,
+which caches each day's partition separately.
+
+Only *final* answers are stored. A window reaching into the current day is
+never cached, and neither is one the service clamped at the end, because both
+legitimately return more data later. A cached answer carries the same
+`.attrs['quantpad']` as the network one, so a hit and a miss are
+indistinguishable to your code.
+
+Defaults, all overridable:
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `QPD_CACHE` | `1` | Set `0` to disable entirely |
+| `QPD_CACHE_DIR` | platform user-cache dir | Where entries live |
+| `QPD_CACHE_MAX_BYTES` | 1 GiB | Least-recently-used entries are evicted past this |
+
+The cache is best-effort by design: a full disk, an unwritable directory or a
+corrupt entry costs you the speedup and never the request.
+
+```python
+from quantpad_data import cache
+
+cache.total_bytes()   # how much is on disk
+cache.clear()         # throw it all away
+```
+
 ### Other namespaces
 
 `client.symbology.resolve(...)`, the `client.metadata.*` mirrors

{quantpad_data-0.4.2 → quantpad_data-0.5.1}/README.md

@@ -54,8 +54,7 @@ client honors `Retry-After` and uses exponential backoff for transient failures.
 QuantPad notebooks remain compatible through `QUANTPAD_NOTEBOOK_DATA_TOKEN`.
 
 Bars preserve the notebook helper's OHLCV aliases and smart futures
-back-adjustment default. Tick timestamps are epoch nanoseconds. Install
-`quantpad-data[rth]` for XNYS regular-session helpers.
+back-adjustment default. Tick timestamps are epoch nanoseconds.
 
 `mbp-10` is true L2 depth with bid/ask price, size, and order-count fields at
 levels 0-9. It is available for supported CME futures, individual CME
@@ -151,6 +150,66 @@ job = client.batch.submit(
 client.batch.hydrate(job["job_id"])
 ```
 
+### Regular trading hours
+
+`get_range` returns the whole published session, which for US equities includes
+pre- and post-market. That is what the upstream feed publishes, and it is more
+data than QuantPad's older `/v1` tick endpoints returned: those enumerated
+exchange sessions, and the XNYS calendar's open and close *are* regular hours,
+so `/v1` excluded the extended session without saying so — around 7% of the
+rows on a liquid name.
+
+If you want that narrower scope, ask for it:
+
+```python
+df = client.timeseries.get_range_rth(
+    dataset="XNAS.ITCH", symbols="BA", schema="trades",
+    start="2026-09-16", end="2026-09-17",
+)
+```
+
+`iter_range_rth` is the streaming form. Both follow the exchange calendar, so
+half-days close early and holidays are skipped, and both filter on `ts_event`
+— the clock `/v1` presented as its `t` column — so the numbers are comparable
+with a `/v1` result. Requires the calendar extra: `pip install
+'quantpad-data[rth]'`.
+
+The window sent to the service is still the whole range; the narrowing happens
+here. So the size budget applies to the full session either way, and a window
+too large unfiltered is too large for `get_range_rth` too — use
+`iter_range_rth` for those.
+
+### The disk cache
+
+Settled `/v2` answers are cached on disk, so asking twice costs the network
+once. Measured against production on a day of `BA` `mbp-10` (237,916 rows):
+1.30s cold, 0.04s warm for `get_range`, and 1.01s to 0.14s for `iter_range`,
+which caches each day's partition separately.
+
+Only *final* answers are stored. A window reaching into the current day is
+never cached, and neither is one the service clamped at the end, because both
+legitimately return more data later. A cached answer carries the same
+`.attrs['quantpad']` as the network one, so a hit and a miss are
+indistinguishable to your code.
+
+Defaults, all overridable:
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `QPD_CACHE` | `1` | Set `0` to disable entirely |
+| `QPD_CACHE_DIR` | platform user-cache dir | Where entries live |
+| `QPD_CACHE_MAX_BYTES` | 1 GiB | Least-recently-used entries are evicted past this |
+
+The cache is best-effort by design: a full disk, an unwritable directory or a
+corrupt entry costs you the speedup and never the request.
+
+```python
+from quantpad_data import cache
+
+cache.total_bytes()   # how much is on disk
+cache.clear()         # throw it all away
+```
+
 ### Other namespaces
 
 `client.symbology.resolve(...)`, the `client.metadata.*` mirrors

{quantpad_data-0.4.2 → quantpad_data-0.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quantpad-data"
-version = "0.4.2"
+version = "0.5.1"
 description = "Official Python client for the QuantPad market-data API"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -23,7 +23,10 @@ classifiers = [
 
 [project.optional-dependencies]
 rth = ["exchange-calendars>=4.5"]
-test = ["pytest>=8", "build>=1.2"]
+# The calendar is in `test` as well as `rth` on purpose: tests/test_rth.py
+# importorskips it, so without it here CI would report green having run none of
+# the regular-hours suite.
+test = ["pytest>=8", "build>=1.2", "exchange-calendars>=4.5"]
 
 [project.urls]
 Documentation = "https://api.quantpad.ai/external/docs"

quantpad_data-0.5.1/quantpad_data/__init__.py

@@ -0,0 +1,219 @@
+"""QuantPad market-data SDK and notebook-compatible function API."""
+
+from __future__ import annotations
+
+from typing import Iterator, Optional
+
+import numpy as np
+import pandas as pd
+import pyarrow as pa
+
+from .client import Client, ROLL_ADJUST_MODES, TICK_SCHEMAS, USER_AGENT, VERSION
+from .errors import (
+    AuthenticationError,
+    NotFoundError,
+    PermissionDeniedError,
+    QuantPadDataError,
+    QuantPadDataNotReady,
+    QuotaExceededError,
+    RateLimitError,
+    ResponseTooLargeError,
+    UpstreamError,
+    V2NotAvailableError,
+    ValidationError,
+)
+
+__version__ = VERSION
+QuantPadClient = Client
+
+
+def _client(**kwargs) -> Client:
+    return Client(**kwargs)
+
+
+def get_bars(symbol, timeframe, start_ms, end_ms, *, max_rows=None, as_df=True,
+             roll_adjust=None):
+    return _client().get_bars(
+        symbol, timeframe, start_ms, end_ms, max_rows=max_rows,
+        as_df=as_df, roll_adjust=roll_adjust,
+    )
+
+
+def get_bars_with_retry(symbol, timeframe, start_ms, end_ms, *, max_rows=None,
+                        retries=3, sleep_seconds=10, roll_adjust=None):
+    # Client retries use Retry-After and exponential jitter. ``sleep_seconds``
+    # remains accepted so existing notebooks do not break.
+    return Client(max_retries=max(0, int(retries) - 1)).get_bars(
+        symbol, timeframe, start_ms, end_ms, max_rows=max_rows,
+        roll_adjust=roll_adjust,
+    )
+
+
+def get_ticks(symbol, schema, start_ms, end_ms, *, columns=None, chunksize=250_000):
+    return _client().get_ticks(
+        symbol, schema, start_ms, end_ms, columns=columns, chunksize=chunksize
+    )
+
+
+def get_trades(symbol, start_ms, end_ms, *, columns=None, chunk_rows=250_000):
+    return get_ticks(
+        symbol, "trades", start_ms, end_ms, columns=columns, chunksize=chunk_rows
+    )
+
+
+def get_mbp1(symbol, start_ms, end_ms, *, columns=None, chunk_rows=250_000):
+    return get_ticks(
+        symbol, "mbp-1", start_ms, end_ms, columns=columns, chunksize=chunk_rows
+    )
+
+
+def get_mbp10(symbol, start_ms, end_ms, *, columns=None, chunk_rows=250_000):
+    return get_ticks(
+        symbol, "mbp-10", start_ms, end_ms, columns=columns, chunksize=chunk_rows
+    )
+
+
+def symbology_resolve(dataset=None, symbols=None, stype_in=None, stype_out=None,
+                      start_date=None, end_date=None):
+    return _client().symbology_resolve(
+        dataset, symbols, stype_in, stype_out, start_date, end_date
+    )
+
+
+def get_universe(query: str, *, limit: int = 20, asset_class: str | None = None):
+    return _client().get_universe(query, limit=limit, asset_class=asset_class)
+
+
+def get_coverage(symbol: str):
+    return _client().get_coverage(symbol)
+
+
+def _iter_rth_windows_ms(start_ms: int, end_ms: int):
+    try:
+        import exchange_calendars as ec
+    except ImportError as exc:
+        raise RuntimeError(
+            "RTH helpers require: pip install 'quantpad-data[rth]'"
+        ) from exc
+    cal = ec.get_calendar("XNYS")
+    start_day = pd.Timestamp(start_ms, unit="ms", tz="UTC").tz_convert(
+        "America/New_York"
+    ).date()
+    end_day = pd.Timestamp(end_ms - 1, unit="ms", tz="UTC").tz_convert(
+        "America/New_York"
+    ).date()
+    for session in cal.sessions_in_range(pd.Timestamp(start_day), pd.Timestamp(end_day)):
+        open_ms = int(cal.session_open(session).timestamp() * 1000)
+        close_ms = int(cal.session_close(session).timestamp() * 1000)
+        left, right = max(open_ms, int(start_ms)), min(close_ms, int(end_ms))
+        if left < right:
+            yield left, right
+
+
+def _stream_ticks_rth(symbol, schema, start_ms, end_ms, *, columns, chunk_rows):
+    for open_ms, close_ms in _iter_rth_windows_ms(start_ms, end_ms):
+        for frame in get_ticks(
+            symbol, schema, open_ms, close_ms,
+            columns=columns, chunksize=chunk_rows,
+        ):
+            if "t" in frame:
+                frame = frame.loc[
+                    (frame["t"] >= open_ms * 1_000_000)
+                    & (frame["t"] < close_ms * 1_000_000)
+                ]
+            if not frame.empty:
+                yield frame
+
+
+def get_trades_rth(symbol, start_ms, end_ms, *, columns=None, chunk_rows=250_000):
+    return _stream_ticks_rth(
+        symbol, "trades", start_ms, end_ms, columns=columns, chunk_rows=chunk_rows
+    )
+
+
+def get_mbp1_rth(symbol, start_ms, end_ms, *, columns=None, chunk_rows=250_000):
+    return _stream_ticks_rth(
+        symbol, "mbp-1", start_ms, end_ms, columns=columns, chunk_rows=chunk_rows
+    )
+
+
+def get_mbp10_rth(symbol, start_ms, end_ms, *, columns=None, chunk_rows=250_000):
+    return _stream_ticks_rth(
+        symbol, "mbp-10", start_ms, end_ms, columns=columns, chunk_rows=chunk_rows
+    )
+
+
+def get_spread_1m_rth(symbol, start_ms, end_ms, *, chunk_rows=250_000):
+    pieces = []
+    for frame in get_mbp1_rth(
+        symbol, start_ms, end_ms,
+        columns=["t", "bid_px", "ask_px"], chunk_rows=chunk_rows,
+    ):
+        spread = frame["ask_px"] - frame["bid_px"]
+        valid = spread.notna() & (spread >= 0)
+        if valid.any():
+            index = pd.to_datetime(frame.loc[valid, "t"], unit="ns", utc=True)
+            pieces.append(pd.Series(spread.loc[valid].to_numpy(), index=index))
+    if not pieces:
+        return pd.DataFrame(
+            {"spread": pd.Series(dtype="float64")},
+            index=pd.DatetimeIndex([], name="t", tz="UTC"),
+        )
+    result = pd.concat(pieces).resample("1min").mean().to_frame("spread")
+    result.index.name = "t"
+    return result
+
+
+def iter_trades(symbol, start_ms, end_ms, *, columns=None, chunksize=250_000):
+    return get_trades(
+        symbol, start_ms, end_ms, columns=columns, chunk_rows=chunksize
+    )
+
+
+def iter_mbp1(symbol, start_ms, end_ms, *, columns=None, chunksize=250_000):
+    return get_mbp1(symbol, start_ms, end_ms, columns=columns, chunk_rows=chunksize)
+
+
+def iter_l1_df_chunks(symbol, schema="trades", start_ms=0, end_ms=0,
+                      chunksize=250_000, usecols: Optional[list[str]] = None,
+                      time_col="ts_event", set_datetime_index=True, channel=None,
+                      chunk_size=None):
+    return get_ticks(
+        symbol, channel or schema, start_ms, end_ms, columns=usecols,
+        chunksize=chunk_size or chunksize,
+    )
+
+
+def iter_l1_trades_df_chunks(symbol, start_ms, end_ms, chunksize=250_000,
+                             usecols=None):
+    return iter_trades(
+        symbol, start_ms, end_ms, columns=usecols, chunksize=chunksize
+    )
+
+
+def iter_l1_mbp1_df_chunks(symbol, start_ms, end_ms, chunksize=250_000,
+                           usecols=None):
+    return iter_mbp1(symbol, start_ms, end_ms, columns=usecols, chunksize=chunksize)
+
+
+from . import cache  # noqa: E402  (submodule: on-disk cache for settled /v2)
+from . import lean  # noqa: E402  (submodule: LEAN backtesting data staging)
+from . import v2  # noqa: E402  (submodule: Databento-shaped explicit API)
+
+# Exported at the root as well as on ``v2``: the sandbox module reaches it
+# as ``qpd.Historical()``, and one spelling across both surfaces means
+# notebook code moves between them unchanged.
+Historical = v2.Historical
+
+__all__ = [
+    "Client", "QuantPadClient", "QuantPadDataError", "QuantPadDataNotReady", "AuthenticationError",
+    "PermissionDeniedError", "RateLimitError", "QuotaExceededError",
+    "NotFoundError", "V2NotAvailableError", "ValidationError", "UpstreamError",
+    "ResponseTooLargeError", "TICK_SCHEMAS",
+    "ROLL_ADJUST_MODES", "get_bars", "get_bars_with_retry", "get_ticks",
+    "get_trades", "get_mbp1", "get_mbp10", "get_trades_rth", "get_mbp1_rth",
+    "get_mbp10_rth", "get_spread_1m_rth", "symbology_resolve", "get_universe",
+    "get_coverage", "iter_trades", "iter_mbp1", "iter_l1_df_chunks",
+    "iter_l1_trades_df_chunks", "iter_l1_mbp1_df_chunks", "cache", "lean",
+    "v2", "Historical", "np", "pd", "pa",
+]