quantpad-data 0.2.1__tar.gz → 0.3.1__tar.gz

{quantpad_data-0.2.1 → quantpad_data-0.3.1}/.gitignore

@@ -14,3 +14,8 @@ venv/
 # 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

{quantpad_data-0.2.1 → quantpad_data-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quantpad-data
-Version: 0.2.1
+Version: 0.3.1
 Summary: Official Python client for the QuantPad market-data API
 Project-URL: Documentation, https://api.quantpad.ai/external/docs
 Author: QuantPad
@@ -88,6 +88,14 @@ symbology. It does not proxy FRED or SEC EDGAR.
 
 ## Explicit addressing: `qpd.v2`
 
+> **Not open yet.** `/v2` is limited to a small allowlist while it is
+> finished, so everything in this section will raise
+> `V2NotAvailableError` for you today — an API key is refused with 403
+> and a notebook token with 404, whatever arguments you pass. Nothing
+> above this section is affected: the `/v1` helpers carry the same data
+> and are generally available. Contact QuantPad support if you need
+> `/v2` access. This notice comes down when the gate does.
+
 The helpers above infer which dataset a symbol lives in and what kind of
 symbol it is. That is convenient until it is wrong, and when it is wrong it
 fails quietly — asking for a specific futures contract returns an empty frame

{quantpad_data-0.2.1 → quantpad_data-0.3.1}/README.md

@@ -67,6 +67,14 @@ symbology. It does not proxy FRED or SEC EDGAR.
 
 ## Explicit addressing: `qpd.v2`
 
+> **Not open yet.** `/v2` is limited to a small allowlist while it is
+> finished, so everything in this section will raise
+> `V2NotAvailableError` for you today — an API key is refused with 403
+> and a notebook token with 404, whatever arguments you pass. Nothing
+> above this section is affected: the `/v1` helpers carry the same data
+> and are generally available. Contact QuantPad support if you need
+> `/v2` access. This notice comes down when the gate does.
+
 The helpers above infer which dataset a symbol lives in and what kind of
 symbol it is. That is convenient until it is wrong, and when it is wrong it
 fails quietly — asking for a specific futures contract returns an empty frame

{quantpad_data-0.2.1 → quantpad_data-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quantpad-data"
-version = "0.2.1"
+version = "0.3.1"
 description = "Official Python client for the QuantPad market-data API"
 readme = "README.md"
 requires-python = ">=3.10"

{quantpad_data-0.2.1 → quantpad_data-0.3.1}/quantpad_data/client.py

@@ -21,10 +21,51 @@ from .errors import (
     QuotaExceededError,
     RateLimitError,
     UpstreamError,
+    V2NotAvailableError,
     ValidationError,
 )
 
-VERSION = "0.2.1"
+#: What the two ``/v2`` gates answer, verbatim.
+#:
+#: Matched on the exact message rather than on the status alone, because
+#: ``/v2`` returns both of these for real reasons too: a batch job that
+#: is not yours is a 404 ("No such batch job", deliberately, so job ids
+#: cannot be enumerated), and a window outside your plan is a 403. Those
+#: are answers about the request and must keep their own errors.
+#:
+#: The 404 is the service declining to confirm the feature exists. That
+#: is right for a stranger and wrong for us — this SDK documents
+#: ``qpd.v2`` in its own README, so there is nothing left to withhold
+#: from someone who has already called it.
+#:
+#: Confirmed by causing both against production, 2026-09-14, rather than
+#: by reading the router. Doing so turned up a distinction the source
+#: does not show: the gate's 404 is rendered by the app's error handler
+#: as ``{"error": "Not Found"}``, while a genuinely absent route falls
+#: through to FastAPI's own ``{"detail": "Not Found"}``. Both reduce to
+#: the same message here, so a typo'd ``/v2`` path — or any ``/v2``
+#: route on a server older than this SDK — is also reported as the gate.
+#: Left deliberately: while ``/v2`` is shut, every 404 on it does mean
+#: "you cannot use this", and keying on which JSON field the body
+#: happens to use would couple the SDK to a rendering detail. The
+#: discriminator is recorded here in case that trade ever stops holding.
+_V2_GATE_REPLIES = frozenset(
+    {
+        (403, "API keys cannot access this endpoint"),
+        (404, "Not Found"),
+    }
+)
+
+V2_NOT_AVAILABLE = (
+    "The /v2 API is not open yet. Your credentials are fine - /v2 is "
+    "limited to a small allowlist while it is finished, so qpd.v2 and "
+    "qpd.Historical will not work for you regardless of what you pass "
+    "them. The documented /v1 helpers (get_bars, get_ticks, get_universe, "
+    "get_coverage, symbology_resolve) are unaffected and carry the same "
+    "data. Contact QuantPad support if you need /v2 access."
+)
+
+VERSION = "0.3.1"
 USER_AGENT = f"quantpad-data-python/{VERSION}"
 TICK_SCHEMAS = (
     "trades", "mbp-1", "mbp-10", "cmbp-1", "tcbbo", "cbbo-1s",
@@ -101,7 +142,7 @@ class Client:
             pass
         return (response.text or f"HTTP {response.status_code}").strip()
 
-    def _raise_for_status(self, response: requests.Response) -> None:
+    def _raise_for_status(self, response: requests.Response, path: str = "") -> None:
         if response.ok:
             return
         message = self._message(response)
@@ -111,6 +152,8 @@ class Client:
         except (KeyError, TypeError, ValueError):
             pass
         status = response.status_code
+        if (status, message) in _V2_GATE_REPLIES and path.startswith("/v2/"):
+            raise V2NotAvailableError(V2_NOT_AVAILABLE, status)
         if status == 400:
             raise ValidationError(message)
         if status == 401:
@@ -136,7 +179,7 @@ class Client:
                 response = self.session.request(
                     method, f"{self.base_url}{path}", headers=headers, **kwargs
                 )
-                self._raise_for_status(response)
+                self._raise_for_status(response, path)
                 return response
             except RateLimitError as exc:
                 if response is not None:

{quantpad_data-0.2.1 → quantpad_data-0.3.1}/quantpad_data/errors.py

@@ -48,6 +48,30 @@ class NotFoundError(ValueError, QuantPadDataError):
     pass
 
 
+class V2NotAvailableError(NotFoundError, PermissionDeniedError):
+    """``/v2`` is gated and this caller is not through the gate.
+
+    Its own class because the two gates are otherwise indistinguishable
+    from real answers, and the 404 one is actively misleading: a caller
+    who wrapped ``get_range`` in ``except NotFoundError`` to mean "no
+    data for that symbol" would report exactly that, for a request the
+    service never looked at.
+
+    Inherits from **both** errors the gates would otherwise raise, so
+    existing ``except NotFoundError`` and ``except PermissionDeniedError``
+    clauses keep catching it and this stays a message change for anyone
+    who has already written against it.
+    """
+
+    def __init__(self, message: str, status_code: int | None = None):
+        # NotFoundError comes first in the MRO and reaches ValueError's
+        # __init__, which does not take status_code — hence setting it
+        # here rather than delegating, the same reason the base class
+        # carries a class-level default.
+        super().__init__(message)
+        self.status_code = status_code
+
+
 class ValidationError(ValueError, QuantPadDataError):
     pass
 

quantpad_data-0.3.1/tests/test_message_encoding.py

@@ -0,0 +1,85 @@
+"""Runtime strings stay ASCII, because they are read on real terminals.
+
+Found by running the SDK against production and watching the em-dash in
+``V2_NOT_AVAILABLE`` come back as a replacement character on a Windows
+console. The message exists to be legible; a message that renders as
+mojibake on a chunk of our users' terminals is not doing its job, and
+the irony of it being the "here is what actually went wrong" string was
+the tell.
+
+Scoped to runtime string *literals*. Docstrings and comments are read in
+an editor and keep their typography.
+"""
+
+from __future__ import annotations
+
+import ast
+import pathlib
+
+import pytest
+
+PACKAGE = pathlib.Path(__file__).resolve().parent.parent / "quantpad_data"
+
+
+def _runtime_strings(path: pathlib.Path):
+    """Every string constant that is not a docstring, with its line."""
+    tree = ast.parse(path.read_text(encoding="utf-8"))
+    docstrings = set()
+    for node in ast.walk(tree):
+        if isinstance(
+            node, (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)
+        ):
+            text = ast.get_docstring(node, clean=False)
+            if text:
+                docstrings.add(text)
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Constant) and isinstance(node.value, str):
+            if node.value not in docstrings:
+                yield node.lineno, node.value
+
+
+@pytest.mark.parametrize(
+    "module", sorted(PACKAGE.rglob("*.py")), ids=lambda p: p.name
+)
+def test_no_runtime_string_needs_a_utf8_terminal(module: pathlib.Path):
+    offenders = [
+        (line, sorted({c for c in value if ord(c) > 127}), value[:60])
+        for line, value in _runtime_strings(module)
+        if any(ord(c) > 127 for c in value)
+    ]
+    assert not offenders, (
+        f"{module.name} has runtime strings that need a UTF-8 terminal: "
+        f"{offenders}. Use ASCII - these are printed to consoles we do "
+        f"not control."
+    )
+
+
+def test_the_check_can_actually_see_a_violation():
+    """A guard that passes on everything is not a guard.
+
+    The trap this repo keeps hitting: a diagnostic built to confirm a
+    change will confirm it. So prove the detector fires.
+    """
+    source = 'X = "an em dash \u2014 here"\n'
+    tree = ast.parse(source)
+    found = [
+        n.value
+        for n in ast.walk(tree)
+        if isinstance(n, ast.Constant) and isinstance(n.value, str)
+    ]
+    assert any(any(ord(c) > 127 for c in v) for v in found)
+
+
+def test_prose_is_deliberately_exempt():
+    """The scoping is the whole design, so pin it both ways.
+
+    ``client.py`` is full of em-dashes in comments and docstrings and
+    must stay passing. If the check ever widens to the raw file, that is
+    a false positive on prose nobody prints.
+    """
+    source = (PACKAGE / "client.py").read_text(encoding="utf-8")
+    assert "\u2014" in source, "expected this module's prose to use em-dashes"
+
+    runtime = [v for _, v in _runtime_strings(PACKAGE / "client.py")]
+    assert runtime, "parser returned nothing - it would pass vacuously"
+    assert not [v for v in runtime if any(ord(c) > 127 for c in v)]

quantpad_data-0.3.1/tests/test_v2_gate.py

@@ -0,0 +1,215 @@
+"""The ``/v2`` gates must be legible, and must not swallow real answers.
+
+``/v2`` is shut to everyone but a two-account allowlist, and it says so
+in two different ways: an API key is refused 403 "API keys cannot access
+this endpoint", a notebook token 404 "Not Found". The second is the
+dangerous one — it is indistinguishable from "that symbol has no data",
+which is a thing callers legitimately wrap in ``except NotFoundError``.
+
+What these tests mostly guard is the *other* direction. ``/v2`` returns
+403 and 404 for real reasons too, and translating those into "the API is
+not open" would replace a true answer with a false one.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+import requests
+
+from quantpad_data.client import V2_NOT_AVAILABLE, Client
+from quantpad_data.errors import (
+    NotFoundError,
+    PermissionDeniedError,
+    QuantPadDataError,
+    V2NotAvailableError,
+)
+
+
+def _response(
+    status: int,
+    detail,
+    url: str = "https://example.test/v2/timeseries/get_range",
+    field: str = "error",
+):
+    """Default to ``error``, which is what production actually sends.
+
+    Confirmed by causing both gates against api.quantpad.ai on
+    2026-09-14: the app's handler renders ``{"error": ...}``, and only a
+    route that does not exist at all falls through to FastAPI's
+    ``{"detail": ...}``. The client reads either, and both shapes are
+    exercised below so that stays true.
+    """
+    response = requests.Response()
+    response.status_code = status
+    response.url = url
+    response._content = json.dumps({field: detail}).encode()
+    response.headers["Content-Type"] = "application/json"
+    return response
+
+
+def _client() -> Client:
+    return Client(api_key="k", base_url="https://example.test")
+
+
+class TestTheGateIsNamed:
+    def test_the_api_key_gate_is_not_reported_as_a_bare_permission_problem(self):
+        with pytest.raises(V2NotAvailableError) as caught:
+            _client()._raise_for_status(
+                _response(403, "API keys cannot access this endpoint"),
+                "/v2/timeseries/get_range",
+            )
+        assert caught.value.status_code == 403
+        assert "not open yet" in str(caught.value)
+
+    def test_the_notebook_gate_is_not_reported_as_a_missing_symbol(self):
+        """The whole point. A 404 here means the service never looked."""
+        with pytest.raises(V2NotAvailableError) as caught:
+            _client()._raise_for_status(
+                _response(404, "Not Found"), "/v2/timeseries/get_range"
+            )
+        assert caught.value.status_code == 404
+        assert str(caught.value) == V2_NOT_AVAILABLE
+
+    def test_the_message_says_v1_still_works(self):
+        """A caller who reads this should not conclude the SDK is broken."""
+        assert "get_bars" in V2_NOT_AVAILABLE
+        assert "not open yet" in V2_NOT_AVAILABLE
+
+    @pytest.mark.parametrize("field", ["error", "detail"])
+    def test_both_body_shapes_are_recognised(self, field):
+        """Production sends ``error``; FastAPI's own 404 sends ``detail``.
+        The client reads either, so the gate must not depend on which."""
+        with pytest.raises(V2NotAvailableError):
+            _client()._raise_for_status(
+                _response(404, "Not Found", field=field), "/v2/timeseries/get_range"
+            )
+
+
+class TestExistingCatchesStillCatchIt:
+    """The new class inherits from both gates' original errors on purpose.
+
+    Anyone who already wrote against either keeps working; this is a
+    message change for them, not a break.
+    """
+
+    @pytest.mark.parametrize(
+        "status, detail",
+        [(403, "API keys cannot access this endpoint"), (404, "Not Found")],
+    )
+    @pytest.mark.parametrize(
+        "caught_as", [NotFoundError, PermissionDeniedError, QuantPadDataError]
+    )
+    def test_the_old_exception_types_still_match(self, status, detail, caught_as):
+        with pytest.raises(caught_as):
+            _client()._raise_for_status(
+                _response(status, detail), "/v2/timeseries/get_range"
+            )
+
+
+class TestRealAnswersSurvive:
+    """``/v2``'s other 403s and 404s are answers, not gates."""
+
+    def test_an_unknown_batch_job_is_still_a_missing_thing(self):
+        """404 "No such batch job" is deliberate — it stops job-id
+        enumeration — and it is about the request, not about access."""
+        with pytest.raises(NotFoundError) as caught:
+            _client()._raise_for_status(
+                _response(404, "No such batch job", url="https://example.test/v2/batch/x/files"),
+                "/v2/batch/x/files",
+            )
+        assert not isinstance(caught.value, V2NotAvailableError)
+        assert "No such batch job" in str(caught.value)
+
+    def test_an_out_of_plan_window_is_still_a_permission_problem(self):
+        with pytest.raises(PermissionDeniedError) as caught:
+            _client()._raise_for_status(
+                _response(
+                    403,
+                    "That window is outside what this subscription carries "
+                    "for this schema.",
+                ),
+                "/v2/timeseries/get_range",
+            )
+        assert not isinstance(caught.value, V2NotAvailableError)
+        assert "subscription" in str(caught.value)
+
+    def test_a_v1_404_is_untouched(self):
+        """The gate only exists on /v2. A /v1 miss is a real miss."""
+        with pytest.raises(NotFoundError) as caught:
+            _client()._raise_for_status(
+                _response(404, "Not Found", url="https://example.test/v1/bars"),
+                "/v1/bars",
+            )
+        assert not isinstance(caught.value, V2NotAvailableError)
+
+    def test_the_prefix_is_anchored_not_merely_contained(self):
+        """No ``/v1`` route contains "v2" today, so this guards a contract
+        rather than a live bug — but it is the contract the whole design
+        rests on. A substring test would relabel a genuine miss on any
+        future path with "v2" in it as "the API is not open", which is
+        the same lie this class exists to prevent, told the other way
+        round. Futures codes alone make that plausible: ESV2 is a real
+        contract month.
+        """
+        for path in ("/v1/coverage/ESV2", "/v1/v2meta", "/healthz/v2"):
+            with pytest.raises(NotFoundError) as caught:
+                _client()._raise_for_status(_response(404, "Not Found"), path)
+            assert not isinstance(caught.value, V2NotAvailableError), path
+
+    def test_the_path_is_what_decides_not_the_message_alone(self):
+        """Same body, same status, different route — different meaning."""
+        gated = pytest.raises(V2NotAvailableError)
+        with gated:
+            _client()._raise_for_status(
+                _response(404, "Not Found"), "/v2/symbology/resolve"
+            )
+        with pytest.raises(NotFoundError) as plain:
+            _client()._raise_for_status(_response(404, "Not Found"), "/v1/coverage")
+        assert not isinstance(plain.value, V2NotAvailableError)
+
+
+class TestItIsActuallyWiredUp:
+    """Everything above calls the translator directly and passes the path
+    by hand, so all of it would still pass if ``_request`` stopped
+    handing the path over. These drive the real call instead.
+    """
+
+    class _Session:
+        def __init__(self, response):
+            self.headers: dict[str, str] = {}
+            self._response = response
+            self.calls: list[tuple] = []
+
+        def request(self, method, url, **kwargs):
+            self.calls.append((method, url, kwargs))
+            return self._response
+
+    def test_a_real_v2_call_reports_the_gate(self):
+        session = self._Session(_response(404, "Not Found"))
+        client = Client(api_key="k", base_url="https://example.test", session=session, max_retries=0)
+        with pytest.raises(V2NotAvailableError):
+            client._request("POST", "/v2/timeseries/get_range", json={})
+
+    def test_a_real_v1_call_with_the_same_reply_does_not(self):
+        session = self._Session(_response(404, "Not Found"))
+        client = Client(api_key="k", base_url="https://example.test", session=session, max_retries=0)
+        with pytest.raises(NotFoundError) as caught:
+            client._request("GET", "/v1/coverage")
+        assert not isinstance(caught.value, V2NotAvailableError)
+
+
+class TestItSurvivesTheRoundTrip:
+    def test_status_code_is_readable_despite_the_valueerror_base(self):
+        """NotFoundError reaches ValueError's __init__, which drops the
+        status. The subclass sets it explicitly; this is the regression
+        test for that being removed."""
+        error = V2NotAvailableError(V2_NOT_AVAILABLE, 404)
+        assert error.status_code == 404
+
+    def test_it_is_exported_at_the_root(self):
+        import quantpad_data
+
+        assert quantpad_data.V2NotAvailableError is V2NotAvailableError
+        assert "V2NotAvailableError" in quantpad_data.__all__

quantpad_data-0.2.1/quantpad_data/__init__.py

@@ -1,215 +0,0 @@
-"""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)
-
-
-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", "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", "lean", "v2",
-    "Historical", "np", "pd", "pa",
-]