krx-openapi 0.2.0__tar.gz → 0.2.2__tar.gz

{krx_openapi-0.2.0 → krx_openapi-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: krx-openapi
-Version: 0.2.0
+Version: 0.2.2
 Summary: Read the Korea Exchange (KRX) Open API: indices, stocks, ETP, bonds, derivatives, commodities, ESG.
 Project-URL: Homepage, https://github.com/seokhoonj/krx-openapi
 Project-URL: Repository, https://github.com/seokhoonj/krx-openapi

{krx_openapi-0.2.0 → krx_openapi-0.2.2}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "krx-openapi"
-version = "0.2.0"
+version = "0.2.2"
 description = "Read the Korea Exchange (KRX) Open API: indices, stocks, ETP, bonds, derivatives, commodities, ESG."
 readme = "README.md"
 requires-python = ">=3.11"

{krx_openapi-0.2.0 → krx_openapi-0.2.2}/src/krx_openapi/errors.py

@@ -36,7 +36,9 @@ class KRXNetworkError(KRXError):
 
     A timeout, DNS failure, connection reset, an interrupted read, a non-success HTTP
     status, or a 200 whose body is not JSON (a proxy/maintenance page). The underlying
-    exception is chained as ``__cause__``.
+    transport/decode exception is deliberately NOT chained: it can hold the request URL
+    or the response body, so surfacing it on ``__cause__``/``__context__`` would expose
+    them to a logger that walks the chain.
     """
 
 

{krx_openapi-0.2.0 → krx_openapi-0.2.2}/src/krx_openapi/session.py

@@ -21,7 +21,7 @@ from typing import Any
 
 from ._config import resolve_api_key
 from ._endpoint import SAMPLE_DATE, SAMPLE_KEY, KRXEndpoint
-from .errors import KRXNetworkError, KRXRateLimitError, _error_for
+from .errors import KRXError, KRXNetworkError, KRXRateLimitError, _error_for
 from .types import Row
 
 _AUTH_HEADER = "AUTH_KEY"
@@ -99,51 +99,92 @@ class KRXSession:
         request = urllib.request.Request(
             full_url, headers={_AUTH_HEADER: api_key.strip(), "User-Agent": _USER_AGENT}
         )
+        # The key rides in the AUTH_KEY header, not the URL, so `url` is safe to name.
+        # Still, every failure is BUILT inside the except and RAISED after it
+        # (`from None`), so no transport exception is chained -- a reflecting server that
+        # echoed the request header into a response body could otherwise reach the key
+        # through, e.g., an IncompleteRead's partial body on the cause chain.
+        failure: KRXError
         try:
             with _OPENER.open(request, timeout=self.timeout) as response:
                 raw = response.read()
         except urllib.error.HTTPError as err:
             with err:  # an HTTPError is an unclosed response; release its socket
                 if err.code == _RATE_LIMIT_STATUS:
-                    raise KRXRateLimitError(
+                    failure = KRXRateLimitError(
                         "KRX daily call quota exceeded (10,000/key/day); resets at "
-                        "midnight") from err
-                hint = ""
-                if err.code == _FORBIDDEN_STATUS:
-                    hint = (" -- check the key, that the URL is https and /svc/apis "
-                            "(not /svc/sample/apis with a real key)")
-                raise KRXNetworkError(f"HTTP {err.code} from KRX for {url}{hint}") from err
+                        "midnight")
+                else:
+                    hint = ""
+                    if err.code == _FORBIDDEN_STATUS:
+                        hint = (" -- check the key, that the URL is https and /svc/apis "
+                                "(not /svc/sample/apis with a real key)")
+                    failure = KRXNetworkError(f"HTTP {err.code} from KRX for {url}{hint}")
         except urllib.error.URLError as err:
-            raise KRXNetworkError(f"request to KRX failed: {err.reason}") from err
+            # A transport reason is external text; keep only its type, then detach below.
+            failure = KRXNetworkError(
+                f"request to KRX failed for {url}: {type(err.reason).__name__}")
         except (http.client.HTTPException, OSError) as err:
             # A failure during response.read() (IncompleteRead, a socket timeout or
-            # reset) is not an HTTPError/URLError; surface it through KRXError too.
-            raise KRXNetworkError(f"KRX response read failed for {url}: {err}") from err
-        return _rows_from_body(raw, url)
+            # reset) is not an HTTPError/URLError; surface it through KRXError too. Name
+            # only the exception type -- str(err) can hold partially-read body bytes.
+            failure = KRXNetworkError(
+                f"KRX response read failed for {url}: {type(err).__name__}")
+        else:
+            return _rows_from_body(raw, url, api_key)
+        raise failure from None
+
+
+def _redact_key(text: str, api_key: str) -> str:
+    """Blank the API key out of server-authored text (a vendor message, or a body a
+    reflecting server echoed the ``AUTH_KEY`` header into).
+
+    krx carries the key in the request header, not the URL, so this is defense-in-depth:
+    a server that reflected the header into a response field would otherwise surface it in
+    an error message. Blank the raw and url-encoded forms of the value actually sent
+    (``api_key.strip()``). (An empty key would splice ``<key>`` between every character.)
+    """
+    key = api_key.strip()
+    if not key:
+        return text
+    return text.replace(key, "<key>").replace(urllib.parse.quote_plus(key), "<key>")
 
 
-def _rows_from_body(raw: bytes, url: str) -> list[Row]:
+def _rows_from_body(raw: bytes, url: str, api_key: str) -> list[Row]:
     """Apply the KRX status contract to a raw response body.
 
-    A pure function of the bytes: parses JSON, raises on a non-empty ``respCode`` or a
-    non-JSON body, and returns the single ``OutBlock_*`` array (``[]`` when the vendor
-    sends an empty one for a no-data date).
+    Parses JSON, raises on a non-empty ``respCode`` or a non-JSON body, and returns the
+    single ``OutBlock_*`` array (``[]`` when the vendor sends an empty one for a no-data
+    date). ``api_key`` is used only to redact it from an error message, in case a server
+    echoes the request header into the body.
     """
+    failure: KRXError | None = None
     try:
         # Decode as UTF-8 explicitly: json.loads(bytes) auto-detects UTF-16/32, which
         # would let a non-UTF-8 body slip through the "must be UTF-8 JSON" contract.
         body: Any = json.loads(raw.decode("utf-8"))
-    except (json.JSONDecodeError, UnicodeDecodeError, RecursionError) as err:
+    except (json.JSONDecodeError, UnicodeDecodeError, RecursionError):
         # A 200 whose body is not JSON / not UTF-8 (a proxy or maintenance HTML page), or
         # is nested deep enough to blow the parser's recursion limit, must surface through
-        # KRXError, not as a raw decode/recursion error.
-        raise KRXNetworkError(f"non-JSON response from KRX for {url}") from err
+        # KRXError. Built here but raised OUTSIDE the except (`from None` below): the decode
+        # error's .doc/.object is the whole body -- which a reflecting server could make
+        # echo the AUTH_KEY header -- so it must not ride __cause__/__context__.
+        failure = KRXNetworkError(f"non-JSON response from KRX for {url}")
+    if failure is not None:
+        raise failure from None
+
     if not isinstance(body, dict):
-        raise KRXNetworkError(f"unexpected KRX response for {url}: {body!r}")
+        # Name only the shape -- body is server-authored and could echo the header key.
+        raise KRXNetworkError(
+            f"unexpected KRX response for {url}: expected a JSON object, "
+            f"got {type(body).__name__}")
 
     code = body.get("respCode")
     if code:  # present only on failure
-        raise _error_for(str(code), str(body.get("respMsg", "")))
+        # respCode/respMsg are server-authored; redact in case they echo the header key.
+        raise _error_for(
+            _redact_key(str(code), api_key),
+            _redact_key(str(body.get("respMsg", "")), api_key))
 
     blocks = [
         value for key, value in body.items()

{krx_openapi-0.2.0 → krx_openapi-0.2.2}/tests/test_session.py

@@ -31,69 +31,69 @@ def _body(payload):
 def test_extracts_the_outblock_array():
     rows = _rows_from_body(
         _body({"OutBlock_1": [{"BAS_DD": "20200414"}, {"BAS_DD": "20200414"}]}),
-        "http://x")
+        "http://x", "")
     assert rows == [{"BAS_DD": "20200414"}, {"BAS_DD": "20200414"}]
 
 
 def test_empty_outblock_is_empty_list():
     # a no-data date: KRX still returns the OutBlock, just empty
-    assert _rows_from_body(_body({"OutBlock_1": []}), "http://x") == []
+    assert _rows_from_body(_body({"OutBlock_1": []}), "http://x", "") == []
 
 
 def test_no_outblock_array_raises():
     with pytest.raises(KRXNetworkError):
-        _rows_from_body(_body({"other": "1"}), "http://x")
+        _rows_from_body(_body({"other": "1"}), "http://x", "")
 
 
 def test_multiple_outblock_arrays_raise():
     with pytest.raises(KRXNetworkError):
-        _rows_from_body(_body({"OutBlock_1": [], "OutBlock_2": []}), "http://x")
+        _rows_from_body(_body({"OutBlock_1": [], "OutBlock_2": []}), "http://x", "")
 
 
 def test_outblock_prefix_requires_the_underscore():
     # The block key must be OutBlock_<n>. A bare "OutBlock" is not a data array, so a
     # body carrying only that is no recognized block -> raises.
     with pytest.raises(KRXNetworkError):
-        _rows_from_body(_body({"OutBlock": []}), "http://x")
+        _rows_from_body(_body({"OutBlock": []}), "http://x", "")
     # A near-prefix like "OutBlockMeta" must be ignored, not mistaken for a second data
     # block: with the real OutBlock_1 present, exactly one block is found and returned.
     # (Under the looser startswith("OutBlock") this would be two blocks and would raise,
     # so this pins the underscore.)
-    rows = _rows_from_body(_body({"OutBlockMeta": [], "OutBlock_1": [{"a": "1"}]}), "http://x")
+    rows = _rows_from_body(_body({"OutBlockMeta": [], "OutBlock_1": [{"a": "1"}]}), "http://x", "")
     assert rows == [{"a": "1"}]
 
 
 def test_respcode_401_raises_auth_error():
     with pytest.raises(KRXAuthError):
-        _rows_from_body(_body({"respCode": "401", "respMsg": "not applied"}), "http://x")
+        _rows_from_body(_body({"respCode": "401", "respMsg": "not applied"}), "http://x", "")
 
 
 def test_respcode_other_raises_response_error():
     with pytest.raises(KRXResponseError):
-        _rows_from_body(_body({"respCode": "500", "respMsg": "boom"}), "http://x")
+        _rows_from_body(_body({"respCode": "500", "respMsg": "boom"}), "http://x", "")
 
 
 def test_non_json_raises_network_error():
     with pytest.raises(KRXNetworkError):
-        _rows_from_body(b"<html>maintenance</html>", "http://x")
+        _rows_from_body(b"<html>maintenance</html>", "http://x", "")
 
 
 def test_invalid_utf8_raises_network_error():
     # json.loads on non-UTF-8 bytes raises UnicodeDecodeError, not JSONDecodeError
     with pytest.raises(KRXNetworkError):
-        _rows_from_body(b"\xff\xfe not utf-8", "http://x")
+        _rows_from_body(b"\xff\xfe not utf-8", "http://x", "")
 
 
 def test_valid_utf16_json_raises_network_error():
     # Well-formed JSON, but UTF-16: json.loads(bytes) would auto-detect and accept it;
     # the contract is UTF-8 only, so decoding explicitly must reject it.
     with pytest.raises(KRXNetworkError):
-        _rows_from_body('{"OutBlock_1": []}'.encode("utf-16"), "http://x")
+        _rows_from_body('{"OutBlock_1": []}'.encode("utf-16"), "http://x", "")
 
 
 def test_non_object_json_raises_network_error():
     with pytest.raises(KRXNetworkError):
-        _rows_from_body(b"[1, 2, 3]", "http://x")
+        _rows_from_body(b"[1, 2, 3]", "http://x", "")
 
 
 def test_recursion_error_becomes_network_error(monkeypatch):
@@ -106,12 +106,12 @@ def test_recursion_error_becomes_network_error(monkeypatch):
 
     monkeypatch.setattr("krx_openapi.session.json.loads", boom)
     with pytest.raises(KRXNetworkError):
-        _rows_from_body(b'{"OutBlock_1": []}', "http://x")
+        _rows_from_body(b'{"OutBlock_1": []}', "http://x", "")
 
 
 def test_non_dict_row_raises():
     with pytest.raises(KRXNetworkError):
-        _rows_from_body(_body({"OutBlock_1": [{"a": "1"}, "junk"]}), "http://x")
+        _rows_from_body(_body({"OutBlock_1": [{"a": "1"}, "junk"]}), "http://x", "")
 
 
 # --- _get (offline opener fake) ---------------------------------------------
@@ -199,6 +199,68 @@ def test_get_read_failure_raises_network(monkeypatch):
         KRXSession(api_key="k").fetch(ENDPOINTS["kospi_dd_trd"], basDd="20200414")
 
 
+def test_read_failure_echoing_the_key_never_leaks_it(monkeypatch):
+    # A reflecting server could echo the AUTH_KEY header into the partial body of an
+    # interrupted read; the read-phase error must not surface it or chain the raw
+    # exception (whose partial body would carry it on the cause chain).
+    key = "SECRETKEY123"
+
+    class _EchoingRead(_FakeResponse):
+        def read(self) -> bytes:
+            raise http.client.IncompleteRead(f"partial Auth_key={key}".encode())
+
+    _patch_opener(monkeypatch, lambda request, timeout=None: _EchoingRead(b""))
+    with pytest.raises(KRXNetworkError) as exc:
+        KRXSession(api_key=key).fetch(ENDPOINTS["kospi_dd_trd"], basDd="20200414")
+    assert key not in str(exc.value)
+    assert exc.value.__context__ is None and exc.value.__cause__ is None
+
+
+# --- parse-path secret safety (the key must not ride the decode-error chain) --
+
+def _assert_no_key(exc, key):
+    seen, pending = set(), [exc]
+    while pending:
+        current = pending.pop()
+        if current is None or id(current) in seen:
+            continue
+        seen.add(id(current))
+        blob = str(current) + repr(current) + repr(current.args)
+        assert key not in blob
+        pending.extend([current.__cause__, current.__context__])
+
+
+def test_non_utf8_body_echoing_the_key_never_leaks_it():
+    # A reflecting server could echo the AUTH_KEY header into a non-UTF-8 200 body; the
+    # decode error (whose .object is the whole body) must not ride the raised error's
+    # chain. This is the sibling of the read-phase test, for the body-parse path.
+    key = "SECRETKEY123"
+    body = ("bad " + key).encode() + b"\xff"   # invalid UTF-8 tail, echoes the key
+    with pytest.raises(KRXNetworkError) as exc:
+        _rows_from_body(body, "http://x", key)
+    assert exc.value.__cause__ is None and exc.value.__context__ is None
+    _assert_no_key(exc.value, key)
+
+
+def test_non_dict_body_echoing_the_key_never_leaks_it():
+    # A non-dict JSON body is server-authored; the "unexpected response" error must name
+    # only the shape, never the body content (which could echo the header key).
+    key = "SECRETKEY123"
+    body = _body([f"{key} reflected"])          # a JSON list echoing the key
+    with pytest.raises(KRXNetworkError) as exc:
+        _rows_from_body(body, "http://x", key)
+    _assert_no_key(exc.value, key)
+
+
+def test_vendor_error_message_echoing_the_key_never_leaks_it():
+    # respCode/respMsg are server-authored; a message echoing the header key is redacted.
+    key = "SECRETKEY123"
+    body = _body({"respCode": "99", "respMsg": f"rejected {key}"})
+    with pytest.raises(KRXResponseError) as exc:
+        _rows_from_body(body, "http://x", key)
+    _assert_no_key(exc.value, key)
+
+
 # --- redirects must never carry the key -------------------------------------
 
 def test_no_redirect_handler_refuses_and_never_follows():
@@ -254,4 +316,6 @@ def test_error_message_never_shows_the_key(monkeypatch):
     with pytest.raises(KRXNetworkError) as exc:
         KRXSession(api_key="SECRETKEY123").fetch(ENDPOINTS["kospi_dd_trd"], basDd="20200414")
     assert "SECRETKEY123" not in str(exc.value)
-    assert "SECRETKEY123" not in str(exc.value.__cause__)
+    # The HTTPError branch also detaches: the key-bearing transport error must not ride
+    # the chain (str(__cause__) alone would pass even if it were chained, so assert None).
+    assert exc.value.__cause__ is None and exc.value.__context__ is None