krx-openapi 0.1.0__py3-none-any.whl

krx_openapi/__init__.py

@@ -0,0 +1,55 @@
+"""krx-openapi -- read daily market data from the KRX Open API.
+
+    from krx_openapi import KRX
+
+    krx = KRX()                              # or set KRX_API_KEY
+    rows = krx.index.kospi("20200414")       # KOSPI series, one day
+    stocks = krx.stock.daily("20200414", market="KOSPI")
+
+Reads the KRX Open API: indices, stocks and
+the issue master, ETF/ETN/ELW, bonds, futures/options, oil/gold/emissions, and ESG.
+Returns raw ``list[dict]`` with the vendor's own field names -- frame it your own
+way, e.g. ``pandas.DataFrame(rows)`` or ``polars.DataFrame(rows)``. The offline
+:mod:`krx_openapi.catalog` describes every service and its fields without a call.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from . import catalog
+from ._endpoint import ENDPOINTS, KRXEndpoint
+from .client import KRX
+from .errors import (
+    KRXAuthError,
+    KRXConfigError,
+    KRXError,
+    KRXNetworkError,
+    KRXRateLimitError,
+    KRXResponseError,
+)
+from .session import KRXSession
+from .types import Category, Market, Row, StockDerivMarket
+
+try:
+    __version__ = version("krx-openapi")   # single source of truth: pyproject.toml
+except PackageNotFoundError:               # running from source without an install
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "ENDPOINTS",
+    "KRX",
+    "Category",
+    "KRXAuthError",
+    "KRXConfigError",
+    "KRXEndpoint",
+    "KRXError",
+    "KRXNetworkError",
+    "KRXRateLimitError",
+    "KRXResponseError",
+    "KRXSession",
+    "Market",
+    "Row",
+    "StockDerivMarket",
+    "catalog",
+]

krx_openapi/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m krx_openapi`` -- same entry point as the ``krx`` command."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

krx_openapi/_config.py

@@ -0,0 +1,74 @@
+"""Resolve the KRX API key from the caller, the environment, or the config file.
+
+The key is looked up in a fixed order, so an explicit value always wins and a set
+environment variable beats a file on disk:
+
+1. the ``api_key`` passed to ``KRX(...)``
+2. the ``KRX_API_KEY`` environment variable
+3. ``"KRX_API_KEY"`` in ``$XDG_CONFIG_HOME/krx-openapi/credentials.json``
+   (``$XDG_CONFIG_HOME`` defaults to ``~/.config``)
+
+The file is optional -- its absence just means "no key here." But a file that is
+present and unreadable, not JSON, or not a JSON object is an error, because a caller
+who wrote one meant it to be used and a silent skip would hide the mistake.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from .errors import KRXConfigError
+
+_ENV_VAR = "KRX_API_KEY"
+_CONFIG_DIR = "krx-openapi"
+_CONFIG_FILE = "credentials.json"
+
+
+def resolve_api_key(explicit: str | None) -> str:
+    """Return the first key found across the three sources, or raise if none exists."""
+    key = (explicit or "").strip() or os.environ.get(_ENV_VAR, "").strip() or _key_from_file()
+    if not key:
+        raise KRXConfigError(
+            f"no KRX API key: pass api_key=, set the {_ENV_VAR} environment "
+            f"variable, or put it in {credentials_path()}"
+        )
+    if any(ord(ch) < 0x20 or ord(ch) == 0x7f for ch in key):
+        # A control character (a stray newline/tab, often from a copy-paste) would make
+        # an invalid HTTP header: urllib raises ValueError echoing the whole value -- the
+        # key. Reject it as a config error, before it becomes a request, and never echo it.
+        raise KRXConfigError(
+            "the KRX API key contains a control character (a stray newline or tab?)")
+    return key
+
+
+def credentials_path() -> Path:
+    """The path krx-openapi reads a stored key from (honoring ``$XDG_CONFIG_HOME``)."""
+    config_home = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(config_home) / _CONFIG_DIR / _CONFIG_FILE
+
+
+def _key_from_file() -> str:
+    path = credentials_path()
+    try:
+        text = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return ""
+    except UnicodeDecodeError as err:
+        # A present file that is not UTF-8 is "unreadable" in the same sense as an
+        # OSError: the caller wrote it meaning it to be used, so surface it, not a
+        # raw decode error. (UnicodeDecodeError is a ValueError, not an OSError.)
+        raise KRXConfigError(f"{path} is not valid UTF-8: {err}") from err
+    except OSError as err:
+        raise KRXConfigError(f"could not read {path}: {err}") from err
+
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as err:
+        raise KRXConfigError(f"{path} is not valid JSON: {err}") from err
+    if not isinstance(data, dict):
+        raise KRXConfigError(f"{path} must contain a JSON object")
+
+    key = data.get(_ENV_VAR)
+    return key.strip() if isinstance(key, str) else ""

krx_openapi/_endpoint.py

@@ -0,0 +1,98 @@
+"""The KRXEndpoint value object and the registry of every KRX Open API service.
+
+Each endpoint is data: its service path code (``category``), its ``api_id``, the
+name of its field schema (:mod:`krx_openapi.catalog`), its Korean title, and the
+earliest ``basDd`` for which KRX serves data. ``url`` and ``sample_url`` resolve
+from those -- the wire location lives in exactly one place.
+
+KRX also publishes a keyless *sample* twin of every endpoint: the same shape at a
+fixed sample date, reachable with a public sample key -- :attr:`KRXEndpoint.sample_url`,
+:data:`SAMPLE_KEY`, and :data:`SAMPLE_DATE` describe it.
+
+``ENDPOINTS`` is exposed read-only (a ``MappingProxyType``): it is package dispatch
+state that every category accessor reads, so a caller must not be able to mutate it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+
+from .types import Category
+
+BASE_URL = "https://data-dbg.krx.co.kr/svc/apis"
+SAMPLE_URL = "https://data-dbg.krx.co.kr/svc/sample/apis"
+
+# Published by KRX on its own API test page -- a public sample key, not a secret.
+# It reaches only the sample endpoints, which always answer for SAMPLE_DATE.
+SAMPLE_KEY = "74D1B99DFBF345BBA3FB4476510A4BED4C78D13A"
+SAMPLE_DATE = "20200414"
+
+
+@dataclass(frozen=True, slots=True)
+class KRXEndpoint:
+    """One KRX Open API service and where its data and spec live."""
+
+    category: Category       # service path code: idx, sto, etp, bon, drv, gen, esg
+    api_id: str              # e.g. "krx_dd_trd"
+    schema: str = ""         # field-schema name, keys into krx_openapi.catalog
+    name_ko: str = ""        # Korean title, e.g. "KRX 시리즈 일별시세정보"
+    start: str = ""          # earliest basDd with data, e.g. "2010-01-04"
+
+    @property
+    def url(self) -> str:
+        # .json makes the JSON format explicit (KRX's documented contract) and https
+        # avoids the http -> https 302 that would drop the AUTH_KEY header.
+        return f"{BASE_URL}/{self.category}/{self.api_id}.json"
+
+    @property
+    def sample_url(self) -> str:
+        return f"{SAMPLE_URL}/{self.category}/{self.api_id}.json"
+
+
+def _registry(*endpoints: KRXEndpoint) -> Mapping[str, KRXEndpoint]:
+    return MappingProxyType({endpoint.api_id: endpoint for endpoint in endpoints})
+
+
+# Every service, grouped by category. api_id -> KRXEndpoint. Read-only.
+ENDPOINTS: Mapping[str, KRXEndpoint] = _registry(
+    # -- 지수 (idx) --------------------------------------------------------
+    KRXEndpoint("idx", "krx_dd_trd",     "IDX_DAILY",   "KRX 시리즈 일별시세정보",    "2010-01-04"),
+    KRXEndpoint("idx", "kospi_dd_trd",   "IDX_DAILY",   "KOSPI 시리즈 일별시세정보",  "2010-01-04"),
+    KRXEndpoint("idx", "kosdaq_dd_trd",  "IDX_DAILY",   "KOSDAQ 시리즈 일별시세정보", "2010-01-04"),
+    KRXEndpoint("idx", "bon_dd_trd",     "BOND_IDX",    "채권지수 시세정보",          "2010-01-04"),
+    KRXEndpoint("idx", "drvprod_dd_trd", "DRVPROD_IDX", "파생상품지수 시세정보",      "2010-01-04"),
+    # -- 주식 (sto) --------------------------------------------------------
+    KRXEndpoint("sto", "stk_bydd_trd",      "STOCK_TRD",  "유가증권 일별매매정보",       "2010-01-04"),
+    KRXEndpoint("sto", "ksq_bydd_trd",      "STOCK_TRD",  "코스닥 일별매매정보",         "2010-01-04"),
+    KRXEndpoint("sto", "knx_bydd_trd",      "STOCK_TRD",  "코넥스 일별매매정보",         "2013-07-01"),
+    KRXEndpoint("sto", "sw_bydd_trd",       "WARRANT_SW", "신주인수권증권 일별매매정보", "2010-01-04"),
+    KRXEndpoint("sto", "sr_bydd_trd",       "WARRANT_SR", "신주인수권증서 일별매매정보", "2010-02-12"),
+    KRXEndpoint("sto", "stk_isu_base_info", "ISU_BASE",   "유가증권 종목기본정보",       "2010-01-04"),
+    KRXEndpoint("sto", "ksq_isu_base_info", "ISU_BASE",   "코스닥 종목기본정보",         "2010-01-04"),
+    KRXEndpoint("sto", "knx_isu_base_info", "ISU_BASE",   "코넥스 종목기본정보",         "2013-07-01"),
+    # -- 증권상품 (etp) ----------------------------------------------------
+    KRXEndpoint("etp", "etf_bydd_trd", "ETF_TRD", "ETF 일별매매정보", "2010-01-04"),
+    KRXEndpoint("etp", "etn_bydd_trd", "ETN_TRD", "ETN 일별매매정보", "2014-11-17"),
+    KRXEndpoint("etp", "elw_bydd_trd", "ELW_TRD", "ELW 일별매매정보", "2010-01-04"),
+    # -- 채권 (bon) --------------------------------------------------------
+    KRXEndpoint("bon", "kts_bydd_trd", "GOVBOND_TRD", "국채전문유통시장 일별매매정보", "2010-01-04"),
+    KRXEndpoint("bon", "bnd_bydd_trd", "BOND_TRD",    "일반채권시장 일별매매정보",     "2010-01-04"),
+    KRXEndpoint("bon", "smb_bydd_trd", "BOND_TRD",    "소액채권시장 일별매매정보",     "2010-01-04"),
+    # -- 파생상품 (drv) ----------------------------------------------------
+    KRXEndpoint("drv", "fut_bydd_trd",        "FUTURES_TRD", "선물 일별매매정보 (주식선물外)", "2010-01-04"),
+    KRXEndpoint("drv", "eqsfu_stk_bydd_trd",  "FUTURES_TRD", "주식선물(유가) 일별매매정보",    "2010-01-04"),
+    KRXEndpoint("drv", "eqkfu_ksq_bydd_trd",  "FUTURES_TRD", "주식선물(코스닥) 일별매매정보",  "2015-08-03"),
+    KRXEndpoint("drv", "opt_bydd_trd",        "OPTION_TRD",  "옵션 일별매매정보 (주식옵션外)", "2010-01-04"),
+    KRXEndpoint("drv", "eqsop_bydd_trd",      "OPTION_TRD",  "주식옵션(유가) 일별매매정보",    "2010-01-04"),
+    KRXEndpoint("drv", "eqkop_bydd_trd",      "OPTION_TRD",  "주식옵션(코스닥) 일별매매정보",  "2017-06-26"),
+    # -- 일반상품 (gen) ----------------------------------------------------
+    KRXEndpoint("gen", "oil_bydd_trd",  "OIL_TRD",      "석유시장 일별매매정보",   "2012-03-30"),
+    KRXEndpoint("gen", "gold_bydd_trd", "GOLD_ETS_TRD", "금시장 일별매매정보",     "2014-03-24"),
+    KRXEndpoint("gen", "ets_bydd_trd",  "GOLD_ETS_TRD", "배출권 시장 일별매매정보", "2015-01-12"),
+    # -- ESG (esg) ---------------------------------------------------------
+    KRXEndpoint("esg", "sri_bond_info",  "SRI_BOND", "사회책임투자채권 정보", "2019-01-01"),
+    KRXEndpoint("esg", "esg_index_info", "ESG_IDX",  "ESG 지수",              "2020-01-02"),
+    KRXEndpoint("esg", "esg_etp_info",   "ESG_ETP",  "ESG 증권상품",          "2020-01-02"),
+)

krx_openapi/catalog.py

@@ -0,0 +1,198 @@
+"""The offline catalog -- every service and its field schema, no network needed.
+
+The 31 endpoints share 19 distinct field schemas (the index-daily endpoints all
+carry the same twelve fields; the three stock-trade endpoints another fifteen; and
+so on). :data:`SCHEMAS` maps each schema name to its field tuple -- the vendor's own
+``OutBlock_*`` field names, in order -- so a caller can see what a call returns
+before making it. :func:`fields` turns a readable ``group name`` into the columns
+that service returns.
+
+``SCHEMAS`` is exposed read-only (a ``MappingProxyType`` of tuples): it is
+authoritative package state, so a caller must not be able to mutate it. Every value
+KRX returns is a string; these are the field *names*, not types.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+
+from ._endpoint import ENDPOINTS, KRXEndpoint
+
+# schema name -> its OutBlock field names, in the order KRX returns them.
+SCHEMAS: Mapping[str, tuple[str, ...]] = MappingProxyType({
+    "IDX_DAILY": (
+        "BAS_DD", "IDX_CLSS", "IDX_NM", "CLSPRC_IDX", "CMPPREVDD_IDX", "FLUC_RT",
+        "OPNPRC_IDX", "HGPRC_IDX", "LWPRC_IDX", "ACC_TRDVOL", "ACC_TRDVAL", "MKTCAP",
+    ),
+    "BOND_IDX": (
+        "BAS_DD", "BND_IDX_GRP_NM", "TOT_EARNG_IDX", "TOT_EARNG_IDX_CMPPREVDD",
+        "NETPRC_IDX", "NETPRC_IDX_CMPPREVDD", "ZERO_REINVST_IDX",
+        "ZERO_REINVST_IDX_CMPPREVDD", "CALL_REINVST_IDX", "CALL_REINVST_IDX_CMPPREVDD",
+        "MKT_PRC_IDX", "MKT_PRC_IDX_CMPPREVDD", "AVG_DURATION", "AVG_CONVEXITY_PRC",
+        "BND_IDX_AVG_YD",
+    ),
+    "DRVPROD_IDX": (
+        "BAS_DD", "IDX_CLSS", "IDX_NM", "CLSPRC_IDX", "CMPPREVDD_IDX", "FLUC_RT",
+        "OPNPRC_IDX", "HGPRC_IDX", "LWPRC_IDX",
+    ),
+    "STOCK_TRD": (
+        "BAS_DD", "ISU_CD", "ISU_NM", "MKT_NM", "SECT_TP_NM", "TDD_CLSPRC",
+        "CMPPREVDD_PRC", "FLUC_RT", "TDD_OPNPRC", "TDD_HGPRC", "TDD_LWPRC",
+        "ACC_TRDVOL", "ACC_TRDVAL", "MKTCAP", "LIST_SHRS",
+    ),
+    "WARRANT_SW": (
+        "BAS_DD", "MKT_NM", "ISU_CD", "ISU_NM", "TDD_CLSPRC", "CMPPREVDD_PRC",
+        "FLUC_RT", "TDD_OPNPRC", "TDD_HGPRC", "TDD_LWPRC", "ACC_TRDVOL", "ACC_TRDVAL",
+        "MKTCAP", "LIST_SHRS", "EXER_PRC", "EXST_STRT_DD", "EXST_END_DD",
+        "TARSTK_ISU_SRT_CD", "TARSTK_ISU_NM", "TARSTK_ISU_PRSNT_PRC",
+    ),
+    "WARRANT_SR": (
+        "BAS_DD", "MKT_NM", "ISU_CD", "ISU_NM", "TDD_CLSPRC", "CMPPREVDD_PRC",
+        "FLUC_RT", "TDD_OPNPRC", "TDD_HGPRC", "TDD_LWPRC", "ACC_TRDVOL", "ACC_TRDVAL",
+        "MKTCAP", "LIST_SHRS", "ISU_PRC", "DELIST_DD", "TARSTK_ISU_SRT_CD",
+        "TARSTK_ISU_NM", "TARSTK_ISU_PRSNT_PRC",
+    ),
+    "ISU_BASE": (
+        "ISU_CD", "ISU_SRT_CD", "ISU_NM", "ISU_ABBRV", "ISU_ENG_NM", "LIST_DD",
+        "MKT_TP_NM", "SECUGRP_NM", "SECT_TP_NM", "KIND_STKCERT_TP_NM", "PARVAL",
+        "LIST_SHRS",
+    ),
+    "ETF_TRD": (
+        "BAS_DD", "ISU_CD", "ISU_NM", "TDD_CLSPRC", "CMPPREVDD_PRC", "FLUC_RT", "NAV",
+        "TDD_OPNPRC", "TDD_HGPRC", "TDD_LWPRC", "ACC_TRDVOL", "ACC_TRDVAL", "MKTCAP",
+        "INVSTASST_NETASST_TOTAMT", "LIST_SHRS", "IDX_IND_NM", "OBJ_STKPRC_IDX",
+        "CMPPREVDD_IDX", "FLUC_RT_IDX",
+    ),
+    "ETN_TRD": (
+        "BAS_DD", "ISU_CD", "ISU_NM", "TDD_CLSPRC", "CMPPREVDD_PRC", "FLUC_RT",
+        "PER1SECU_INDIC_VAL", "TDD_OPNPRC", "TDD_HGPRC", "TDD_LWPRC", "ACC_TRDVOL",
+        "ACC_TRDVAL", "MKTCAP", "INDIC_VAL_AMT", "LIST_SHRS", "IDX_IND_NM",
+        "OBJ_STKPRC_IDX", "CMPPREVDD_IDX", "FLUC_RT_IDX",
+    ),
+    "ELW_TRD": (
+        "BAS_DD", "ISU_CD", "ISU_NM", "TDD_CLSPRC", "CMPPREVDD_PRC", "TDD_OPNPRC",
+        "TDD_HGPRC", "TDD_LWPRC", "ACC_TRDVOL", "ACC_TRDVAL", "MKTCAP", "LIST_SHRS",
+        "ULY_NM", "ULY_PRC", "CMPPREVDD_PRC_ULY", "FLUC_RT_ULY",
+    ),
+    "GOVBOND_TRD": (
+        "BAS_DD", "MKT_NM", "ISU_CD", "ISU_NM", "BND_EXP_TP_NM", "GOVBND_ISU_TP_NM",
+        "CLSPRC", "CMPPREVDD_PRC", "CLSPRC_YD", "OPNPRC", "OPNPRC_YD", "HGPRC",
+        "HGPRC_YD", "LWPRC", "LWPRC_YD", "ACC_TRDVOL", "ACC_TRDVAL",
+    ),
+    "BOND_TRD": (
+        "BAS_DD", "MKT_NM", "ISU_CD", "ISU_NM", "CLSPRC", "CMPPREVDD_PRC", "CLSPRC_YD",
+        "OPNPRC", "OPNPRC_YD", "HGPRC", "HGPRC_YD", "LWPRC", "LWPRC_YD", "ACC_TRDVOL",
+        "ACC_TRDVAL",
+    ),
+    "FUTURES_TRD": (
+        "BAS_DD", "PROD_NM", "MKT_NM", "ISU_CD", "ISU_NM", "TDD_CLSPRC",
+        "CMPPREVDD_PRC", "TDD_OPNPRC", "TDD_HGPRC", "TDD_LWPRC", "SPOT_PRC", "SETL_PRC",
+        "ACC_TRDVOL", "ACC_TRDVAL", "ACC_OPNINT_QTY",
+    ),
+    "OPTION_TRD": (
+        "BAS_DD", "PROD_NM", "RGHT_TP_NM", "ISU_CD", "ISU_NM", "TDD_CLSPRC",
+        "CMPPREVDD_PRC", "TDD_OPNPRC", "TDD_HGPRC", "TDD_LWPRC", "IMP_VOLT",
+        "NXTDD_BAS_PRC", "ACC_TRDVOL", "ACC_TRDVAL", "ACC_OPNINT_QTY",
+    ),
+    "OIL_TRD": (
+        "BAS_DD", "OIL_NM", "WT_AVG_PRC", "WT_DIS_AVG_PRC", "ACC_TRDVOL", "ACC_TRDVAL",
+    ),
+    "GOLD_ETS_TRD": (
+        "BAS_DD", "ISU_CD", "ISU_NM", "TDD_CLSPRC", "CMPPREVDD_PRC", "FLUC_RT",
+        "TDD_OPNPRC", "TDD_HGPRC", "TDD_LWPRC", "ACC_TRDVOL", "ACC_TRDVAL",
+    ),
+    "ESG_ETP": (
+        "BAS_DD", "ISU_ABBRV", "TDD_CLSPRC", "CMPPREVDD_PRC", "FLUC_RT", "LIST_SHRS",
+        "ACC_TRDVOL", "ACC_TRDVAL",
+    ),
+    "SRI_BOND": (
+        "BAS_DD", "ISUR_NM", "ISU_CD", "SRI_BND_TP_NM", "ISU_NM", "LIST_DD", "ISU_DD",
+        "REDMPT_DD", "ISU_RT", "ISU_AMT", "LIST_AMT", "BND_TP_NM",
+    ),
+    "ESG_IDX": (
+        "BAS_DD", "IDX_NM", "CLSPRC_IDX", "PRV_DD_CMPR", "UPDN_RATE", "TRD_ISU_CNT",
+        "ACC_TRDVOL", "ACC_TRDVAL",
+    ),
+})
+
+
+# The KRX client's accessor tree as data: group -> [(method name, representative
+# api_id)]. It mirrors the KRX / _Surface accessors so the CLI can offer the same
+# readable names (`krx fetch index kospi`) instead of raw api_ids, and drive `list` /
+# `fields` offline. The api_id is only used to look up a field schema, and every
+# market variant of a method shares one schema, so a single representative suffices.
+ACCESSORS: Mapping[str, tuple[tuple[str, str], ...]] = MappingProxyType({
+    "index": (
+        ("krx", "krx_dd_trd"), ("kospi", "kospi_dd_trd"), ("kosdaq", "kosdaq_dd_trd"),
+        ("bond", "bon_dd_trd"), ("derivatives", "drvprod_dd_trd"),
+    ),
+    "stock": (
+        ("info", "stk_isu_base_info"), ("daily", "stk_bydd_trd"),
+        ("warrant", "sw_bydd_trd"), ("right", "sr_bydd_trd"),
+    ),
+    "etp": (("etf", "etf_bydd_trd"), ("etn", "etn_bydd_trd"), ("elw", "elw_bydd_trd")),
+    "bond": (
+        ("treasury", "kts_bydd_trd"), ("general", "bnd_bydd_trd"),
+        ("small_lot", "smb_bydd_trd"),
+    ),
+    "derivatives": (
+        ("futures", "fut_bydd_trd"), ("options", "opt_bydd_trd"),
+        ("stock_futures", "eqsfu_stk_bydd_trd"), ("stock_options", "eqsop_bydd_trd"),
+    ),
+    "commodity": (
+        ("oil", "oil_bydd_trd"), ("gold", "gold_bydd_trd"), ("emissions", "ets_bydd_trd"),
+    ),
+    "esg": (
+        ("sri_bond", "sri_bond_info"), ("index", "esg_index_info"), ("etp", "esg_etp_info"),
+    ),
+})
+
+
+def groups() -> list[str]:
+    """The client accessor groups, in tree order (``index``, ``stock``, ...)."""
+    return list(ACCESSORS)
+
+
+def methods(group: str) -> list[str]:
+    """The method names under one accessor group (raises ``KeyError`` if unknown)."""
+    return [name for name, _ in ACCESSORS[group]]
+
+
+def fields(group: str, name: str) -> list[str]:
+    """The field (column) names an accessor ``group.name`` returns, in order.
+
+        catalog.fields("index", "kospi")   # -> ["BAS_DD", "IDX_CLSS", ..., "MKTCAP"]
+
+    Reads the bundled schema -- no network, no key. Raises ``KeyError`` for an
+    unknown group or method (the same signal the client gives).
+    """
+    return _schema_fields(_api_id_for(group, name))
+
+
+def _api_id_for(group: str, name: str) -> str:
+    """Translate an accessor ``group.name`` to the KRX api_id it maps to -- the bridge
+    from the readable names to the api_id-keyed schema data. Internal: users and the
+    CLI go through :func:`fields`, never an api_id."""
+    for method_name, api_id in ACCESSORS[group]:
+        if method_name == name:
+            return api_id
+    raise KeyError(f"{group}.{name}")
+
+
+def _schema_fields(api_id: str) -> list[str]:
+    """The field names of an api_id's schema, in order. Internal: reached through
+    :func:`fields` by accessor name, never by a raw api_id."""
+    return list(SCHEMAS[ENDPOINTS[api_id].schema])
+
+
+def endpoints() -> list[KRXEndpoint]:
+    """Every KRX endpoint, in registry order."""
+    return list(ENDPOINTS.values())
+
+
+def schemas() -> dict[str, list[str]]:
+    """A mutable copy of the schema-name -> field-list map."""
+    return {name: list(field_names) for name, field_names in SCHEMAS.items()}
+
+

krx_openapi/cli.py

@@ -0,0 +1,170 @@
+"""Command-line shell over ``KRX`` -- three commands, one per plugin skill.
+
+``list`` and ``fields`` browse the bundled catalog offline (no key); ``fetch`` runs
+one service for a date. Each takes the readable ``group name`` pair the Python client
+uses -- ``krx fetch index kospi 20200414`` fetches what
+``krx.index.kospi("20200414")`` returns. No api_ids to memorize.
+
+    $ krx list                      # every group and its methods (offline)
+    $ krx list stock                # just one group (offline)
+    $ krx fields index kospi         # the columns that service returns (offline)
+    $ krx fetch index kospi 20200414
+    $ krx fetch stock daily 20200414 --market KOSDAQ
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Callable, Sequence
+
+from . import __version__, catalog
+from .client import KRX, _accepts_market
+from .errors import KRXError
+from .types import Row
+
+_PROG = "krx"
+_ERROR_PREFIX = f"{_PROG}: "
+
+# How many rows the text view prints; the full result is always in --json.
+_MAX_SHOWN_ROWS = 20
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Parse ``argv``, run one call, and return a process exit code.
+
+    A failure -- a missing/rejected key, a vendor error, or a transport problem -- is
+    printed as a one-line ``krx: <message>`` to stderr and returns 1. A usage error
+    caught here (an unknown service, or ``--market`` on a service without it) returns
+    2; argparse's own usage errors (a bad flag or subcommand) raise ``SystemExit(2)``.
+    """
+    args = _make_parser().parse_args(argv)
+    run: Callable[[argparse.Namespace], int] = args.run
+    try:
+        return run(args)
+    except KRXError as err:
+        print(f"{_ERROR_PREFIX}{err}", file=sys.stderr)
+        return 1
+
+
+def _make_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog=_PROG, description="Read the KRX Open API from the command line.")
+    parser.add_argument("--version", action="version", version=f"{_PROG} {__version__}")
+    commands = parser.add_subparsers(required=True)
+
+    # Registered list -> fields -> fetch: discovery first, then the key-gated fetch.
+    list_cmd = commands.add_parser("list", help="list services (offline)")
+    list_cmd.add_argument("group", nargs="?", choices=catalog.groups(), default=None,
+                          help="only this group; omit for all")
+    list_cmd.add_argument("--json", action="store_true", help="emit JSON instead of text")
+    list_cmd.set_defaults(run=_run_list)
+
+    fields_cmd = commands.add_parser("fields", help="a service's field schema (offline)")
+    fields_cmd.add_argument("group", choices=catalog.groups(), help="accessor group")
+    fields_cmd.add_argument("method", help="service method (e.g. kospi)")
+    fields_cmd.add_argument("--json", action="store_true", help="emit JSON instead of text")
+    fields_cmd.set_defaults(run=_run_fields)
+
+    # `krx fetch <group> <method> <date>` -- the one data command, mirroring the `fetch`
+    # skill. group is validated here; the method depends on the group, which argparse
+    # choices cannot express, so _run_fetch checks it against `catalog.methods(group)`.
+    fetch_cmd = commands.add_parser("fetch", help="fetch one day of a service")
+    fetch_cmd.add_argument("group", choices=catalog.groups(), help="accessor group")
+    fetch_cmd.add_argument("method", help="service method, e.g. kospi (see `krx list <group>`)")
+    fetch_cmd.add_argument("date", metavar="YYYYMMDD", help="trade date (basDd)")
+    fetch_cmd.add_argument("--market", default=None, metavar="M",
+                           help="KOSPI/KOSDAQ/KONEX for stock; KOSPI/KOSDAQ for stock-derivatives")
+    fetch_cmd.add_argument("--json", action="store_true", help="emit JSON instead of text")
+    fetch_cmd.set_defaults(run=_run_fetch)
+
+    return parser
+
+
+def _run_fetch(args: argparse.Namespace) -> int:
+    # Both usage checks run before KRX(), so a misused command is a usage error (exit 2)
+    # without needing an API key. The valid methods, and whether one takes --market,
+    # depend on the group -- more than argparse choices can express.
+    if args.method not in catalog.methods(args.group):
+        print(f"{_ERROR_PREFIX}unknown service {args.group} {args.method!r} "
+              f"(try `{_PROG} list {args.group}`)", file=sys.stderr)
+        return 2
+    if args.market is not None and not _accepts_market(args.group, args.method):
+        print(f"{_ERROR_PREFIX}fetch {args.group} {args.method} takes no --market",
+              file=sys.stderr)
+        return 2
+    method = getattr(getattr(KRX(), args.group), args.method)
+    kwargs = {"market": args.market} if args.market is not None else {}
+    try:
+        rows = method(args.date, **kwargs)
+    except ValueError as err:
+        # An unknown --market VALUE: the client raises ValueError (a caller mistake),
+        # a usage error (exit 2), not a traceback and not a transport failure.
+        print(f"{_ERROR_PREFIX}{err}", file=sys.stderr)
+        return 2
+    _emit(rows, args.json)
+    return 0
+
+
+def _run_list(args: argparse.Namespace) -> int:
+    target = [args.group] if args.group else catalog.groups()
+    if args.json:
+        print(json.dumps({g: catalog.methods(g) for g in target}, ensure_ascii=False, indent=2))
+        return 0
+    lines = []
+    for group in target:
+        lines.append(group)
+        lines += [f"  {group} {name}" for name in catalog.methods(group)]
+    print("\n".join(lines))
+    return 0
+
+
+def _run_fields(args: argparse.Namespace) -> int:
+    try:
+        fields = catalog.fields(args.group, args.method)
+    except KeyError:
+        print(f"{_ERROR_PREFIX}unknown service {args.group} {args.method!r} "
+              f"(try `{_PROG} list {args.group}`)", file=sys.stderr)
+        return 2
+    if args.json:
+        print(json.dumps(fields, ensure_ascii=False, indent=2))
+        return 0
+    print("\n".join(fields))
+    return 0
+
+
+def _emit(rows: Sequence[Row], as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(list(rows), ensure_ascii=False, indent=2))
+    else:
+        print(_render_rows(rows))
+
+
+def _render_rows(rows: Sequence[Row]) -> str:
+    """Rows as an aligned table over the first row's keys (up to ``_MAX_SHOWN_ROWS``),
+    then a total count. Empty -> ``(no rows)``."""
+    if not rows:
+        return "(no rows)"
+    headers = list(rows[0].keys())
+    shown = rows[:_MAX_SHOWN_ROWS]
+    body = [[row.get(key, "") for key in headers] for row in shown]
+    table = _render(headers, body)
+    if len(rows) > len(shown):
+        return f"{table}\n... ({len(rows)} rows total, showing {len(shown)})"
+    return f"{table}\n({len(rows)} rows)"
+
+
+def _render(headers: Sequence[str], rows: Sequence[Sequence[str]]) -> str:
+    """Rows as an aligned table over ``headers``, one row per line."""
+    columns = list(zip(headers, *rows, strict=True)) if rows else [(h,) for h in headers]
+    widths = [max(len(str(cell)) for cell in column) for column in columns]
+    line = "  ".join(str(h).ljust(w) for h, w in zip(headers, widths, strict=True))
+    body = "\n".join(
+        "  ".join(str(cell).ljust(w) for cell, w in zip(row, widths, strict=True))
+        for row in rows)
+    return f"{line}\n{body}" if body else line
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())