krx-openapi 0.1.0__py3-none-any.whl

krx_openapi/client.py

@@ -0,0 +1,238 @@
+"""KRX -- the entry point.
+
+Built from an API key (constructor, ``KRX_API_KEY`` env, or config file), it holds a
+:class:`KRXSession` and wires the seven category sub-surfaces -- ``index``,
+``stock``, ``etp``, ``bond``, ``derivatives``, ``commodity``, ``esg`` -- whose methods
+mirror the KRX service list one-to-one. Each method takes ``date`` (the
+``YYYYMMDD`` trade date) and returns ``list[dict[str, str]]``, the vendor's rows with
+their own field names.
+"""
+
+from __future__ import annotations
+
+import inspect
+
+from ._endpoint import ENDPOINTS
+from .session import KRXSession
+from .types import Market, Row, StockDerivMarket
+
+_STOCK_TRD = {"KOSPI": "stk_bydd_trd", "KOSDAQ": "ksq_bydd_trd", "KONEX": "knx_bydd_trd"}
+_STOCK_INFO = {
+    "KOSPI": "stk_isu_base_info", "KOSDAQ": "ksq_isu_base_info", "KONEX": "knx_isu_base_info",
+}
+_STOCK_FUTURES = {"KOSPI": "eqsfu_stk_bydd_trd", "KOSDAQ": "eqkfu_ksq_bydd_trd"}
+_STOCK_OPTIONS = {"KOSPI": "eqsop_bydd_trd", "KOSDAQ": "eqkop_bydd_trd"}
+
+
+def _pick(mapping: dict[str, str], market: str) -> str:
+    """Resolve a ``market`` against ``mapping``, case-insensitively, with a clear
+    ``ValueError`` for an unknown code (a caller mistake, not a runtime failure).
+
+    ``market`` is upper-cased first, so ``"kospi"`` and ``"KOSPI"`` both resolve;
+    the type hint keeps the canonical upper-case form (:data:`Market`)."""
+    try:
+        return mapping[market.upper()]
+    except (KeyError, AttributeError):
+        raise ValueError(f"market must be one of {list(mapping)}, got {market!r}") from None
+
+
+class _Surface:
+    """Base for a category sub-surface: holds the session and fetches by api_id."""
+
+    def __init__(self, session: KRXSession) -> None:
+        self._session = session
+
+    def _fetch(self, api_id: str, **params: str) -> list[Row]:
+        return self._session.fetch(ENDPOINTS[api_id], **params)
+
+
+class _Index(_Surface):
+    """지수 (idx) -- daily index series."""
+
+    def krx(self, date: str) -> list[Row]:
+        """KRX 시리즈 일별시세정보 (idx/krx_dd_trd)."""
+        return self._fetch("krx_dd_trd", basDd=date)
+
+    def kospi(self, date: str) -> list[Row]:
+        """KOSPI 시리즈 일별시세정보 (idx/kospi_dd_trd)."""
+        return self._fetch("kospi_dd_trd", basDd=date)
+
+    def kosdaq(self, date: str) -> list[Row]:
+        """KOSDAQ 시리즈 일별시세정보 (idx/kosdaq_dd_trd)."""
+        return self._fetch("kosdaq_dd_trd", basDd=date)
+
+    def bond(self, date: str) -> list[Row]:
+        """채권지수 시세정보 (idx/bon_dd_trd)."""
+        return self._fetch("bon_dd_trd", basDd=date)
+
+    def derivatives(self, date: str) -> list[Row]:
+        """파생상품지수 시세정보 (idx/drvprod_dd_trd)."""
+        return self._fetch("drvprod_dd_trd", basDd=date)
+
+
+class _Stock(_Surface):
+    """주식 (sto) -- daily trades and the issue master."""
+
+    def info(self, date: str, market: Market = "KOSPI") -> list[Row]:
+        """종목기본정보 (sto/{stk|ksq|knx}_isu_base_info). The issue master:
+        ISU_CD/ISU_SRT_CD/ISU_NM, LIST_DD, MKT_TP_NM, SECUGRP_NM, SECT_TP_NM, PARVAL,
+        LIST_SHRS. market KOSPI/KOSDAQ/KONEX."""
+        return self._fetch(_pick(_STOCK_INFO, market), basDd=date)
+
+    def daily(self, date: str, market: Market = "KOSPI") -> list[Row]:
+        """일별매매정보 (sto/{stk|ksq|knx}_bydd_trd). market: KOSPI 유가증권,
+        KOSDAQ 코스닥, KONEX 코넥스."""
+        return self._fetch(_pick(_STOCK_TRD, market), basDd=date)
+
+    def warrant(self, date: str) -> list[Row]:
+        """신주인수권증권 일별매매정보 (sto/sw_bydd_trd)."""
+        return self._fetch("sw_bydd_trd", basDd=date)
+
+    def right(self, date: str) -> list[Row]:
+        """신주인수권증서 일별매매정보 (sto/sr_bydd_trd)."""
+        return self._fetch("sr_bydd_trd", basDd=date)
+
+
+class _Etp(_Surface):
+    """증권상품 (etp) -- ETF / ETN / ELW daily trades."""
+
+    def etf(self, date: str) -> list[Row]:
+        """ETF 일별매매정보 (etp/etf_bydd_trd). Carries each ETF's base-index name
+        (IDX_IND_NM) and NAV alongside price."""
+        return self._fetch("etf_bydd_trd", basDd=date)
+
+    def etn(self, date: str) -> list[Row]:
+        """ETN 일별매매정보 (etp/etn_bydd_trd)."""
+        return self._fetch("etn_bydd_trd", basDd=date)
+
+    def elw(self, date: str) -> list[Row]:
+        """ELW 일별매매정보 (etp/elw_bydd_trd)."""
+        return self._fetch("elw_bydd_trd", basDd=date)
+
+
+class _Bond(_Surface):
+    """채권 (bon) -- daily bond trades (price + yield pairs)."""
+
+    def treasury(self, date: str) -> list[Row]:
+        """국채전문유통시장 일별매매정보 (bon/kts_bydd_trd)."""
+        return self._fetch("kts_bydd_trd", basDd=date)
+
+    def general(self, date: str) -> list[Row]:
+        """일반채권시장 일별매매정보 (bon/bnd_bydd_trd)."""
+        return self._fetch("bnd_bydd_trd", basDd=date)
+
+    def small_lot(self, date: str) -> list[Row]:
+        """소액채권시장 일별매매정보 (bon/smb_bydd_trd)."""
+        return self._fetch("smb_bydd_trd", basDd=date)
+
+
+class _Derivatives(_Surface):
+    """파생상품 (drv) -- futures and options daily trades."""
+
+    def futures(self, date: str) -> list[Row]:
+        """선물 일별매매정보, 주식선물 제외 (drv/fut_bydd_trd)."""
+        return self._fetch("fut_bydd_trd", basDd=date)
+
+    def options(self, date: str) -> list[Row]:
+        """옵션 일별매매정보, 주식옵션 제외 (drv/opt_bydd_trd). Large response (every
+        listed series) -- can take tens of seconds."""
+        return self._fetch("opt_bydd_trd", basDd=date)
+
+    def stock_futures(self, date: str, market: StockDerivMarket = "KOSPI") -> list[Row]:
+        """주식선물 일별매매정보 (drv/eqsfu_stk_bydd_trd 유가, eqkfu_ksq_bydd_trd
+        코스닥). market KOSPI/KOSDAQ (KONEX has no stock futures)."""
+        return self._fetch(_pick(_STOCK_FUTURES, market), basDd=date)
+
+    def stock_options(self, date: str, market: StockDerivMarket = "KOSPI") -> list[Row]:
+        """주식옵션 일별매매정보 (drv/eqsop_bydd_trd 유가, eqkop_bydd_trd 코스닥).
+        market KOSPI/KOSDAQ (KONEX has no stock options)."""
+        return self._fetch(_pick(_STOCK_OPTIONS, market), basDd=date)
+
+
+class _Commodity(_Surface):
+    """일반상품 (gen) -- oil, gold, emissions daily trades."""
+
+    def oil(self, date: str) -> list[Row]:
+        """석유시장 일별매매정보 (gen/oil_bydd_trd)."""
+        return self._fetch("oil_bydd_trd", basDd=date)
+
+    def gold(self, date: str) -> list[Row]:
+        """금시장 일별매매정보 (gen/gold_bydd_trd)."""
+        return self._fetch("gold_bydd_trd", basDd=date)
+
+    def emissions(self, date: str) -> list[Row]:
+        """배출권 시장 일별매매정보 (gen/ets_bydd_trd)."""
+        return self._fetch("ets_bydd_trd", basDd=date)
+
+
+class _Esg(_Surface):
+    """ESG (esg)."""
+
+    def sri_bond(self, date: str) -> list[Row]:
+        """사회책임투자채권 정보 (esg/sri_bond_info)."""
+        return self._fetch("sri_bond_info", basDd=date)
+
+    def index(self, date: str) -> list[Row]:
+        """ESG 지수 (esg/esg_index_info)."""
+        return self._fetch("esg_index_info", basDd=date)
+
+    def etp(self, date: str) -> list[Row]:
+        """ESG 증권상품 (esg/esg_etp_info)."""
+        return self._fetch("esg_etp_info", basDd=date)
+
+
+# The category sub-surfaces by accessor name. One source of truth: KRX builds one of
+# each here, and _accepts_market introspects the same classes -- so the CLI can answer
+# "does this method take --market?" offline (no key) without duplicating the fact.
+_SURFACES: dict[str, type[_Surface]] = {
+    "index": _Index,              # 지수 (idx)
+    "stock": _Stock,              # 주식 (sto)
+    "etp": _Etp,                  # 증권상품 (etp)
+    "bond": _Bond,                # 채권 (bon)
+    "derivatives": _Derivatives,  # 파생상품 (drv)
+    "commodity": _Commodity,      # 일반상품 (gen)
+    "esg": _Esg,                  # ESG (esg)
+}
+
+
+def _accepts_market(group: str, method: str) -> bool:
+    """Whether an accessor ``group.method`` takes a ``market`` argument.
+
+    Read from the accessor method's own signature, so it cannot drift from the
+    method definition. Lets the CLI reject a stray ``--market`` as a usage error
+    before it constructs a client (which would need an API key)."""
+    func = getattr(_SURFACES[group], method)
+    return "market" in inspect.signature(func).parameters
+
+
+class KRX:
+    """Client for the KRX Open API. Groups services as sub-surfaces.
+
+    Construct it with an API key, or leave it out to resolve one from the
+    ``KRX_API_KEY`` environment variable or ``~/.config/krx-openapi/credentials.json``::
+
+        krx = KRX()
+        rows = krx.index.kospi("20200414")
+        stocks = krx.stock.daily("20200414", market="KOSPI")
+
+    Each service is authorized separately on the KRX account; a call to one not
+    applied for raises :class:`KRXAuthError` (respCode 401). Rows come back as
+    ``list[dict[str, str]]`` -- frame them with ``pandas.DataFrame(rows)`` /
+    ``polars.DataFrame(rows)``.
+    """
+
+    index: _Index
+    stock: _Stock
+    etp: _Etp
+    bond: _Bond
+    derivatives: _Derivatives
+    commodity: _Commodity
+    esg: _Esg
+
+    def __init__(self, api_key: str | None = None, *, timeout: float = 60.0) -> None:
+        self._session = KRXSession(api_key, timeout=timeout)
+        for name, surface_cls in _SURFACES.items():
+            setattr(self, name, surface_cls(self._session))
+
+    def __repr__(self) -> str:
+        return f"KRX({self._session!r})"

krx_openapi/errors.py

@@ -0,0 +1,86 @@
+"""Exception hierarchy for krx-openapi.
+
+Every *operational* error this package raises derives from :class:`KRXError`, so one
+``except KRXError`` catches them all. The subclasses separate the failure modes a
+caller handles differently: a misconfiguration caught before any request
+(:class:`KRXConfigError`), a rejected or un-applied service key
+(:class:`KRXAuthError`), a daily-quota exhaustion (:class:`KRXRateLimitError`), any
+other vendor-reported error inside a well-formed response
+(:class:`KRXResponseError`), and a transport failure that never produced a KRX body
+(:class:`KRXNetworkError`). Invalid *caller input* -- an unknown ``market`` code raises
+``ValueError``, an unknown accessor ``group``/``method`` raises ``KeyError`` -- the
+usual signal for a caller mistake rather than a runtime failure.
+
+KRX answers every request with HTTP 200 and marks failure with a non-empty
+``respCode`` in the JSON body; :func:`_error_for` turns that code into the right
+subclass.
+"""
+
+from __future__ import annotations
+
+
+class KRXError(RuntimeError):
+    """Base class for every operational error raised by krx-openapi."""
+
+
+class KRXConfigError(KRXError):
+    """The client is misconfigured; raised before any request goes out.
+
+    The usual cause is a missing API key -- neither passed to ``KRX(...)`` nor
+    present in the ``KRX_API_KEY`` environment variable nor the config file.
+    """
+
+
+class KRXNetworkError(KRXError):
+    """The request failed at the transport or HTTP layer.
+
+    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__``.
+    """
+
+
+class KRXRateLimitError(KRXError):
+    """The daily call quota was exceeded (HTTP 429).
+
+    KRX limits each *auth key* (not IP) to 10,000 calls per day, reset at midnight.
+    It is its own class -- not a :class:`KRXNetworkError` -- so a bulk caller can
+    catch it distinctly and stop until the quota resets rather than retry.
+    """
+
+
+class KRXResponseError(KRXError):
+    """KRX returned a well-formed response carrying an error ``respCode``.
+
+    ``code`` and ``message`` are the vendor's own (``respCode`` / ``respMsg``), so a
+    caller can branch on the code without parsing the message text.
+    """
+
+    def __init__(self, code: str, message: str) -> None:
+        self.code = code
+        self.message = message
+        super().__init__(f"KRX {code}: {message}")
+
+
+class KRXAuthError(KRXResponseError):
+    """KRX rejected the key, or the service was not applied for (respCode 401).
+
+    Each KRX service (지수, 주식, ...) is authorized separately on the account; a
+    request for an un-applied service returns 401 exactly as a bad key does. It
+    subclasses :class:`KRXResponseError`, so ``except KRXResponseError`` still
+    catches it while a caller can catch an auth failure distinctly.
+    """
+
+    def __init__(self, message: str) -> None:
+        super().__init__("401", message)
+
+
+def _error_for(code: str, message: str) -> KRXResponseError:
+    """Build the most specific :class:`KRXResponseError` for a KRX ``respCode``.
+
+    A rate limit (429) arrives as an HTTP status, not a ``respCode`` -- handled in
+    the session -- so it is not mapped here; this only covers the in-body codes.
+    """
+    if code == "401":
+        return KRXAuthError(message or "KRX rejected the key or the service is not applied for")
+    return KRXResponseError(code, message)

krx_openapi/session.py

@@ -0,0 +1,160 @@
+"""KRXSession -- key injection, one GET over the standard library, the status contract.
+
+The session holds the API key and turns an endpoint + params into rows: a
+``list[dict[str, str]]``, the vendor's ``OutBlock_*`` array passed through with its
+own field names. No third-party HTTP client -- ``urllib`` carries it, so the package
+has zero runtime dependencies.
+
+KRX answers with HTTP 200 even on failure and marks the failure with a non-empty
+``respCode`` (+ ``respMsg``) in the JSON body; :meth:`fetch` applies that contract,
+raising the typed error and otherwise returning the single array the body carries.
+"""
+
+from __future__ import annotations
+
+import http.client
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+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 .types import Row
+
+_AUTH_HEADER = "AUTH_KEY"
+_USER_AGENT = "krx-openapi"
+
+# KRX limits each auth key to 10,000 calls/day; over it, the request returns 429.
+_RATE_LIMIT_STATUS = 429
+# A wrong key/URL, the sample path with a real key, or http:// all return 403.
+_FORBIDDEN_STATUS = 403
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """Refuse every redirect instead of following it.
+
+    ``urllib`` follows a 3xx automatically and copies the request headers -- the
+    ``AUTH_KEY`` among them -- onto the new location, so a redirect (in particular an
+    https -> http downgrade) would hand the API key to another host, in cleartext on
+    the downgrade. Refusing turns any redirect into an ``HTTPError``, which
+    :meth:`KRXSession._get` already surfaces as :class:`KRXNetworkError`; the key
+    never leaves the original https host.
+    """
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[no-untyped-def]
+        # The redirect target (newurl) is server-controlled -- keep it out of the error
+        # so nothing it carries can surface through the chained exception.
+        raise urllib.error.HTTPError(req.full_url, code, "redirect refused", headers, fp)
+
+
+# One opener for the whole package: the default global opener follows redirects, so
+# a private opener with the no-redirect handler is what actually closes the leak.
+_OPENER = urllib.request.build_opener(_NoRedirect)
+
+
+class KRXSession:
+    """Holds the API key and fetches endpoints as raw rows.
+
+    The key comes from ``api_key``, then ``$KRX_API_KEY``, then the config file
+    ``~/.config/krx-openapi/credentials.json``; construction raises
+    :class:`KRXConfigError` when none of them supplies one.
+    """
+
+    def __init__(self, api_key: str | None = None, *, timeout: float = 60.0) -> None:
+        self.api_key = resolve_api_key(api_key)
+        self.timeout = timeout
+
+    def __repr__(self) -> str:
+        # Never shows the API key, in whole or in part.
+        return "KRXSession(...)"
+
+    def fetch(self, endpoint: KRXEndpoint, **params: str) -> list[Row]:
+        """Fetch one service and return its ``OutBlock_*`` rows.
+
+        ``params`` are the query arguments the endpoint takes -- for the daily
+        endpoints, ``basDd="YYYYMMDD"``. A non-empty ``respCode`` raises the matching
+        :class:`KRXResponseError` (``401`` -> :class:`KRXAuthError`); HTTP 429 raises
+        :class:`KRXRateLimitError`; a transport or non-JSON failure raises
+        :class:`KRXNetworkError`; an empty ``OutBlock_*`` (a no-data date) returns ``[]``.
+        """
+        return self._get(endpoint.url, self.api_key, params)
+
+    @classmethod
+    def fetch_sample(cls, endpoint: KRXEndpoint, *, timeout: float = 60.0) -> list[Row]:
+        """Fetch an endpoint's keyless sample (fixed :data:`SAMPLE_DATE`).
+
+        A classmethod: it builds its own session from the public sample key, so it
+        needs no configured ``KRX_API_KEY`` at all. Hits the ``/svc/sample/apis``
+        twin, never a real service.
+        """
+        session = cls(SAMPLE_KEY, timeout=timeout)
+        return session._get(endpoint.sample_url, SAMPLE_KEY, {"basDd": SAMPLE_DATE})
+
+    def _get(self, url: str, api_key: str, params: dict[str, str]) -> list[Row]:
+        query = urllib.parse.urlencode({k: v for k, v in params.items() if v is not None})
+        full_url = f"{url}?{query}" if query else url
+        request = urllib.request.Request(
+            full_url, headers={_AUTH_HEADER: api_key.strip(), "User-Agent": _USER_AGENT}
+        )
+        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(
+                        "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
+        except urllib.error.URLError as err:
+            raise KRXNetworkError(f"request to KRX failed: {err.reason}") from err
+        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)
+
+
+def _rows_from_body(raw: bytes, url: 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).
+    """
+    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:
+        # 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
+    if not isinstance(body, dict):
+        raise KRXNetworkError(f"unexpected KRX response for {url}: {body!r}")
+
+    code = body.get("respCode")
+    if code:  # present only on failure
+        raise _error_for(str(code), str(body.get("respMsg", "")))
+
+    blocks = [
+        value for key, value in body.items()
+        if key.startswith("OutBlock_") and isinstance(value, list)
+    ]
+    if len(blocks) != 1:
+        # Success must carry exactly one OutBlock_* array; zero or several is a shape
+        # this contract does not recognize (not a silent empty result).
+        raise KRXNetworkError(
+            f"expected exactly one OutBlock_* array from KRX for {url}, got {len(blocks)}")
+    rows = blocks[0]
+    if not all(isinstance(row, dict) for row in rows):
+        raise KRXNetworkError(f"a non-object row in KRX OutBlock for {url}")
+    return rows

krx_openapi/types.py

@@ -0,0 +1,28 @@
+"""Shared type aliases for krx-openapi.
+
+KRX returns every field as a string (numbers included, a missing value as ``""``),
+so a row is a plain ``dict[str, str]`` -- ``Row``. The client passes rows through
+untouched, which is why there is no per-endpoint ``TypedDict`` here: the field set
+is the vendor's, documented in :mod:`krx_openapi.catalog`, and a caller frames a
+list of rows into a table in one line (``pandas.DataFrame(rows)`` /
+``polars.DataFrame(rows)``) and coerces the columns they need.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+Row = dict[str, str]
+
+# The three cash-equity markets, by their common names. The client maps these to
+# KRX's internal segment codes (KOSPI->stk, KOSDAQ->ksq, KONEX->knx) when picking
+# the endpoint; the name never goes on the wire.
+Market = Literal["KOSPI", "KOSDAQ", "KONEX"]
+
+# The subset that has stock futures/options: KRX lists these only for the KOSPI and
+# KOSDAQ markets, never KONEX. A narrower type than Market so an unsupported KONEX is
+# rejected by the type checker, not only at runtime.
+StockDerivMarket = Literal["KOSPI", "KOSDAQ"]
+
+# The seven service path codes under /svc/apis/<Category>/<api_id>.
+Category = Literal["idx", "sto", "etp", "bon", "drv", "gen", "esg"]