quantpad-data 0.7.0__tar.gz → 0.8.0__tar.gz

{quantpad_data-0.7.0 → quantpad_data-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quantpad-data
-Version: 0.7.0
+Version: 0.8.0
 Summary: Official Python client for the QuantPad market-data API
 Project-URL: Documentation, https://api.quantpad.ai/external/docs
 Author: QuantPad
@@ -243,7 +243,11 @@ cache.clear()         # throw it all away
 (`list_datasets`, `list_schemas`, `list_fields`, `list_publishers`,
 `get_dataset_range`, `get_dataset_condition`, `get_record_count`), and
 `client.options.chain(...)` for enumerating strikes and expiries without
-downloading a day's entire `definition` schema.
+downloading a day's entire `definition` schema. A chain is capped at `limit`
+(5,000 by default, 50,000 at most); the frame's `attrs` carry the server's
+`count`, `total` and `truncated`, and a cut chain raises
+`TruncatedChainWarning` — `warnings.simplefilter("error",
+qpd.TruncatedChainWarning)` makes a partial chain a hard failure.
 
 There is no cost or unit-price surface. QuantPad data is included in the plan
 rather than metered per request.

{quantpad_data-0.7.0 → quantpad_data-0.8.0}/README.md

@@ -221,7 +221,11 @@ cache.clear()         # throw it all away
 (`list_datasets`, `list_schemas`, `list_fields`, `list_publishers`,
 `get_dataset_range`, `get_dataset_condition`, `get_record_count`), and
 `client.options.chain(...)` for enumerating strikes and expiries without
-downloading a day's entire `definition` schema.
+downloading a day's entire `definition` schema. A chain is capped at `limit`
+(5,000 by default, 50,000 at most); the frame's `attrs` carry the server's
+`count`, `total` and `truncated`, and a cut chain raises
+`TruncatedChainWarning` — `warnings.simplefilter("error",
+qpd.TruncatedChainWarning)` makes a partial chain a hard failure.
 
 There is no cost or unit-price surface. QuantPad data is included in the plan
 rather than metered per request.

{quantpad_data-0.7.0 → quantpad_data-0.8.0}/pyproject.toml

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

{quantpad_data-0.7.0 → quantpad_data-0.8.0}/quantpad_data/__init__.py

@@ -204,12 +204,16 @@ from . import v2  # noqa: E402  (submodule: Databento-shaped explicit API)
 # as ``qpd.Historical()``, and one spelling across both surfaces means
 # notebook code moves between them unchanged.
 Historical = v2.Historical
+# At the root for the same reason: ``warnings.simplefilter("error",
+# qpd.TruncatedChainWarning)`` is how a script turns a cut chain into a
+# failure, and it should not need to know which submodule warns.
+TruncatedChainWarning = v2.TruncatedChainWarning
 
 __all__ = [
     "Client", "QuantPadClient", "QuantPadDataError", "QuantPadDataNotReady", "AuthenticationError",
     "PermissionDeniedError", "RateLimitError", "QuotaExceededError",
     "NotFoundError", "V2NotAvailableError", "ValidationError", "UpstreamError",
-    "ResponseTooLargeError", "TICK_SCHEMAS",
+    "ResponseTooLargeError", "TruncatedChainWarning", "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",

{quantpad_data-0.7.0 → quantpad_data-0.8.0}/quantpad_data/client.py

@@ -84,7 +84,7 @@ V2_NOT_AVAILABLE = (
     "QuantPad support about /v2 access."
 )
 
-VERSION = "0.7.0"
+VERSION = "0.8.0"
 USER_AGENT = f"quantpad-data-python/{VERSION}"
 TICK_SCHEMAS = (
     "trades", "mbp-1", "mbp-10", "cmbp-1", "tcbbo", "cbbo-1s",
@@ -143,6 +143,25 @@ BARS_TIMEOUT = (30, 1800)
 V2_DATA_TIMEOUT = (10, 1800)
 
 
+def _prose_with_hint(error: dict) -> str:
+    """The sentence to raise from a structured refusal.
+
+    ``message`` first; a ``hint`` follows it as a second sentence when the
+    service sent one.  Kept out of the message on the wire so a caller
+    reading the body can still tell the refusal from the advice, and put
+    back here because the exception text is the only thing most callers
+    ever see.  A body with a hint and no message is stringified whole, as
+    it always was.
+    """
+    message = error.get("message")
+    if not message:
+        return str(error)
+    hint = error.get("hint")
+    if isinstance(hint, str) and hint.strip():
+        return f"{message} {hint.strip()}"
+    return str(message)
+
+
 class Client:
     def __init__(
         self,
@@ -189,6 +208,14 @@ class Client:
         user where the service had written a sentence.  So the prose is
         unwrapped from ``message`` when there is one, and the object is
         kept beside it for the callers that need to branch on it.
+
+        A ``hint`` rides with the prose.  The /v2 404 for a symbol nothing
+        resolves carries what to send instead -- ``NQ.FUT`` with
+        ``stype_in='parent'`` for a bare ``NQ`` -- as its own field so a
+        caller branching on the body can tell it from the message; but the
+        exception a notebook prints is the message, and advice a client
+        drops on the floor is advice nobody gets (the shape
+        ``options.chain`` had with ``truncated``).
         """
         try:
             body = response.json()
@@ -198,7 +225,7 @@ class Client:
             return str(body), None
         error = body.get("error") or body.get("detail") or body
         if isinstance(error, dict):
-            return str(error.get("message") or error), error
+            return _prose_with_hint(error), error
         return str(error), None
 
     @classmethod

{quantpad_data-0.7.0 → quantpad_data-0.8.0}/quantpad_data/v2.py

@@ -38,6 +38,7 @@ import io
 import json
 import os
 import tempfile
+import warnings
 from datetime import date, timedelta
 from typing import Any, Iterator, Sequence
 
@@ -920,6 +921,51 @@ class Metadata(_Namespace):
         return self._client._request("GET", path, params=clean).json()
 
 
+class TruncatedChainWarning(UserWarning):
+    """``options.chain`` returned fewer contracts than the filters matched.
+
+    The service caps a chain at ``limit`` (5,000 by default, 50,000 at
+    most) and says so in the body; this is that flag made audible.  Raise
+    ``limit`` or narrow the filters (``expiration``, ``strike_min``/
+    ``strike_max``, ``instrument_class``) for the whole chain.
+    """
+
+
+def _chain_frame(payload: dict) -> pd.DataFrame:
+    """The chain as a frame, carrying the server's count beside the rows.
+
+    The route answers ``count`` (rows in the body), ``total`` (rows the
+    filters matched) and ``truncated`` beside ``contracts``.  Until this
+    the frame was built from ``contracts`` alone and the other three were
+    dropped, so a notebook handed exactly 5,000 rows could not tell a cut
+    chain from a whole one -- verified on prod, where an unfiltered
+    SPY.OPT came back as exactly the default limit against ~12,470
+    instruments.  The three ride on ``frame.attrs`` (the same place
+    ``get_range`` keeps its echo) and a truncation is also warned, since
+    ``attrs`` is invisible to anyone not already looking for it.
+
+    Older servers send no ``total``; it is then unknown rather than
+    guessed, and ``truncated`` is read as the server sent it.
+    """
+    contracts = payload.get("contracts", [])
+    frame = pd.DataFrame(contracts)
+    truncated = bool(payload.get("truncated", False))
+    frame.attrs["count"] = payload.get("count", len(contracts))
+    frame.attrs["total"] = payload.get("total")
+    frame.attrs["truncated"] = truncated
+    if truncated:
+        total = frame.attrs["total"]
+        matched = f"{total:,} matched" if isinstance(total, int) else "more matched"
+        warnings.warn(
+            f"options.chain returned {len(contracts):,} contracts but "
+            f"{matched}: the chain was cut at the service's limit. Raise "
+            "limit= (up to 50,000) or narrow the filters to see the rest.",
+            TruncatedChainWarning,
+            stacklevel=3,
+        )
+    return frame
+
+
 class Options(_Namespace):
     """Options-chain enumeration.
 
@@ -927,6 +973,9 @@ class Options(_Namespace):
     the whole ``definition`` schema and filter it yourself.  This does
     that server-side, because "download every instrument definition for
     the day" is a poor answer to "what strikes exist".
+
+    The frame's ``attrs`` carry ``count``, ``total`` and ``truncated``;
+    a truncated chain also raises :class:`TruncatedChainWarning`.
     """
 
     def chain(
@@ -955,7 +1004,7 @@ class Options(_Namespace):
         payload = self._client._request(
             "GET", "/v2/options/chain", params=clean
         ).json()
-        return pd.DataFrame(payload.get("contracts", []))
+        return _chain_frame(payload)
 
 
 class Batch(_Namespace):

quantpad_data-0.8.0/tests/test_refusal_hint.py

@@ -0,0 +1,71 @@
+"""A structured refusal's ``hint`` reaches the exception text.
+
+The /v2 404 for a symbol nothing resolves carries what to send instead as
+its own ``hint`` field -- ``NQ.FUT with stype_in='parent'`` for a bare
+``NQ`` -- so a caller reading the body can tell the refusal from the
+advice.  The client used to raise ``message`` alone, which is the shape
+``options.chain`` had with ``truncated``: the server said the useful thing
+and the SDK dropped it before anyone could read it.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+import requests
+
+from quantpad_data.client import Client
+from quantpad_data.errors import NotFoundError
+
+MESSAGE = "None of the requested symbols resolve to an instrument on GLBX.MDP3 over this window."
+HINT = "For NQ try NQ.FUT with stype_in='parent' (every contract in the chain)."
+
+
+def _response(body: dict, status: int = 404) -> requests.Response:
+    response = requests.Response()
+    response.status_code = status
+    response.url = "https://example.test/v2/timeseries/get_range"
+    response._content = json.dumps({"error": body}).encode()
+    response.headers["Content-Type"] = "application/json"
+    return response
+
+
+def _client() -> Client:
+    return Client(api_key="k", base_url="https://example.test")
+
+
+class TestTheHintIsRaisedWithTheMessage:
+    def test_the_exception_text_carries_both_sentences_in_order(self):
+        with pytest.raises(NotFoundError) as caught:
+            _client()._raise_for_status(
+                _response({"message": MESSAGE, "hint": HINT, "not_found": ["NQ"]}),
+                "/v2/timeseries/get_range",
+            )
+        text = str(caught.value)
+        assert text == f"{MESSAGE} {HINT}"
+
+    def test_the_structured_body_is_still_available_beside_it(self):
+        """Branching callers read the fields; the hint joining the prose
+        must not take the fields away."""
+        message, detail = Client._envelope(
+            _response({"message": MESSAGE, "hint": HINT, "not_found": ["NQ"]})
+        )
+        assert detail["hint"] == HINT
+        assert detail["not_found"] == ["NQ"]
+        assert message.startswith(MESSAGE)
+
+    def test_a_refusal_without_a_hint_reads_exactly_as_before(self):
+        message, _ = Client._envelope(_response({"message": MESSAGE}))
+        assert message == MESSAGE
+
+    @pytest.mark.parametrize("hint", ["", "   ", None, 7, ["not", "prose"]])
+    def test_a_blank_or_non_prose_hint_adds_nothing(self, hint):
+        message, _ = Client._envelope(_response({"message": MESSAGE, "hint": hint}))
+        assert message == MESSAGE
+
+    def test_a_hint_with_no_message_does_not_become_the_message(self):
+        """A body with advice but no refusal is malformed; stringify it
+        whole as the client always has rather than promote the hint."""
+        message, _ = Client._envelope(_response({"hint": HINT}))
+        assert message == str({"hint": HINT})

{quantpad_data-0.7.0 → quantpad_data-0.8.0}/tests/test_v2.py

@@ -2117,6 +2117,79 @@ class TestTheOtherNamespaces:
         assert "strike_min" not in params
         assert "instrument_class" not in params
 
+    # chaintruncate: the route says when it cut the chain, and the frame
+    # used to drop that.  Verified on prod: unfiltered SPY.OPT returned
+    # exactly 5,000 rows (the default limit) against ~12,470 instruments,
+    # with no way to tell from the frame.
+
+    def test_a_cut_chain_warns_and_carries_the_servers_count(self):
+        import warnings
+
+        api, _ = client_with([json_response({
+            "count": 2, "total": 12470, "truncated": True,
+            "contracts": [
+                {"raw_symbol": "SPY   260116C00500000"},
+                {"raw_symbol": "SPY   260116P00500000"},
+            ],
+        })])
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            chain = api.options.chain(
+                dataset="OPRA.PILLAR", underlier="SPY.OPT", date="2026-01-05",
+            )
+        assert len(chain) == 2
+        assert chain.attrs["truncated"] is True
+        assert chain.attrs["count"] == 2
+        assert chain.attrs["total"] == 12470
+        (warning,) = [
+            w for w in caught if issubclass(w.category, quantpad_data.TruncatedChainWarning)
+        ]
+        text = str(warning.message)
+        assert "2 contracts" in text and "12,470 matched" in text
+        assert "limit=" in text  # the way out is named, not just the fact
+
+    def test_a_whole_chain_is_silent_and_says_so(self):
+        import warnings
+
+        api, _ = client_with([json_response({
+            "count": 1, "total": 1, "truncated": False,
+            "contracts": [{"raw_symbol": "ESM6 C4800"}],
+        })])
+        with warnings.catch_warnings():
+            warnings.simplefilter("error")  # any warning here is a failure
+            chain = api.options.chain(
+                dataset="GLBX.MDP3", underlier="ES.OPT", date="2026-01-05",
+            )
+        assert chain.attrs["truncated"] is False
+        assert chain.attrs["total"] == 1
+
+    def test_an_older_server_without_total_still_reports_the_cut(self):
+        """The deployed route sent ``truncated`` before it sent ``total``;
+        a frame from it must still say it was cut, with the total unknown
+        rather than invented."""
+        import warnings
+
+        api, _ = client_with([json_response({
+            "count": 1, "truncated": True, "contracts": [{"raw_symbol": "A"}],
+        })])
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            chain = api.options.chain(
+                dataset="GLBX.MDP3", underlier="ES.OPT", date="2026-01-05",
+            )
+        assert chain.attrs["truncated"] is True
+        assert chain.attrs["total"] is None
+        assert any(
+            issubclass(w.category, quantpad_data.TruncatedChainWarning) for w in caught
+        )
+
+    def test_the_truncation_warning_is_exported_at_the_root(self):
+        """``warnings.simplefilter("error", quantpad_data.TruncatedChainWarning)`` is
+        how a script refuses to run on a partial chain; it needs the name
+        without knowing which submodule warns."""
+        assert quantpad_data.TruncatedChainWarning is quantpad_data.v2.TruncatedChainWarning
+        assert issubclass(quantpad_data.TruncatedChainWarning, UserWarning)
+
     def test_batch_submit_and_hydrate_are_reachable(self):
         api, session = client_with([
             json_response({"job_id": "j1"}),