kwcli 0.1.0__py3-none-any.whl

kiwoom_cli/arguments.py

@@ -0,0 +1,147 @@
+"""Shared argparse helpers for resource commands."""
+
+from __future__ import annotations
+
+import argparse
+from datetime import datetime
+import re
+
+from kiwoom.core.types import VALID_MODES
+from kiwoom_cli.errors import CliInputError
+from kiwoom_cli.output import OUTPUT_FORMATS
+
+
+STOCK_CODE_PATTERN = re.compile(r"^\d{6}$")
+EXCHANGE_STOCK_CODE_PATTERN = re.compile(r"^\d{6}(?:_(?:NX|AL))?$")
+INSTRUMENT_CODE_PATTERN = re.compile(r"^[A-Za-z0-9]{6}$")
+SECTOR_CODE_PATTERN = re.compile(r"^\d{3}$")
+DATE_YYYYMMDD_PATTERN = re.compile(r"^\d{8}$")
+INTEGER_PATTERN = re.compile(r"^\d+$")
+ORDER_ID_PATTERN = re.compile(r"^\d{7}$")
+PREVIEW_ORDER_ID_PATTERN = re.compile(r"^\d+$")
+
+
+def add_runtime_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--profile",
+        help="사용할 계좌 별칭입니다. --mode/KIWOOM_MODE가 없을 때 생략하면 현재 계좌 별칭을 사용합니다.",
+    )
+    parser.add_argument("--mode", choices=VALID_MODES, help="계좌 별칭 대신 모드를 직접 지정합니다.")
+
+
+def add_output_format_arg(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--format", choices=OUTPUT_FORMATS, default="pretty", help="출력 형식")
+
+
+def resolve_optional_alias(
+    positional: str | None, option: str | None, option_name: str
+) -> str | None:
+    if positional and option and positional != option:
+        raise CliInputError(
+            "계좌 별칭은 positional 또는 "
+            f"{option_name} 중 하나만 지정해 주세요: {positional!r} != {option!r}"
+        )
+    return option or positional
+
+
+def stock_code(value: str) -> str:
+    if not STOCK_CODE_PATTERN.fullmatch(value):
+        raise argparse.ArgumentTypeError("--code는 6자리 국내 종목코드여야 합니다.")
+    return value
+
+
+def exchange_stock_code(value: str) -> str:
+    normalized = value.upper()
+    if not EXCHANGE_STOCK_CODE_PATTERN.fullmatch(normalized):
+        raise argparse.ArgumentTypeError(
+            "--code는 6자리 종목코드이거나 _NX/_AL 접미사가 붙은 거래소별 종목코드여야 합니다."
+        )
+    return normalized
+
+
+def instrument_code(value: str) -> str:
+    if not INSTRUMENT_CODE_PATTERN.fullmatch(value):
+        raise argparse.ArgumentTypeError("--code는 6자리 영문/숫자 종목코드여야 합니다.")
+    return value.upper()
+
+
+def sector_code(value: str) -> str:
+    if not SECTOR_CODE_PATTERN.fullmatch(value):
+        raise argparse.ArgumentTypeError("--code는 3자리 키움 업종코드여야 합니다.")
+    return value
+
+
+def date_yyyymmdd(value: str) -> str:
+    if not DATE_YYYYMMDD_PATTERN.fullmatch(value):
+        raise argparse.ArgumentTypeError("날짜는 YYYYMMDD 형식이어야 합니다.")
+    try:
+        datetime.strptime(value, "%Y%m%d")
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("날짜가 실제 달력 날짜가 아닙니다.") from exc
+    return value
+
+
+def adjusted_price_flag(value: str) -> str:
+    normalized = value.strip().lower()
+    if normalized in {"1", "true", "yes", "y", "adjusted"}:
+        return "1"
+    if normalized in {"0", "false", "no", "n", "raw", "unadjusted"}:
+        return "0"
+    raise argparse.ArgumentTypeError(
+        "--adjusted 값은 0, 1, true, false, adjusted, raw 중 하나여야 합니다."
+    )
+
+
+def positive_int_string(value: str) -> str:
+    if not INTEGER_PATTERN.fullmatch(value):
+        raise argparse.ArgumentTypeError("값은 양의 정수여야 합니다.")
+    if int(value) <= 0:
+        raise argparse.ArgumentTypeError("값은 0보다 커야 합니다.")
+    return value
+
+
+def nonnegative_int_string(value: str) -> str:
+    if not INTEGER_PATTERN.fullmatch(value):
+        raise argparse.ArgumentTypeError("값은 0 이상의 정수여야 합니다.")
+    if int(value) < 0:
+        raise argparse.ArgumentTypeError("값은 0 이상이어야 합니다.")
+    return value
+
+
+def price_string(value: str) -> str:
+    if not INTEGER_PATTERN.fullmatch(value):
+        raise argparse.ArgumentTypeError("가격은 정수 문자열이어야 합니다.")
+    if int(value) < 0:
+        raise argparse.ArgumentTypeError("가격은 0 이상이어야 합니다.")
+    return value
+
+
+def order_id(value: str) -> str:
+    if not ORDER_ID_PATTERN.fullmatch(value):
+        raise argparse.ArgumentTypeError("주문번호는 키움 7자리 주문번호여야 합니다.")
+    return value
+
+
+def preview_order_id(value: str) -> str:
+    if not PREVIEW_ORDER_ID_PATTERN.fullmatch(value):
+        raise argparse.ArgumentTypeError("주문번호는 숫자만 입력할 수 있습니다.")
+    return value
+
+
+def page_count(value: str) -> int:
+    try:
+        parsed = int(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("페이지 수는 정수여야 합니다.") from exc
+    if parsed < 0:
+        raise argparse.ArgumentTypeError("페이지 수는 0(전체) 이상이어야 합니다.")
+    return parsed
+
+
+def add_pages_arg(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--pages",
+        type=page_count,
+        default=1,
+        help="연속조회 페이지 수입니다 (기본 1, 0은 서버가 제공하는 모든 페이지).",
+    )

kiwoom_cli/auth_context.py

@@ -0,0 +1,64 @@
+"""Shared auth-context composition for CLI status/doctor/error rendering.
+
+This module does not redefine auth state. It composes the two existing
+sources of truth:
+
+- `kiwoom.core.runtime.describe_selection` — which input won target selection.
+- `kiwoom.core.auth.AuthStatus` — credential/token health for that target.
+
+`auth status`, `auth list`, `doctor`, and credential error messages all build
+on `AuthContext` so they cannot disagree about "can I call now / later?".
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from kiwoom.core.auth import AuthStatus
+from kiwoom.core.runtime import SelectionContext, describe_selection, get_auth
+
+
+@dataclass(frozen=True)
+class AuthContext:
+    selection: SelectionContext
+    status: AuthStatus
+
+    @property
+    def can_call_now(self) -> bool:
+        """A request can be served right now."""
+        # A reusable cached token works even without stored credentials;
+        # otherwise credentials let auth issue/refresh before the request.
+        return self.status.token_reusable or self.status.has_credentials
+
+    @property
+    def can_refresh(self) -> bool:
+        """A fresh token can be issued/refreshed (needs credentials)."""
+        return self.status.has_credentials
+
+    def warnings(self) -> list[str]:
+        messages: list[str] = []
+        if self.status.token_warning:
+            messages.append(self.status.token_warning)
+        if self.status.token_reusable and not self.status.has_credentials:
+            messages.append(
+                "지금은 캐시 토큰으로 호출할 수 있지만, 토큰 만료 후에는 자동 재발급할 수 없습니다."
+            )
+        if not self.can_call_now:
+            messages.append("현재 이 대상으로는 API를 호출할 수 없습니다.")
+        return messages
+
+
+def build_auth_context(
+    mode: str | None = None,
+    *,
+    profile: str | None = None,
+) -> AuthContext:
+    """Resolve selection then snapshot auth health for that target.
+
+    Raises `ModeNotConfiguredError` when nothing selects a target, matching
+    `describe_selection`/`get_auth`.
+    """
+
+    selection = describe_selection(mode, profile=profile)
+    auth = get_auth(mode, profile=profile)
+    return AuthContext(selection=selection, status=auth.status())

kiwoom_cli/banner.py

@@ -0,0 +1,125 @@
+"""`kiwoomcli setup` 시작 시 표시하는 ASCII 배너.
+
+컬러: KIWOOM 워드마크는 네이비, 오른쪽 'K' 로고는 기본 회색(#BEBEBE)에
+상단 화살표만 마젠타 핑크로 포인트. 자막/버전은 회색. 색은 대화형 터미널에서만
+적용하고, 파이프/리다이렉트(비-TTY)나 NO_COLOR 환경에서는 무채색으로 출력한다.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import sys
+from importlib.metadata import PackageNotFoundError, version
+
+# 키움 브랜드 컬러 (truecolor).
+_NAVY = "\033[1;38;2;26;31;113m"      # KIWOOM 워드마크
+_GRAY = "\033[1;38;2;190;190;190m"    # 오른쪽 K 기본색 #BEBEBE
+_MAGENTA = "\033[1;38;2;230;0;122m"   # K 상단 화살표 포인트
+_WHITE = "\033[1;38;2;255;255;255m"   # 자막 / 버전
+_RESET = "\033[0m"
+
+# 워드마크(좌) / 오른쪽 K(우) 경계 컬럼.
+_SPLIT = 51
+# 오른쪽 K에서 상단 화살표(마젠타) 행. 하단(4~6행)은 회색.
+_ARROW_ROWS = {0, 1, 2, 3}
+
+_ART = """\
+██╗  ██╗██╗██╗    ██╗ ██████╗  ██████╗ ███╗   ███╗  ██   ▜██
+██║ ██╔╝██║██║    ██║██╔═══██╗██╔═══██╗████╗ ████║  ██  ╱█▛▜
+█████╔╝ ██║██║ █╗ ██║██║   ██║██║   ██║██╔████╔██║  ██ ███╱
+██╔═██╗ ██║██║███╗██║██║   ██║██║   ██║██║╚██╔╝██║  █████╱
+██║  ██╗██║╚███╔███╔╝╚██████╔╝╚██████╔╝██║ ╚═╝ ██║  ██ ╲██╲
+╚═╝  ╚═╝╚═╝ ╚══╝╚══╝  ╚═════╝  ╚═════╝ ╚═╝     ╚═╝  ██  ╲██╲
+                                                    ██   ╲██▙"""
+
+_SUBTITLE = "                    키움증권 CLI"
+
+
+def _use_color() -> bool:
+    if "NO_COLOR" in os.environ:
+        return False
+    if not sys.stdout.isatty():
+        return False
+    if os.environ.get("TERM") == "dumb":
+        return False
+    if os.name != "nt":
+        return True
+    if os.environ.get("WT_SESSION") or os.environ.get("ANSICON"):
+        return True
+    if os.environ.get("ConEmuANSI", "").upper() == "ON":
+        return True
+    return _enable_windows_vt()
+
+
+def _enable_windows_vt() -> bool:
+    std_output_handle = -11
+    enable_virtual_terminal_processing = 0x0004
+    try:
+        kernel32 = ctypes.windll.kernel32
+        handle = kernel32.GetStdHandle(std_output_handle)
+        if handle in (-1, 0):
+            return False
+        mode = ctypes.c_uint()
+        if not kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+            return False
+        if mode.value & enable_virtual_terminal_processing:
+            return True
+        return bool(
+            kernel32.SetConsoleMode(
+                handle,
+                mode.value | enable_virtual_terminal_processing,
+            )
+        )
+    except Exception:
+        return False
+
+
+_BOX = set("╗╝═║╔╚")  # 워드마크 외곽선(그림자) 문자
+
+
+def _colorize_wordmark(segment: str) -> str:
+    """워드마크: `█` 블록은 네이비, 외곽선 문자는 #BEBEBE로 대비를 준다."""
+    out: list[str] = []
+    current: str | None = None
+    for char in segment:
+        color = _GRAY if char in _BOX else _NAVY
+        if color != current:
+            out.append(color)
+            current = color
+        out.append(char)
+    return "".join(out)
+
+
+def _arrow_start(right: str) -> int:
+    """오른쪽 조각에서 마지막 공백 뒤(=상단 화살표 시작) 인덱스."""
+    index = len(right)
+    while index > 0 and right[index - 1] != " ":
+        index -= 1
+    return index
+
+
+def print_banner() -> None:
+    try:
+        current = version("kiwoomcli")
+    except PackageNotFoundError:
+        current = "dev"
+    ver_line = f"                    ver {current}"
+
+    if _use_color():
+        for row, line in enumerate(_ART.splitlines()):
+            left, right = line[:_SPLIT], line[_SPLIT:]
+            if row in _ARROW_ROWS:
+                cut = _arrow_start(right)
+                if row == 3:
+                    cut += 1  # 엘보 맨 왼쪽 한 칸은 기둥이므로 회색 유지
+                print(f"{_colorize_wordmark(left)}{_GRAY}{right[:cut]}{_MAGENTA}{right[cut:]}{_RESET}")
+            else:
+                print(f"{_colorize_wordmark(left)}{_GRAY}{right}{_RESET}")
+        print(f"{_WHITE}{_SUBTITLE}{_RESET}")
+        print(f"{_WHITE}{ver_line}{_RESET}")
+    else:
+        print(_ART)
+        print(_SUBTITLE)
+        print(ver_line)
+    print()

kiwoom_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Domain command handlers for the installed kiwoom CLI."""