kwcli 0.1.0__py3-none-any.whl

kiwoom/core/errors.py

@@ -0,0 +1,177 @@
+from pathlib import Path
+
+# Kiwoom auth-expiry return codes that warrant a one-shot credential
+# recovery + retry (shared by the REST client and the WebSocket client).
+AUTH_RETRY_RETURN_CODES = frozenset({8005, 8031, 8103})
+
+
+def normalize_return_code(value: object) -> int | None:
+    """Normalize a Kiwoom ``return_code`` payload value.
+
+    The server emits the code as an int or a numeric string ("0", "0000",
+    "8005") depending on the endpoint. ``None``, blank, and non-numeric
+    values mean "no code present".
+    """
+    if value is None or isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    text = str(value).strip()
+    if not text or not text.lstrip("-").isdigit():
+        return None
+    return int(text)
+
+
+class KiwoomError(Exception):
+    """Base error for the Kiwoom helper package."""
+
+
+class SetupError(KiwoomError):
+    """Raised when setup onboarding cannot complete."""
+
+
+class InvalidModeError(KiwoomError):
+    def __init__(self, value: str):
+        super().__init__(
+            f"지원하지 않는 모드 값입니다: {value!r}. "
+            "사용 가능한 값은 'real' 또는 'demo' 입니다."
+        )
+        self.value = value
+
+
+class SettingsError(KiwoomError):
+    """Raised when the local settings file is unreadable or invalid."""
+
+
+class ModeNotConfiguredError(KiwoomError):
+    def __init__(self):
+        super().__init__(
+            "사용할 계좌가 설정되어 있지 않습니다. "
+            "`kiwoomcli setup`으로 계좌를 등록하거나, 이미 등록한 계좌가 있으면 "
+            "`kiwoomcli auth switch <별칭>`으로 선택해 주세요."
+        )
+
+
+class CredentialsNotFoundError(KiwoomError):
+    def __init__(self, mode: str):
+        super().__init__(
+            f"{mode!r} 모드 자격 증명을 찾을 수 없습니다. "
+            "다음 명령으로 초기 설정을 진행하거나, 환경변수를 설정해 주세요: "
+            "kiwoomcli setup"
+        )
+        self.mode = mode
+
+
+class KeyringUnavailableError(KiwoomError):
+    """Raised when the OS credential store is unavailable."""
+
+
+class InvalidTokenCacheError(KiwoomError):
+    def __init__(self, path: Path, reason: str):
+        super().__init__(f"토큰 캐시 파일이 올바르지 않습니다: {path} ({reason})")
+        self.path = path
+        self.reason = reason
+
+
+class HTTPRequestError(KiwoomError):
+    def __init__(self, status_code: int, message: str):
+        super().__init__(f"HTTP 요청 실패 ({status_code}): {message}")
+        self.status_code = status_code
+        self.message = message
+
+
+class AuthenticationError(KiwoomError):
+    """Raised when token issuance or auth recovery fails."""
+
+
+class APIError(KiwoomError):
+    def __init__(self, return_code: int, return_msg: str):
+        super().__init__(f"키움 API 오류 ({return_code}): {return_msg}")
+        self.return_code = return_code
+        self.return_msg = return_msg
+
+
+class InputValidationError(APIError):
+    """Raised when required fields or formats are invalid."""
+
+
+class RateLimitError(APIError):
+    """Raised when the API request limit is exceeded."""
+
+    def __init__(self, return_code: int, return_msg: str):
+        super().__init__(return_code, f"요청 한도를 초과했습니다. 잠시 후 다시 시도해 주세요. ({return_msg})")
+
+
+class SymbolNotFoundError(APIError):
+    """Raised when a requested symbol or market code is invalid."""
+
+    def __init__(self, return_code: int, return_msg: str):
+        super().__init__(return_code, f"종목 코드 또는 시장 정보가 올바르지 않습니다. ({return_msg})")
+
+
+class InvalidCredentialsError(AuthenticationError):
+    def __init__(self, return_code: int, return_msg: str):
+        super().__init__(f"앱키 또는 시크릿키가 올바르지 않습니다 ({return_code}): {return_msg}")
+        self.return_code = return_code
+        self.return_msg = return_msg
+
+
+class InvalidTokenError(AuthenticationError):
+    def __init__(self, return_code: int, return_msg: str):
+        super().__init__(f"접근 토큰이 올바르지 않거나 만료되었습니다 ({return_code}): {return_msg}")
+        self.return_code = return_code
+        self.return_msg = return_msg
+
+
+class ModeMismatchError(AuthenticationError):
+    def __init__(self, return_code: int, return_msg: str):
+        super().__init__(f"실전/모의 모드가 일치하지 않습니다 ({return_code}): {return_msg}")
+        self.return_code = return_code
+        self.return_msg = return_msg
+
+
+class DeviceAuthenticationError(AuthenticationError):
+    def __init__(self, return_code: int, return_msg: str):
+        super().__init__(f"단말기 인증에 실패했습니다 ({return_code}): {return_msg}")
+        self.return_code = return_code
+        self.return_msg = return_msg
+
+
+INPUT_VALIDATION_CODES = {
+    1501,
+    1504,
+    1505,
+    1511,
+    1512,
+    1513,
+    1514,
+    1515,
+    1516,
+    1517,
+    1687,
+    8020,
+}
+RATE_LIMIT_CODES = {1700}
+SYMBOL_NOT_FOUND_CODES = {1901, 1902}
+INVALID_CREDENTIAL_CODES = {8001, 8002, 8011, 8012}
+INVALID_TOKEN_CODES = {8003, 8005, 8006, 8009, 8015, 8016}
+MODE_MISMATCH_CODES = {8030, 8031}
+DEVICE_AUTH_CODES = {8010, 8040, 8050, 8103}
+
+
+def raise_for_error_code(return_code: int, return_msg: str) -> None:
+    if return_code in INPUT_VALIDATION_CODES:
+        raise InputValidationError(return_code, return_msg)
+    if return_code in RATE_LIMIT_CODES:
+        raise RateLimitError(return_code, return_msg)
+    if return_code in SYMBOL_NOT_FOUND_CODES:
+        raise SymbolNotFoundError(return_code, return_msg)
+    if return_code in INVALID_CREDENTIAL_CODES:
+        raise InvalidCredentialsError(return_code, return_msg)
+    if return_code in INVALID_TOKEN_CODES:
+        raise InvalidTokenError(return_code, return_msg)
+    if return_code in MODE_MISMATCH_CODES:
+        raise ModeMismatchError(return_code, return_msg)
+    if return_code in DEVICE_AUTH_CODES:
+        raise DeviceAuthenticationError(return_code, return_msg)
+    raise APIError(return_code, return_msg)

kiwoom/core/platform_paths.py

@@ -0,0 +1,68 @@
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from platformdirs import user_cache_dir, user_config_dir
+
+
+APP_NAME = "kiwoom"
+
+
+def config_dir() -> Path:
+    return Path(user_config_dir(APP_NAME))
+
+
+def cache_dir() -> Path:
+    return Path(user_cache_dir(APP_NAME))
+
+
+def ensure_private_directory(path: Path, *, strict: bool = False) -> Path:
+    path.mkdir(parents=True, exist_ok=True)
+    _protect_path(path, strict=strict, is_dir=True)
+    return path
+
+
+def protect_file(path: Path, *, strict: bool = False) -> Path:
+    _protect_path(path, strict=strict, is_dir=False)
+    return path
+
+
+def _protect_path(path: Path, *, strict: bool, is_dir: bool) -> None:
+    if os.name == "nt":
+        success = _protect_windows_path(path, is_dir=is_dir)
+        if strict and not success:
+            raise PermissionError(f"Could not restrict access to {path}")
+        return
+
+    mode = 0o700 if is_dir else 0o600
+    path.chmod(mode)
+
+
+def _protect_windows_path(path: Path, *, is_dir: bool) -> bool:
+    # Prefer OS-specific user directories and then try to remove inherited ACLs.
+    icacls = shutil.which("icacls")
+    if not icacls:
+        return False
+
+    target = str(path)
+    commands = [
+        [icacls, target, "/inheritance:r"],
+        [icacls, target, "/grant:r", f"{os.environ.get('USERNAME', '%USERNAME%')}:F"],
+    ]
+
+    if is_dir:
+        commands[1].append("/t")
+        commands[1].append("/c")
+
+    for command in commands:
+        result = subprocess.run(
+            command,
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0:
+            return False
+
+    return True

kiwoom/core/profiles.py

@@ -0,0 +1,143 @@
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+
+from kiwoom.core.errors import SettingsError
+from kiwoom.core.platform_paths import config_dir, ensure_private_directory, protect_file
+from kiwoom.core.settings import SETTINGS_FILE_NAME, settings_path
+from kiwoom.core.types import Mode, normalize_mode
+
+PROFILE_ALIAS_MAX_LENGTH = 64
+PROFILE_ALIAS_ALLOWED_PUNCTUATION = {" ", ".", "_", "-"}
+PROFILE_ALIAS_FORBIDDEN_CHARACTERS = {"/", "\\", ":"}
+
+
+@dataclass(frozen=True)
+class AuthProfile:
+    alias: str
+    mode: Mode
+
+
+def validate_profile_alias(alias: str) -> str:
+    normalized = alias.strip()
+    if not normalized:
+        raise ValueError("계좌 별칭을 입력해 주세요. 예: 모의계좌, 실전계좌, family-demo")
+    if len(normalized) > PROFILE_ALIAS_MAX_LENGTH:
+        raise ValueError("계좌 별칭은 64자 이하여야 합니다.")
+    if normalized in {".", ".."}:
+        raise ValueError("계좌 별칭으로 '.', '..'는 사용할 수 없습니다.")
+    if any(character in PROFILE_ALIAS_FORBIDDEN_CHARACTERS for character in normalized):
+        raise ValueError("계좌 별칭에는 '/', '\\', ':' 문자를 사용할 수 없습니다.")
+    if any(ord(character) < 32 for character in normalized):
+        raise ValueError("계좌 별칭에는 제어 문자를 사용할 수 없습니다.")
+    if not any(character.isalnum() for character in normalized):
+        raise ValueError("계좌 별칭에는 한글/영문/숫자 중 하나 이상이 포함되어야 합니다.")
+    invalid_characters = [
+        character
+        for character in normalized
+        if not character.isalnum() and character not in PROFILE_ALIAS_ALLOWED_PUNCTUATION
+    ]
+    if invalid_characters:
+        raise ValueError("계좌 별칭에는 한글, 영문, 숫자, 공백, '.', '_', '-'만 사용할 수 있습니다.")
+    return normalized
+
+
+def load_profiles() -> dict[str, AuthProfile]:
+    payload = _load_settings_payload()
+    raw_profiles = payload.get("profiles", {})
+    if not isinstance(raw_profiles, dict):
+        raise SettingsError("settings.json의 profiles 값은 객체(JSON object)여야 합니다.")
+
+    profiles: dict[str, AuthProfile] = {}
+    for alias, raw in raw_profiles.items():
+        if not isinstance(alias, str) or not isinstance(raw, dict):
+            raise SettingsError("settings.json의 profiles 항목 형식이 올바르지 않습니다.")
+        profile_alias = validate_profile_alias(alias)
+        mode_value = raw.get("mode")
+        if not isinstance(mode_value, str):
+            raise SettingsError(f"profile {alias!r}의 mode 값은 문자열이어야 합니다.")
+        profiles[profile_alias] = AuthProfile(alias=profile_alias, mode=normalize_mode(mode_value))
+    return profiles
+
+
+def get_profile(alias: str) -> AuthProfile:
+    profile_alias = validate_profile_alias(alias)
+    profiles = load_profiles()
+    try:
+        return profiles[profile_alias]
+    except KeyError as exc:
+        raise SettingsError(f"저장된 Kiwoom 계좌 별칭을 찾을 수 없습니다: {profile_alias}") from exc
+
+
+def get_current_profile() -> AuthProfile | None:
+    payload = _load_settings_payload()
+    current = payload.get("current_profile")
+    if current is None:
+        return None
+    if not isinstance(current, str):
+        raise SettingsError("settings.json의 current_profile 값은 문자열이어야 합니다.")
+    profiles = load_profiles()
+    return profiles.get(validate_profile_alias(current))
+
+
+def save_profile(alias: str, mode: Mode, *, make_current: bool = True) -> AuthProfile:
+    profile = AuthProfile(alias=validate_profile_alias(alias), mode=normalize_mode(mode))
+    payload = _load_settings_payload()
+    profiles = payload.get("profiles", {})
+    if not isinstance(profiles, dict):
+        profiles = {}
+    profiles[profile.alias] = {"mode": profile.mode}
+    payload["profiles"] = profiles
+    if make_current:
+        payload["current_profile"] = profile.alias
+    _write_settings_payload(payload)
+    return profile
+
+
+def set_current_profile(alias: str) -> AuthProfile:
+    profile = get_profile(alias)
+    payload = _load_settings_payload()
+    payload["current_profile"] = profile.alias
+    _write_settings_payload(payload)
+    return profile
+
+
+def delete_profile(alias: str) -> None:
+    profile_alias = validate_profile_alias(alias)
+    payload = _load_settings_payload()
+    profiles = payload.get("profiles", {})
+    if isinstance(profiles, dict):
+        profiles.pop(profile_alias, None)
+        payload["profiles"] = profiles
+    if payload.get("current_profile") == profile_alias:
+        payload.pop("current_profile", None)
+    _write_settings_payload(payload)
+
+
+def _load_settings_payload() -> dict:
+    path = settings_path()
+    if not path.exists():
+        return {}
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise SettingsError("settings.json 파일 형식이 올바르지 않습니다.") from exc
+    except OSError as exc:
+        raise SettingsError("settings.json 파일을 읽을 수 없습니다.") from exc
+    if not isinstance(payload, dict):
+        raise SettingsError("settings.json 최상위 형식은 객체(JSON object)여야 합니다.")
+    return payload
+
+
+def _write_settings_payload(payload: dict) -> Path:
+    directory = ensure_private_directory(config_dir(), strict=False)
+    path = directory / SETTINGS_FILE_NAME
+    rendered = json.dumps(payload, ensure_ascii=True, indent=2)
+    with NamedTemporaryFile("w", encoding="utf-8", dir=directory, delete=False) as tmp:
+        tmp.write(rendered)
+        temp_path = Path(tmp.name)
+    protect_file(temp_path, strict=False)
+    temp_path.replace(path)
+    protect_file(path, strict=False)
+    return path

kiwoom/core/runtime.py

@@ -0,0 +1,153 @@
+from dataclasses import dataclass
+from typing import Literal
+
+from kiwoom.core.auth import KiwoomAuth, get_base_url as _auth_base_url, get_ws_base_url as _auth_ws_base_url
+from kiwoom.core.client import KiwoomClient
+from kiwoom.core.errors import ModeNotConfiguredError
+from kiwoom.core.profiles import AuthProfile, get_current_profile, get_profile
+from kiwoom.core.secrets import SecretProvider, default_secret_provider
+from kiwoom.core.settings import get_mode_from_env, get_profile_from_env
+from kiwoom.core.token_store import FileTokenStore, MemoryTokenStore
+from kiwoom.core.types import Mode, normalize_mode
+from kiwoom.core.ws_client import KiwoomWebSocketClient
+
+TokenStoreKind = Literal["file", "memory"]
+
+SelectionSource = Literal[
+    "--profile",
+    "KIWOOM_PROFILE",
+    "--mode",
+    "KIWOOM_MODE",
+    "current_profile",
+]
+
+
+@dataclass(frozen=True)
+class _Selection:
+    """How `mode`/`profile` inputs resolved to a concrete auth target.
+
+    Single source of truth shared by `resolve_mode`, `get_auth`, and
+    `describe_selection` so the selection precedence cannot diverge.
+    """
+
+    source: SelectionSource
+    profile: AuthProfile | None
+    mode: Mode
+
+
+def _resolve_selection(*, mode: str | None, profile: str | None) -> _Selection:
+    explicit_profile = profile
+    env_profile = get_profile_from_env() if profile is None else None
+    profile_alias = explicit_profile if explicit_profile is not None else env_profile
+    env_mode = None if mode is not None else get_mode_from_env()
+
+    if profile_alias is not None:
+        selected = get_profile(profile_alias)
+        selected_mode = normalize_mode(mode) if mode is not None else env_mode
+        if selected_mode is not None and selected_mode != selected.mode:
+            raise ValueError("지정한 mode가 선택한 계좌 별칭의 mode와 일치하지 않습니다")
+        source: SelectionSource = "--profile" if explicit_profile is not None else "KIWOOM_PROFILE"
+        return _Selection(source=source, profile=selected, mode=selected.mode)
+
+    if mode is not None:
+        return _Selection(source="--mode", profile=None, mode=normalize_mode(mode))
+
+    if env_mode is not None:
+        return _Selection(source="KIWOOM_MODE", profile=None, mode=env_mode)
+
+    current_profile = get_current_profile()
+    if current_profile is not None:
+        return _Selection(source="current_profile", profile=current_profile, mode=current_profile.mode)
+
+    raise ModeNotConfiguredError()
+
+
+@dataclass(frozen=True)
+class SelectionContext:
+    """Public description of which input won auth target selection."""
+
+    selection_source: SelectionSource
+    mode: Mode
+    profile: str | None
+    uses_profile: bool
+    target_label: str
+
+
+def describe_selection(mode: str | None = None, *, profile: str | None = None) -> SelectionContext:
+    """Report how `mode`/`profile` resolve, without building an auth object.
+
+    Raises `ModeNotConfiguredError` when nothing selects a target, matching
+    `resolve_mode`/`get_auth`.
+    """
+
+    selection = _resolve_selection(mode=mode, profile=profile)
+    alias = selection.profile.alias if selection.profile else None
+    uses_profile = selection.profile is not None
+    target_label = f"계좌 별칭 {alias}" if uses_profile else f"{selection.mode} mode"
+    return SelectionContext(
+        selection_source=selection.source,
+        mode=selection.mode,
+        profile=alias,
+        uses_profile=uses_profile,
+        target_label=target_label,
+    )
+
+
+def resolve_mode(mode: str | None = None, *, profile: str | None = None) -> Mode:
+    return _resolve_selection(mode=mode, profile=profile).mode
+
+
+def get_auth(
+    mode: str | None = None,
+    *,
+    profile: str | None = None,
+    secret_provider: SecretProvider | None = None,
+    token_store_kind: TokenStoreKind = "file",
+) -> KiwoomAuth:
+    selection = _resolve_selection(mode=mode, profile=profile)
+    profile_alias = selection.profile.alias if selection.profile else None
+    return KiwoomAuth(
+        mode=selection.mode,
+        profile=profile_alias,
+        secret_provider=secret_provider or default_secret_provider(profile=profile_alias),
+        token_store=_build_token_store(token_store_kind),
+    )
+
+
+def get_client(
+    mode: str | None = None,
+    *,
+    profile: str | None = None,
+    auth: KiwoomAuth | None = None,
+    timeout_seconds: int = 30,
+) -> KiwoomClient:
+    if auth is not None and (mode is not None or profile is not None):
+        raise ValueError("mode/profile and auth cannot be used together")
+    return KiwoomClient(auth or get_auth(mode, profile=profile), timeout_seconds=timeout_seconds)
+
+
+def get_ws_client(
+    mode: str | None = None,
+    *,
+    profile: str | None = None,
+    auth: KiwoomAuth | None = None,
+) -> KiwoomWebSocketClient:
+    if auth is not None and (mode is not None or profile is not None):
+        raise ValueError("mode/profile and auth cannot be used together")
+    return KiwoomWebSocketClient(auth or get_auth(mode, profile=profile))
+
+
+def get_base_url(mode: str | None = None, *, profile: str | None = None) -> str:
+    return _auth_base_url(resolve_mode(mode, profile=profile))
+
+
+def get_ws_base_url(mode: str | None = None, *, profile: str | None = None) -> str:
+    return _auth_ws_base_url(resolve_mode(mode, profile=profile))
+
+
+def _build_token_store(token_store_kind: TokenStoreKind):
+    if token_store_kind == "file":
+        return FileTokenStore()
+    if token_store_kind == "memory":
+        return MemoryTokenStore()
+    raise ValueError(f"unsupported token_store_kind: {token_store_kind}")