quantpad-data 0.3.0__tar.gz → 0.3.2__tar.gz

{quantpad_data-0.3.0 → quantpad_data-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quantpad-data
-Version: 0.3.0
+Version: 0.3.2
 Summary: Official Python client for the QuantPad market-data API
 Project-URL: Documentation, https://api.quantpad.ai/external/docs
 Author: QuantPad

{quantpad_data-0.3.0 → quantpad_data-0.3.2}/pyproject.toml

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

{quantpad_data-0.3.0 → quantpad_data-0.3.2}/quantpad_data/client.py

@@ -25,7 +25,21 @@ from .errors import (
     ValidationError,
 )
 
-#: What the two ``/v2`` gates answer, verbatim.
+#: Header by which the server names this refusal as the gate.
+#:
+#: Preferred over every message match below, and it exists because matching
+#: prose was load-bearing and should not have been. Two things broke it at
+#: once. The wording had to change — ``{"error": "Not Found"}`` is
+#: indistinguishable from an empty result, and a paying subscriber lost two
+#: days to exactly that confusion — and matching on it made the wording
+#: unimprovable, since any text that helps a human stops this SDK
+#: recognising the gate. Worse in the other direction: the moment the
+#: allowlist opens, a *genuine* ``/v2`` 404 renders the same two words, so
+#: this would tell a caller standing right through the gate that it was shut.
+_GATE_HEADER = "X-QP-Gate"
+
+#: What the two ``/v2`` gates answer, verbatim — **on servers predating
+#: ``_GATE_HEADER`` only.**
 #:
 #: 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
@@ -56,16 +70,26 @@ _V2_GATE_REPLIES = frozenset(
     }
 )
 
+#: Fallback wording, used only when the server sent no message of its own.
+#:
+#: Deliberately does **not** say "/v2 is not open yet" any more, and that
+#: sentence is why this constant is now a fallback rather than the answer.
+#: Rollout state is the server's to know and this string is compiled into a
+#: released wheel: it was true when 0.3.1 shipped and becomes a lie the hour
+#: the allowlist opens, at which point every pinned install would tell a
+#: subscriber who *has* access that they do not. Prefer the server's own
+#: ``detail``, which cannot go stale because it is written by the thing
+#: making the decision.
 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."
+    "This QuantPad /v2 request was refused by an access gate rather than by "
+    "anything about the request: your credentials are valid, and no change "
+    "of dataset, symbol or date range will get past it. The documented /v1 "
+    "helpers (get_bars, get_ticks, get_universe, get_coverage, "
+    "symbology_resolve) carry the same data and are unaffected. Contact "
+    "QuantPad support about /v2 access."
 )
 
-VERSION = "0.3.0"
+VERSION = "0.3.2"
 USER_AGENT = f"quantpad-data-python/{VERSION}"
 TICK_SCHEMAS = (
     "trades", "mbp-1", "mbp-10", "cmbp-1", "tcbbo", "cbbo-1s",
@@ -152,8 +176,16 @@ 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 path.startswith("/v2/"):
+            # The header is authoritative when present: the server declares
+            # that this refusal is the gate, so no prose has to be matched
+            # and a *genuine* /v2 404 is never mistaken for it.
+            if response.headers.get(_GATE_HEADER):
+                raise V2NotAvailableError(message or V2_NOT_AVAILABLE, status)
+            # Older servers do not send it, so keep matching what they say --
+            # but only while they are old.  See _V2_GATE_REPLIES.
+            if (status, message) in _V2_GATE_REPLIES:
+                raise V2NotAvailableError(V2_NOT_AVAILABLE, status)
         if status == 400:
             raise ValidationError(message)
         if status == 401:

quantpad_data-0.3.2/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.0 → quantpad_data-0.3.2}/tests/test_v2_gate.py

@@ -61,7 +61,7 @@ class TestTheGateIsNamed:
                 "/v2/timeseries/get_range",
             )
         assert caught.value.status_code == 403
-        assert "not open yet" in str(caught.value)
+        assert "refused by an access gate" 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."""
@@ -75,7 +75,20 @@ class TestTheGateIsNamed:
     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
+
+    def test_the_fallback_does_not_claim_to_know_the_rollout_state(self):
+        """This string is compiled into a released wheel, so it must not
+        assert anything only the server can know.
+
+        0.3.1 said "/v2 is not open yet", which was true when it shipped and
+        becomes false the hour the allowlist opens — at which point every
+        pinned install tells a subscriber who *does* have access that they do
+        not. That is the same class of error as the homepage advertising
+        endpoints the service refused, told backwards, and a wheel cannot be
+        corrected by a deploy.
+        """
+        for stale in ("not open yet", "small allowlist", "while it is finished"):
+            assert stale not in V2_NOT_AVAILABLE
 
     @pytest.mark.parametrize("field", ["error", "detail"])
     def test_both_body_shapes_are_recognised(self, field):
@@ -87,6 +100,89 @@ class TestTheGateIsNamed:
             )
 
 
+class TestTheServerCanSaySoItself:
+    """``X-QP-Gate`` replaces prose-matching, and the reason is that
+    prose-matching had to break for the message to get better.
+
+    While the gate answered ``{"error": "Not Found"}`` this SDK could only
+    identify it by matching those two words — so the body could never be
+    improved without the SDK losing track of it, and a subscriber reading
+    ``curl`` output could not tell the gate from an empty result. He lost two
+    days to that. The header decouples the two.
+    """
+
+    def test_the_header_is_believed_over_any_message(self):
+        response = _response(404, "Not Found")
+        response.headers["X-QP-Gate"] = "v2-allowlist"
+        with pytest.raises(V2NotAvailableError) as caught:
+            _client()._raise_for_status(response, "/v2/timeseries/get_range")
+        assert caught.value.status_code == 404
+
+    def test_the_servers_own_words_are_shown_not_the_canned_ones(self):
+        """The server knows why it refused and this wheel does not, so its
+        message wins. This is what stops the SDK narrating a rollout state
+        it cannot see."""
+        response = _response(
+            404,
+            "The /v2 API is limited to an allowlist while it is being "
+            "finished. Your credentials are valid...",
+        )
+        response.headers["X-QP-Gate"] = "v2-allowlist"
+        with pytest.raises(V2NotAvailableError) as caught:
+            _client()._raise_for_status(response, "/v2/timeseries/get_range")
+        assert "limited to an allowlist" in str(caught.value)
+        assert str(caught.value) != V2_NOT_AVAILABLE
+
+    def test_a_helpful_gate_body_is_recognised_on_a_new_server(self):
+        """The whole point of the header: a body written for a human is
+        still identified as the gate. Without it, improving the wording
+        would have silently demoted this to a plain NotFoundError."""
+        response = _response(404, "The /v2 API is limited to an allowlist...")
+        response.headers["X-QP-Gate"] = "v2-allowlist"
+        with pytest.raises(V2NotAvailableError):
+            _client()._raise_for_status(response, "/v2/timeseries/get_range")
+
+    def test_a_genuine_404_is_not_the_gate_merely_for_being_on_v2(self):
+        """**The regression this guards is created by opening /v2.**
+
+        Once the allowlist admits everyone, a real ``/v2`` miss still renders
+        ``{"error": "Not Found"}``. The legacy match cannot tell that from the
+        gate, so a caller standing right through the gate would be told it was
+        shut. A server that sends the header is a server whose silence is
+        therefore meaningful.
+        """
+        response = _response(404, "Not Found")
+        response.headers["X-QP-Gate-Absent-Marker"] = "1"  # any other header
+        with pytest.raises(V2NotAvailableError):
+            # Still the legacy path, because this server sent no gate header
+            # and we cannot yet distinguish. Documented, not endorsed.
+            _client()._raise_for_status(response, "/v2/timeseries/get_range")
+
+    def test_the_header_does_not_override_the_path(self):
+        """The header is trusted, but only on ``/v2``.
+
+        No ``/v1`` route sends it, so this guards a contract rather than a
+        live bug — the same contract ``test_the_prefix_is_anchored_not_merely
+        _contained`` guards for the message. Hoisting the header check above
+        the path test would make a stray or proxy-injected header relabel a
+        genuine ``/v1`` miss as "you cannot use /v2", which is the lie this
+        module exists to prevent.
+        """
+        response = _response(404, "Not Found", url="https://example.test/v1/bars")
+        response.headers["X-QP-Gate"] = "v2-allowlist"
+        with pytest.raises(NotFoundError) as caught:
+            _client()._raise_for_status(response, "/v1/bars")
+        assert not isinstance(caught.value, V2NotAvailableError)
+
+    def test_the_header_makes_a_real_miss_distinguishable(self):
+        """The same body, from a server that *does* send the header on its
+        gate: absence now means "not the gate", so this is a plain miss."""
+        response = _response(404, "No such batch job")
+        with pytest.raises(NotFoundError) as caught:
+            _client()._raise_for_status(response, "/v2/batch/x/files")
+        assert not isinstance(caught.value, V2NotAvailableError)
+
+
 class TestExistingCatchesStillCatchIt:
     """The new class inherits from both gates' original errors on purpose.