kwcli 0.1.0__py3-none-any.whl

kiwoom_cli/main.py

@@ -0,0 +1,203 @@
+import argparse
+import re
+import sys
+
+import requests
+
+from kiwoom import describe_selection
+from kiwoom.core.errors import CredentialsNotFoundError, KiwoomError
+from kiwoom.core.secrets import env_var_names
+from kiwoom_cli.errors import CliInputError, CliInternalError
+from kiwoom_cli.commands.auth import add_auth_parser
+from kiwoom_cli.commands.groups import DOMESTIC_GROUPS, add_group_parser
+from kiwoom_cli.commands.orders import add_orders_parser
+from kiwoom_cli.commands.spec import add_spec_parser
+from kiwoom_cli.commands.stocks import add_stocks_parser
+from kiwoom_cli.commands.streams import add_streams_parser
+from kiwoom_cli.doctor import add_doctor_parser
+from kiwoom_cli.setup import add_setup_parser
+
+
+class KiwoomArgumentParser(argparse.ArgumentParser):
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault("allow_abbrev", False)
+        kwargs.setdefault("formatter_class", argparse.RawDescriptionHelpFormatter)
+        super().__init__(*args, **kwargs)
+
+    def add_subparsers(self, *args, **kwargs):
+        kwargs.setdefault("parser_class", type(self))
+        return super().add_subparsers(*args, **kwargs)
+
+    def error(self, message: str) -> None:
+        self.print_usage(sys.stderr)
+        translated = _translate_argparse_error(message)
+        self.exit(2, f"{self.prog}: 오류: {translated}\n")
+
+
+def _translate_argparse_error(message: str) -> str:
+    required = re.fullmatch(r"the following arguments are required: (.+)", message)
+    if required:
+        return f"필수 인자가 빠졌습니다: {required.group(1)}"
+
+    argument_error = re.fullmatch(r"argument ([^:]+): (.+)", message)
+    if argument_error:
+        argument, reason = argument_error.groups()
+        return f"{argument} 값 오류: {_translate_argparse_error(reason)}"
+
+    unrecognized = re.fullmatch(r"unrecognized arguments: (.+)", message)
+    if unrecognized:
+        return f"알 수 없는 인자입니다: {unrecognized.group(1)}"
+
+    invalid_choice = re.fullmatch(
+        r"invalid choice: (.+) \(choose from (.+)\)", message
+    )
+    if invalid_choice:
+        value, choices = invalid_choice.groups()
+        return f"지원하지 않는 값입니다: {value}. 가능한 값: {choices}"
+
+    expected_one = re.fullmatch(r"expected one argument", message)
+    if expected_one:
+        return "값 하나가 필요합니다."
+
+    ignored_explicit = re.fullmatch(r"ignored explicit argument (.+)", message)
+    if ignored_explicit:
+        return f"예상하지 못한 값입니다: {ignored_explicit.group(1)}"
+
+    return message
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = KiwoomArgumentParser(prog="kiwoomcli", description="키움 REST API 도우미 CLI")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # 전역(시장 무관) 명령
+    add_setup_parser(subparsers)
+    add_auth_parser(subparsers)
+    add_doctor_parser(subparsers)
+    add_spec_parser(subparsers)
+
+    # 국내 시장(OpenAPI) 명령: `kiwoomcli domestic <group> <command>`
+    domestic_parser = subparsers.add_parser(
+        "domestic", help="국내 시장(OpenAPI) 명령입니다."
+    )
+    domestic = domestic_parser.add_subparsers(dest="domestic_command", required=True)
+    add_stocks_parser(domestic)
+    for group_name in (
+        "quotes",
+        "orderbooks",
+        "candles",
+        "etfs",
+        "elws",
+        "investors",
+        "rankings",
+        "sectors",
+        "short-selling",
+        "securities-lending",
+        "themes",
+    ):
+        add_group_parser(domestic, DOMESTIC_GROUPS[group_name])
+    add_streams_parser(domestic)
+    add_group_parser(domestic, DOMESTIC_GROUPS["accounts"])
+    add_orders_parser(domestic)
+
+    return parser
+
+
+def _normalize_console_encoding() -> None:
+    """표준 출력 스트림을 UTF-8로 맞춘다.
+
+    한글 Windows 콘솔의 기본 코덱(cp949)은 배너의 박스 문자나 일부 한글
+    출력을 인코딩하지 못해 UnicodeEncodeError로 죽는다. 시작 시 한 번
+    UTF-8로 정규화해 CLI 전체 출력을 일관되게 만든다.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        try:
+            reconfigure(encoding="utf-8")
+        except (ValueError, OSError):
+            pass
+
+
+def main() -> None:
+    _normalize_console_encoding()
+    parser = build_parser()
+    args = parser.parse_args()
+
+    try:
+        args.handler(args)
+    except KeyboardInterrupt:
+        print("사용자에 의해 작업이 취소되었습니다.", file=sys.stderr)
+        raise SystemExit(130)
+    except EOFError:
+        print("입력이 중단되었습니다.", file=sys.stderr)
+        raise SystemExit(1)
+    except CliInputError as exc:
+        # 사용자 입력/정책 위반: 한글 한 줄, usage 오류 코드(2)로 종료.
+        print(str(exc), file=sys.stderr)
+        raise SystemExit(2)
+    except CliInternalError as exc:
+        # 정상 사용으로는 도달 불가한 단언: 버그로 취급해 traceback과 함께 노출.
+        print(f"내부 오류: {exc}", file=sys.stderr)
+        raise
+    except CredentialsNotFoundError as exc:
+        print(_format_credentials_error(args, exc), file=sys.stderr)
+        raise SystemExit(1)
+    except (KiwoomError, OSError, requests.RequestException, ValueError) as exc:
+        # API/서버 오류와 라이브러리 ValueError(예: mode 불일치)는 원형 통과.
+        print(str(exc), file=sys.stderr)
+        raise SystemExit(1)
+    except Exception as exc:
+        # 예기치 못한 오류 = 버그: 내부 오류로 표시하고 traceback을 남긴다.
+        print(f"내부 오류: {exc}", file=sys.stderr)
+        raise
+
+
+def _format_credentials_error(args: argparse.Namespace, exc: CredentialsNotFoundError) -> str:
+    """Render a credentials error tailored to how the target was selected.
+
+    `CredentialsNotFoundError` only carries `mode`, so reconstruct the entry
+    path from args/env via `describe_selection`. The `--mode` failure and the
+    `--profile` failure are genuinely different problems and get different fixes.
+    """
+    mode_arg = getattr(args, "mode", None)
+    profile_arg = getattr(args, "profile", None)
+    try:
+        selection = describe_selection(mode_arg, profile=profile_arg)
+    except KiwoomError:
+        return str(exc)
+
+    if selection.uses_profile:
+        return "\n".join(
+            [
+                f"계좌 별칭 '{selection.profile}'의 키/시크릿을 찾을 수 없습니다.",
+                "",
+                "해결:",
+                f"  kiwoomcli setup {selection.profile}",
+            ]
+        )
+
+    appkey_var, secretkey_var = env_var_names(selection.mode)
+    return "\n".join(
+        [
+            f"{selection.mode} mode 키/시크릿을 찾을 수 없습니다.",
+            "",
+            "현재 인증 컨텍스트:",
+            f"  선택 방식: {selection.selection_source}",
+            f"  선택 대상: {selection.target_label}",
+            "  계좌 별칭: 사용 안 함",
+            "",
+            "왜 발생했나요?",
+            f"  {selection.selection_source}은(는) 저장된 계좌 별칭을 사용하지 않습니다.",
+            "  mode 방식은 APP_KEY / APP_SECRET 환경변수 또는 mode용 자격 증명이 필요합니다.",
+            "",
+            "해결:",
+            "  저장된 별칭을 쓰려면:  kiwoomcli <명령> --profile <별칭>",
+            f"  환경변수 방식으로 쓰려면:  {appkey_var} / {secretkey_var} 를 설정하세요.",
+        ]
+    )
+
+
+if __name__ == "__main__":
+    main()

kiwoom_cli/maps/README.md

@@ -0,0 +1,99 @@
+# Kiwoom CLI Maps
+
+**GENERATED — do not edit these CSVs by hand.** Every file in this folder is a
+build artifact written by `uv run python utils/build.py`. Human decisions live
+in `registry/` at the repo root: per-API curation in `registry/api_registry.csv`
+and the command-scoped tables in `registry/*.csv`. Edit there, then rebuild;
+`utils/build.py --check` fails on any drift between the two.
+
+## Files
+
+- `api_commands.csv`: one row per local Kiwoom API. Machine columns (api_name,
+  categories, method, path, required fields) are derived from `api_list.csv` /
+  `kiwoom_api_spec.json`; curated columns (cli_group, cli_command, command_path,
+  status, coverage_status, safety_policy, canonical_code_option, notes) come
+  from `registry/api_registry.csv`.
+- `arguments.csv`: explicit CLI option to Kiwoom request-field mappings for implemented commands (copied from `registry/arguments.csv`).
+- `positional_arguments.csv`: explicit positional shorthand policy by command path (copied from `registry/`).
+- `order_price_policies.csv`: explicit order-type to price/condition-price validation policy for implemented order-write commands (copied from `registry/`).
+- `order_confirmation_commands.csv`, `order_confirmation_fields.csv`, and `order_value_labels.csv`: 미전송 주문 확인 messages, fields, and labels for domestic order-write commands (copied from `registry/`).
+
+The table is intentionally explicit. Full CLI coverage means every API ID appears exactly once with an implemented, planned, review, blocked, or unsupported implementation status and a separate coverage status.
+
+## Current Counts
+
+| CLI Group | Implementation Status | Coverage Status | Count |
+| --- | --- | --- | ---: |
+| `accounts` | `implemented` | `guarded` | 28 |
+| `auth` | `implemented` | `public` | 2 |
+| `candles` | `implemented` | `public` | 21 |
+| `elws` | `implemented` | `public` | 11 |
+| `etfs` | `implemented` | `public` | 9 |
+| `investors` | `implemented` | `public` | 3 |
+| `orderbooks` | `implemented` | `public` | 2 |
+| `orders` | `implemented` | `guarded` | 17 |
+| `quotes` | `implemented` | `public` | 23 |
+| `rankings` | `implemented` | `public` | 23 |
+| `sectors` | `implemented` | `public` | 6 |
+| `securities-lending` | `implemented` | `public` | 4 |
+| `short-selling` | `implemented` | `public` | 1 |
+| `stocks` | `implemented` | `public` | 31 |
+| `stocks` | `planned` | `public` | 2 |
+| `streams` | `implemented` | `guarded` | 2 |
+| `streams` | `implemented` | `public` | 21 |
+| `themes` | `implemented` | `public` | 2 |
+
+## Implementation Status Meaning
+
+- `implemented`: parser/runtime behavior exists now.
+- `planned`: part of the intended CLI implementation backlog.
+- `review`: covered in maps/docs, but command semantics or safety policy still need review.
+
+## Coverage Status Meaning
+
+- `public`: ordinary read/query command surface.
+- `guarded`: command is exposed, but output/redaction/account-safety policy applies.
+- `preview-only`: request generation/validation is allowed first; real write submission is blocked (even with `--confirm`) until real-call verification promotes the row to `guarded`.
+- `planned`: mapped for full coverage, but command UX or policy is not fixed yet.
+
+## Column Notes
+
+- `cli_group` and `cli_command` are user-facing command taxonomy candidates.
+- `command_path` is the public invocation prefix when a command path is approved, not a raw API-ID command.
+- `status` tracks implementation lifecycle; `coverage_status` tracks exposure/safety posture.
+- `required_body_fields` and `required_header_fields` come from `kiwoom_api_spec.json`.
+- Implemented command request bodies are assembled from `arguments.csv`, not hidden field rewrites.
+- Order price validation is assembled from `order_price_policies.csv`; e.g. `limit` requires `--price`, while `market` forbids it.
+- 미전송 주문 확인 output is assembled from `order_confirmation_*.csv`; without `--confirm` the order API is never called.
+- `canonical_code_option` records the CLI naming rule: prefer `--code` for instrument/sector/theme/symbol-like values and map it internally to Kiwoom field names.
+
+## Validation Scope
+
+`.venv/bin/python -m utils.audit.validate_maps` verifies that `api_commands.csv`
+is in sync with `api_list.csv`, `kiwoom_api_spec.json`, and `arguments.csv`: API
+IDs, API names, categories, method/path, required body fields, required header
+fields, implementation status, coverage status, safety policy, implemented
+command argument coverage, argument Kiwoom fields, positional shorthand policy,
+order price policies, and documented count tables are checked directly from the
+source files.
+Count-table drift is checked across `kiwoom_cli/maps/README.md`,
+`docs/cli/api-coverage.md`, and `docs/cli/implementation-status.md`.
+
+`.venv/bin/python -m utils.audit.audit_implementation` verifies that implemented
+map rows exist in the argparse command surface, appear in the user-facing docs,
+and that implemented `preview-only`/`order_write` commands do not submit
+unless `--confirm` is supplied for domestic order writes. Domestic order writes
+show 미전송 주문 확인 output without `--confirm` and never call the order API. It also checks the project boundary rules that
+matter to the CLI surface: no broad `kiwoom/apis/` wrapper layer, no
+example-local auth helpers, no customer-facing `uv run kiwoom` invocation, no
+test-double/response-recording terms in implementation/test/example code, and
+resource command modules using the shared executor/runtime facade instead of
+direct network access. Generated `Examples/` files are also compiled
+statically and checked for package-facade runtime acquisition
+(`get_auth`, `get_client`, or `get_ws_client`) rather than direct network/core
+runtime access.
+
+`.venv/bin/python -m utils.prove.verify_real_calls --mode demo` is the
+credentialed-environment smoke checker for sanitized safe-read evidence. Without
+credentials it reports a blocked status before network submission instead of
+using any substitute response.