quantpad-data 0.1.0__py3-none-any.whl

quantpad_data/__init__.py

@@ -0,0 +1,206 @@
+"""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,
+    UpstreamError,
+    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)
+
+
+__all__ = [
+    "Client", "QuantPadClient", "QuantPadDataError", "QuantPadDataNotReady", "AuthenticationError",
+    "PermissionDeniedError", "RateLimitError", "QuotaExceededError",
+    "NotFoundError", "ValidationError", "UpstreamError", "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", "np", "pd", "pa",
+]

quantpad_data/client.py

@@ -0,0 +1,273 @@
+"""Synchronous QuantPad Data API client."""
+
+from __future__ import annotations
+
+import io
+import os
+import random
+import time
+from datetime import date
+from typing import Iterator, Sequence
+
+import pandas as pd
+import pyarrow.ipc as ipc
+import requests
+
+from .errors import (
+    AuthenticationError,
+    NotFoundError,
+    PermissionDeniedError,
+    QuantPadDataError,
+    QuotaExceededError,
+    RateLimitError,
+    UpstreamError,
+    ValidationError,
+)
+
+VERSION = "0.1.0"
+USER_AGENT = f"quantpad-data-python/{VERSION}"
+TICK_SCHEMAS = (
+    "trades", "mbp-1", "mbp-10", "cmbp-1", "tcbbo", "cbbo-1s",
+    "cbbo-1m", "definition", "statistics", "status",
+)
+ROLL_ADJUST_MODES = ("none", "back", "ratio")
+
+
+class Client:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        token: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 120,
+        max_retries: int = 3,
+        session: requests.Session | None = None,
+    ) -> None:
+        self.api_key = (api_key or os.getenv("QUANTPAD_API_KEY") or "").strip() or None
+        self.token = (
+            token or os.getenv("QUANTPAD_NOTEBOOK_DATA_TOKEN") or ""
+        ).strip() or None
+        self.base_url = (
+            base_url
+            or os.getenv("QUANTPAD_API_BASE")
+            or os.getenv("QUANTPAD_NOTEBOOK_DATA_API_BASE")
+            or "https://api.quantpad.ai"
+        ).rstrip("/")
+        self.timeout = float(timeout)
+        self.max_retries = max(0, int(max_retries))
+        self.session = session or requests.Session()
+        self.session.headers.update({"User-Agent": USER_AGENT})
+
+    def _headers(self) -> dict[str, str]:
+        if self.api_key:
+            return {"X-API-Key": self.api_key}
+        if self.token:
+            return {"Authorization": f"Bearer {self.token}"}
+        raise AuthenticationError(
+            "Set QUANTPAD_API_KEY, or run inside QuantPad with "
+            "QUANTPAD_NOTEBOOK_DATA_TOKEN."
+        )
+
+    @staticmethod
+    def _message(response: requests.Response) -> str:
+        try:
+            body = response.json()
+            if isinstance(body, dict):
+                return str(body.get("error") or body.get("detail") or body)
+        except ValueError:
+            pass
+        return (response.text or f"HTTP {response.status_code}").strip()
+
+    def _raise_for_status(self, response: requests.Response) -> None:
+        if response.ok:
+            return
+        message = self._message(response)
+        retry_after: float | None = None
+        try:
+            retry_after = float(response.headers["Retry-After"])
+        except (KeyError, TypeError, ValueError):
+            pass
+        if response.status_code == 400:
+            raise ValidationError(message)
+        if response.status_code == 401:
+            raise AuthenticationError(message)
+        if response.status_code == 403:
+            raise PermissionDeniedError(message)
+        if response.status_code == 404:
+            raise NotFoundError(message)
+        if response.status_code == 429:
+            cls = QuotaExceededError if "quota" in message.lower() else RateLimitError
+            raise cls(message, retry_after)
+        if response.status_code >= 500:
+            raise UpstreamError(message)
+        raise QuantPadDataError(message)
+
+    def _request(self, method: str, path: str, **kwargs) -> requests.Response:
+        kwargs.setdefault("timeout", self.timeout)
+        headers = {**self._headers(), **kwargs.pop("headers", {})}
+        last_error: Exception | None = None
+        for attempt in range(self.max_retries + 1):
+            response: requests.Response | None = None
+            try:
+                response = self.session.request(
+                    method, f"{self.base_url}{path}", headers=headers, **kwargs
+                )
+                self._raise_for_status(response)
+                return response
+            except RateLimitError as exc:
+                if response is not None:
+                    response.close()
+                last_error = exc
+                if attempt >= self.max_retries:
+                    raise
+                delay = exc.retry_after
+            except (requests.ConnectionError, requests.Timeout, UpstreamError) as exc:
+                if response is not None:
+                    response.close()
+                last_error = exc
+                if attempt >= self.max_retries:
+                    raise
+                delay = None
+            base_delay = delay if delay is not None else min(8.0, 0.5 * (2**attempt))
+            time.sleep(max(0.0, base_delay) + random.uniform(0, 0.25))
+        raise QuantPadDataError(str(last_error or "Request failed"))
+
+    @staticmethod
+    def _roll_adjust(symbol: str, value: str | None) -> str:
+        if value is None:
+            return "back" if symbol.strip().upper().endswith(".FUT") else "none"
+        mode = str(value).strip().lower()
+        if mode not in ROLL_ADJUST_MODES:
+            raise ValidationError(f"roll_adjust must be one of {ROLL_ADJUST_MODES}")
+        return mode
+
+    def get_bars(
+        self,
+        symbol: str,
+        timeframe: str,
+        start_ms: int,
+        end_ms: int,
+        *,
+        max_rows: int | None = None,
+        as_df: bool = True,
+        roll_adjust: str | None = None,
+    ) -> pd.DataFrame | list[dict]:
+        if int(end_ms) <= int(start_ms):
+            raise ValidationError("end_ms must be > start_ms")
+        params = {
+            "symbol": symbol.strip().upper(),
+            "timeframe": timeframe.strip().lower(),
+            "start": int(start_ms),
+            "end": int(end_ms),
+            "format": "arrow",
+            "roll_adjust": self._roll_adjust(symbol, roll_adjust),
+        }
+        response = self._request("GET", "/v1/bars", params=params, stream=True)
+        try:
+            table = ipc.open_stream(response.content).read_all()
+            frame = table.to_pandas()
+        except Exception:
+            response.close()
+            params["format"] = "csv"
+            fallback = self._request("GET", "/v1/bars", params=params, stream=True)
+            try:
+                frame = pd.read_csv(io.StringIO(fallback.text))
+            finally:
+                fallback.close()
+        finally:
+            response.close()
+        if "t" in frame.columns:
+            frame.index = pd.to_datetime(frame.pop("t"), unit="ms", utc=True)
+            frame.index.name = "t"
+        for short, long_name in (
+            ("o", "open"), ("h", "high"), ("l", "low"),
+            ("c", "close"), ("v", "volume"),
+        ):
+            if short in frame.columns and long_name not in frame.columns:
+                frame[long_name] = frame[short]
+        if max_rows is not None:
+            frame = frame.head(int(max_rows))
+        return frame if as_df else frame.reset_index().to_dict("records")
+
+    def get_ticks(
+        self,
+        symbol: str,
+        schema: str,
+        start_ms: int,
+        end_ms: int,
+        *,
+        columns: Sequence[str] | None = None,
+        chunksize: int = 250_000,
+    ) -> Iterator[pd.DataFrame]:
+        schema = schema.strip().lower()
+        if schema not in TICK_SCHEMAS:
+            raise ValidationError(f"schema must be one of {TICK_SCHEMAS}")
+        if chunksize <= 0 or int(end_ms) <= int(start_ms):
+            raise ValidationError("chunksize must be positive and end_ms > start_ms")
+        params: dict[str, str | int] = {
+            "symbol": symbol.strip().upper(),
+            "schema": schema,
+            "start": int(start_ms),
+            "end": int(end_ms),
+        }
+        if columns:
+            params["columns"] = ",".join(str(value).strip() for value in columns)
+        response = self._request(
+            "GET", "/v1/ticks", params=params, timeout=(30, 1800), stream=True
+        )
+        response.raw.decode_content = True
+        buffered: list[pd.DataFrame] = []
+        buffered_rows = 0
+        try:
+            for batch in ipc.open_stream(response.raw):
+                if not batch.num_rows:
+                    continue
+                buffered.append(batch.to_pandas(split_blocks=True, self_destruct=True))
+                buffered_rows += batch.num_rows
+                while buffered_rows >= chunksize:
+                    combined = pd.concat(buffered, ignore_index=True)
+                    yield combined.iloc[:chunksize].copy()
+                    remainder = combined.iloc[chunksize:]
+                    buffered = [remainder] if len(remainder) else []
+                    buffered_rows = len(remainder)
+            if buffered_rows:
+                yield pd.concat(buffered, ignore_index=True)
+        finally:
+            response.close()
+
+    def symbology_resolve(
+        self,
+        dataset=None,
+        symbols=None,
+        stype_in=None,
+        stype_out=None,
+        start_date=None,
+        end_date=None,
+    ) -> dict:
+        if symbols is None or stype_out is None or start_date is None:
+            raise ValidationError("symbols, stype_out, and start_date are required")
+        if isinstance(start_date, date):
+            start_date = start_date.isoformat()
+        if isinstance(end_date, date):
+            end_date = end_date.isoformat()
+        payload = {
+            "dataset": str(dataset) if dataset is not None else None,
+            "symbols": symbols if isinstance(symbols, (str, int)) else list(symbols),
+            "stype_in": str(stype_in) if stype_in is not None else None,
+            "stype_out": str(stype_out),
+            "start_date": start_date,
+            "end_date": end_date,
+        }
+        return self._request("POST", "/v1/symbology/resolve", json=payload).json()
+
+    def get_universe(
+        self, query: str, *, limit: int = 20, asset_class: str | None = None
+    ) -> dict:
+        params = {"q": query, "limit": int(limit)}
+        if asset_class:
+            params["asset_class"] = asset_class
+        return self._request("GET", "/v1/universe", params=params).json()
+
+    def get_coverage(self, symbol: str) -> dict:
+        return self._request("GET", "/v1/coverage", params={"symbol": symbol}).json()

quantpad_data/errors.py

@@ -0,0 +1,41 @@
+"""Typed QuantPad Data API exceptions."""
+
+from __future__ import annotations
+
+
+class QuantPadDataError(RuntimeError):
+    """Base error for API and transport failures."""
+
+
+class AuthenticationError(QuantPadDataError):
+    pass
+
+
+class PermissionDeniedError(QuantPadDataError):
+    pass
+
+
+class RateLimitError(QuantPadDataError):
+    def __init__(self, message: str, retry_after: float | None = None):
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class QuotaExceededError(RateLimitError):
+    pass
+
+
+class NotFoundError(ValueError, QuantPadDataError):
+    pass
+
+
+class ValidationError(ValueError, QuantPadDataError):
+    pass
+
+
+class UpstreamError(QuantPadDataError):
+    pass
+
+
+class QuantPadDataNotReady(QuantPadDataError):
+    """Backward-compatible error retained for older notebooks."""

quantpad_data/py.typed

@@ -0,0 +1 @@
+

quantpad_data-0.1.0.dist-info/METADATA

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: quantpad-data
+Version: 0.1.0
+Summary: Official Python client for the QuantPad market-data API
+Project-URL: Documentation, https://api.quantpad.ai/external/docs
+Author: QuantPad
+License: Proprietary
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pandas<3,>=2.2
+Requires-Dist: pyarrow>=18
+Requires-Dist: requests>=2.32
+Provides-Extra: rth
+Requires-Dist: exchange-calendars>=4.5; extra == 'rth'
+Provides-Extra: test
+Requires-Dist: build>=1.2; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# QuantPad Data Python SDK
+
+```bash
+pip install quantpad-data
+export QUANTPAD_API_KEY=qp_live_...
+```
+
+```python
+import time
+import quantpad_data as qpd
+
+end = int(time.time() * 1000)
+bars = qpd.get_bars("ES.FUT", "1m", end - 86_400_000, end)
+
+for chunk in qpd.get_ticks(
+    "AAPL", "trades", end - 3_600_000, end, columns=["t", "price", "size"]
+):
+    print(chunk.head())
+
+matches = qpd.get_universe("apple", asset_class="equity")
+coverage = qpd.get_coverage("AAPL")
+```
+
+`QuantPadClient` (also available as `Client`) accepts `api_key=`, `base_url=`,
+and `max_retries=`. The default
+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.
+
+This SDK intentionally exposes only bars, ticks, universe, coverage, and
+symbology. It does not proxy FRED or SEC EDGAR.

quantpad_data-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+quantpad_data/__init__.py,sha256=TZjloh2prMSz7QcsoCJzkhpjOE-IOQJ0O5OoOCPFZ04,7247
+quantpad_data/client.py,sha256=Mzj69znNq1y4nek0Ebcr_zr3bznxSnDOyAwrIa9DskU,10126
+quantpad_data/errors.py,sha256=MZrPSzy6SyQY_FcMx623Bspv1xN2TMn01ftxnAnl1ok,823
+quantpad_data/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+quantpad_data-0.1.0.dist-info/METADATA,sha256=MJbeCRJMPUbJ-KOM2a7mYJ0H8UVNNqYfbEq-1WQwo5Q,1752
+quantpad_data-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+quantpad_data-0.1.0.dist-info/RECORD,,

quantpad_data-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any