kwcli 0.1.0__py3-none-any.whl

kiwoom/core/__init__.py

@@ -0,0 +1,6 @@
+"""Runtime primitives for the Kiwoom OpenAPI package.
+
+Import concrete submodules (``kiwoom.core.errors``, ``kiwoom.core.secrets``,
+...) or use the canonical package facade ``kiwoom`` (``get_auth``,
+``get_client``, ``get_ws_client``, profiles, types).
+"""

kiwoom/core/auth.py

@@ -0,0 +1,349 @@
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta, timezone
+import hashlib
+import os
+from typing import Literal
+
+import requests
+
+from kiwoom.core.errors import (
+    AuthenticationError,
+    CredentialsNotFoundError,
+    HTTPRequestError,
+    InvalidTokenCacheError,
+    raise_for_error_code,
+)
+from kiwoom.core.secrets import CredentialSet, SecretProvider
+from kiwoom.core.token_store import TokenRecord
+from kiwoom.core.types import Mode, normalize_mode
+
+
+KST = timezone(timedelta(hours=9))
+TOKEN_PATH = "/oauth2/token"
+REVOKE_PATH = "/oauth2/revoke"
+BASE_URL_ENV_VARS: dict[Mode, str] = {
+    "real": "PRD",
+    "demo": "MOCK",
+}
+WS_BASE_URL_ENV_VARS: dict[Mode, str] = {
+    "real": "W_PRD",
+    "demo": "W_MOCK",
+}
+DEFAULT_BASE_URLS: dict[Mode, str] = {
+    "real": "https://api.kiwoom.com",
+    "demo": "https://mockapi.kiwoom.com",
+}
+DEFAULT_WS_BASE_URLS: dict[Mode, str] = {
+    "real": "wss://api.kiwoom.com:10000",
+    "demo": "wss://mockapi.kiwoom.com:10000",
+}
+
+
+def get_base_url(mode: Mode) -> str:
+    resolved_mode = normalize_mode(mode)
+    return _endpoint_from_env(BASE_URL_ENV_VARS[resolved_mode], DEFAULT_BASE_URLS[resolved_mode])
+
+
+def get_ws_base_url(mode: Mode) -> str:
+    resolved_mode = normalize_mode(mode)
+    return _endpoint_from_env(WS_BASE_URL_ENV_VARS[resolved_mode], DEFAULT_WS_BASE_URLS[resolved_mode])
+
+
+def endpoint_env_var_names(mode: Mode) -> tuple[str, str]:
+    resolved_mode = normalize_mode(mode)
+    return BASE_URL_ENV_VARS[resolved_mode], WS_BASE_URL_ENV_VARS[resolved_mode]
+
+
+def _endpoint_from_env(name: str, default: str) -> str:
+    value = os.getenv(name, "").strip()
+    return value.rstrip("/") if value else default
+
+
+NextAuthAction = Literal[
+    "use_cached_token",
+    "issue_before_request",
+    "refresh_before_request",
+    "credentials_missing",
+]
+
+
+@dataclass(frozen=True)
+class AuthStatus:
+    mode: Mode
+    credential_source: str | None
+    has_credentials: bool
+    has_token: bool
+    token_saved_at: datetime | None
+    token_expires_at: datetime | None
+    token_valid: bool
+    token_reusable: bool
+    next_auth_action: NextAuthAction
+    token_warning: str | None
+    profile: str | None = None
+
+
+class KiwoomAuth:
+    def __init__(
+        self,
+        mode: Mode,
+        secret_provider: SecretProvider,
+        token_store,
+        *,
+        profile: str | None = None,
+        refresh_buffer_seconds: int = 600,
+        timeout_seconds: int = 30,
+    ) -> None:
+        self.mode = normalize_mode(mode)
+        self.secret_provider = secret_provider
+        self.token_store = token_store
+        self.profile = profile
+        self.timeout_seconds = timeout_seconds
+
+        if refresh_buffer_seconds < 0:
+            raise ValueError("refresh_buffer_seconds는 0 이상이어야 합니다.")
+        if refresh_buffer_seconds > 60 * 60 * 12:
+            raise ValueError("refresh_buffer_seconds 값이 너무 큽니다.")
+        self.refresh_buffer = timedelta(seconds=refresh_buffer_seconds)
+
+    def get_access_token(self) -> str:
+        record = self._load_valid_token()
+        if record is not None:
+            return record.access_token
+        return self.refresh_access_token()
+
+    def refresh_access_token(self) -> str:
+        credentials = self.secret_provider.get_credentials(self.mode)
+        if credentials is None:
+            raise CredentialsNotFoundError(self.mode)
+
+        payload = {
+            "grant_type": "client_credentials",
+            "appkey": credentials.appkey,
+            "secretkey": credentials.secretkey,
+        }
+        response = requests.post(
+            f"{get_base_url(self.mode)}{TOKEN_PATH}",
+            json=payload,
+            headers={"Content-Type": "application/json;charset=UTF-8"},
+            timeout=self.timeout_seconds,
+        )
+        data = _safe_json(response)
+        if response.status_code >= 400:
+            _raise_structured_error(
+                response.status_code,
+                data,
+                fallback_message="토큰 요청에 실패했습니다.",
+            )
+        if data.get("return_code") not in (None, 0):
+            raise_for_error_code(
+                int(data["return_code"]),
+                str(data.get("return_msg", "인증에 실패했습니다.")),
+            )
+
+        access_token = data.get("token")
+        token_type = str(data.get("token_type", "bearer")).lower()
+        expires_dt = data.get("expires_dt")
+        if not access_token or not expires_dt:
+            raise AuthenticationError("토큰 응답에 필요한 값이 없습니다.")
+
+        record = TokenRecord(
+            access_token=access_token,
+            token_type=token_type,
+            expires_at=self._parse_kiwoom_expiry(expires_dt),
+            mode=self.mode,
+            profile=self.profile,
+            credential_fingerprint=self._credential_fingerprint(credentials),
+            saved_at=datetime.now(UTC),
+        )
+        self.token_store.save(record)
+        return record.access_token
+
+    def authorization_header(self) -> str:
+        return f"Bearer {self.get_access_token()}"
+
+    def clear_token(self) -> None:
+        self.token_store.clear(self.mode, profile=self.profile)
+
+    def recover_from_auth_failure(self) -> str:
+        self.clear_token()
+        return self.refresh_access_token()
+
+    def revoke_access_token(self) -> None:
+        record = self._load_cached_token_for_revoke()
+        if record is None:
+            raise AuthenticationError("폐기할 로컬 토큰 캐시가 없습니다. 먼저 토큰을 발급하거나 재발급해 주세요.")
+
+        credentials = self.secret_provider.get_credentials(self.mode)
+        if credentials is None:
+            raise CredentialsNotFoundError(self.mode)
+
+        response = requests.post(
+            f"{get_base_url(self.mode)}{REVOKE_PATH}",
+            json={
+                "appkey": credentials.appkey,
+                "secretkey": credentials.secretkey,
+                "token": record.access_token,
+            },
+            headers={"Content-Type": "application/json;charset=UTF-8"},
+            timeout=self.timeout_seconds,
+        )
+        data = _safe_json(response)
+        if response.status_code >= 400:
+            _raise_structured_error(
+                response.status_code,
+                data,
+                fallback_message="토큰 폐기 요청에 실패했습니다.",
+            )
+        if "return_code" not in data:
+            raise AuthenticationError("토큰 폐기 응답에 성공 여부가 없습니다.")
+        if data.get("return_code") != 0:
+            raise_for_error_code(
+                int(data["return_code"]),
+                str(data.get("return_msg", "토큰 폐기에 실패했습니다.")),
+            )
+
+        self.clear_token()
+
+    def status(self) -> AuthStatus:
+        credentials = self.secret_provider.get_credentials(self.mode)
+        token = None
+        token_warning = None
+        try:
+            inspect_token = getattr(self.token_store, "peek", self.token_store.load)
+            token = inspect_token(self.mode, profile=self.profile)
+        except (InvalidTokenCacheError, OSError) as exc:
+            token_warning = str(exc)
+            token = None
+
+        token_valid = token is not None and self._is_not_expired(token) and self._has_compatible_credentials(
+            token,
+            credentials,
+        )
+        token_reusable = token_valid and token is not None and self._is_valid(token)
+        if token_valid and not token_reusable:
+            token_warning = token_warning or "토큰 만료가 가까워 다음 요청에서 재발급될 수 있습니다."
+        return AuthStatus(
+            mode=self.mode,
+            profile=self.profile,
+            credential_source=credentials.source if credentials else None,
+            has_credentials=credentials is not None,
+            has_token=token is not None,
+            token_saved_at=token.saved_at if token else None,
+            token_expires_at=token.expires_at if token else None,
+            token_valid=token_valid,
+            token_reusable=token_reusable,
+            next_auth_action=self._next_auth_action(
+                token=token,
+                credentials=credentials,
+                token_reusable=token_reusable,
+            ),
+            token_warning=token_warning,
+        )
+
+    def _load_valid_token(self) -> TokenRecord | None:
+        try:
+            record = self.token_store.load(self.mode, profile=self.profile)
+        except (InvalidTokenCacheError, OSError):
+            return None
+        if record is None:
+            return None
+        if record.credential_fingerprint is None:
+            self.clear_token()
+            return None
+        credentials = self.secret_provider.get_credentials(self.mode)
+        if credentials is not None:
+            if not self._credentials_match(record, credentials):
+                self.clear_token()
+                return None
+        if not self._is_valid(record):
+            self.clear_token()
+            return None
+        return record
+
+    def _load_cached_token_for_revoke(self) -> TokenRecord | None:
+        inspect_token = getattr(self.token_store, "peek", self.token_store.load)
+        try:
+            record = inspect_token(self.mode, profile=self.profile)
+        except InvalidTokenCacheError as exc:
+            self.clear_token()
+            raise AuthenticationError("토큰 캐시가 손상되어 먼저 삭제했습니다. 필요하면 토큰을 다시 발급해 주세요.") from exc
+        except OSError:
+            return None
+        if record is None:
+            return None
+        if record.credential_fingerprint is None:
+            self.clear_token()
+            return None
+        credentials = self.secret_provider.get_credentials(self.mode)
+        if credentials is not None and not self._credentials_match(record, credentials):
+            self.clear_token()
+            return None
+        if not self._is_not_expired(record):
+            self.clear_token()
+            return None
+        return record
+
+    def _is_valid(self, record: TokenRecord) -> bool:
+        now_utc = datetime.now(UTC)
+        return now_utc < (record.expires_at - self.refresh_buffer)
+
+    def _is_not_expired(self, record: TokenRecord) -> bool:
+        return datetime.now(UTC) < record.expires_at
+
+    def _credentials_match(self, record: TokenRecord, credentials: CredentialSet) -> bool:
+        if record.credential_fingerprint is None:
+            return False
+        return record.credential_fingerprint == self._credential_fingerprint(credentials)
+
+    def _has_compatible_credentials(
+        self,
+        record: TokenRecord,
+        credentials: CredentialSet | None,
+    ) -> bool:
+        if record.credential_fingerprint is None:
+            return False
+        if credentials is None:
+            return True
+        return self._credentials_match(record, credentials)
+
+    def _next_auth_action(
+        self,
+        *,
+        token: TokenRecord | None,
+        credentials: CredentialSet | None,
+        token_reusable: bool,
+    ) -> NextAuthAction:
+        if token_reusable:
+            return "use_cached_token"
+        if credentials is None:
+            return "credentials_missing"
+        if token is None:
+            return "issue_before_request"
+        return "refresh_before_request"
+
+    @staticmethod
+    def _parse_kiwoom_expiry(value: str) -> datetime:
+        parsed = datetime.strptime(value, "%Y%m%d%H%M%S")
+        return parsed.replace(tzinfo=KST).astimezone(UTC)
+
+    @staticmethod
+    def _credential_fingerprint(credentials: CredentialSet) -> str:
+        raw = f"{credentials.appkey}:{credentials.secretkey}".encode("utf-8")
+        return hashlib.sha256(raw).hexdigest()
+
+
+def _safe_json(response: requests.Response) -> dict:
+    try:
+        payload = response.json()
+    except ValueError:
+        payload = {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def _raise_structured_error(status_code: int, payload: dict, *, fallback_message: str) -> None:
+    if payload.get("return_code") not in (None, 0):
+        raise_for_error_code(
+            int(payload["return_code"]),
+            str(payload.get("return_msg", fallback_message)),
+        )
+    raise HTTPRequestError(status_code, fallback_message)

kiwoom/core/client.py

@@ -0,0 +1,244 @@
+import time
+from collections.abc import Iterator
+from typing import Any
+
+import requests
+
+from kiwoom.core.auth import KiwoomAuth, get_base_url
+from kiwoom.core.errors import (
+    AUTH_RETRY_RETURN_CODES,
+    AuthenticationError,
+    HTTPRequestError,
+    normalize_return_code,
+)
+from kiwoom.core.types import Continuation, KiwoomResponse
+
+RESERVED_REQUEST_HEADERS = {"content-type", "api-id", "authorization"}
+
+
+class KiwoomClient:
+    def __init__(self, auth: KiwoomAuth, *, timeout_seconds: int = 30) -> None:
+        self.auth = auth
+        self.timeout_seconds = timeout_seconds
+        self.session = requests.Session()
+
+    def request(
+        self,
+        *,
+        api_url: str | None = None,
+        api: str | None = None,
+        api_id: str | None = None,
+        path: str | None = None,
+        body: dict[str, Any] | None = None,
+        method: str = "POST",
+        extra_headers: dict[str, str] | None = None,
+        retry_on_auth_failure: bool = True,
+    ) -> KiwoomResponse:
+        resolved_api_id, resolved_path = _resolve_api_target(
+            api_url=api_url,
+            api=api,
+            api_id=api_id,
+            path=path,
+        )
+        _validate_extra_headers(extra_headers)
+        headers = {
+            "Content-Type": "application/json;charset=UTF-8",
+            "api-id": resolved_api_id,
+            "authorization": self.auth.authorization_header(),
+        }
+        if extra_headers:
+            headers.update(extra_headers)
+
+        response = self.session.request(
+            method=method,
+            url=f"{get_base_url(self.auth.mode)}{resolved_path}",
+            headers=headers,
+            json=body or {},
+            timeout=self.timeout_seconds,
+        )
+
+        if response.status_code == 401 and retry_on_auth_failure:
+            self.auth.recover_from_auth_failure()
+            return self.request(
+                api_id=resolved_api_id,
+                path=resolved_path,
+                body=body,
+                method=method,
+                extra_headers=extra_headers,
+                retry_on_auth_failure=False,
+            )
+        if response.status_code == 401:
+            raise AuthenticationError("인증 정보를 갱신한 뒤 다시 시도했지만 요청에 실패했습니다.")
+
+        try:
+            data = response.json()
+        except ValueError as exc:
+            if response.status_code >= 400:
+                raise HTTPRequestError(response.status_code, "API 응답이 JSON 형식이 아닙니다.") from exc
+            data = {
+                "return_msg": "API 응답이 JSON 형식이 아닙니다.",
+                "raw_text": response.text,
+            }
+
+        return_code = normalize_return_code(data.get("return_code"))
+        if return_code in AUTH_RETRY_RETURN_CODES and retry_on_auth_failure:
+            self.auth.recover_from_auth_failure()
+            return self.request(
+                api_id=resolved_api_id,
+                path=resolved_path,
+                body=body,
+                method=method,
+                extra_headers=extra_headers,
+                retry_on_auth_failure=False,
+            )
+
+        if response.status_code >= 400:
+            message = str(data.get("return_msg", "API 요청에 실패했습니다."))
+            if return_code not in (None, 0):
+                message = f"{message} (return_code={data['return_code']})"
+            raise HTTPRequestError(response.status_code, message)
+        return _build_response(data, response.headers)
+
+    def fetch_page(
+        self,
+        *,
+        api_url: str | None = None,
+        api: str | None = None,
+        api_id: str | None = None,
+        path: str | None = None,
+        body: dict[str, Any] | None = None,
+        method: str = "POST",
+        cont_yn: str | None = None,
+        next_key: str | None = None,
+    ) -> KiwoomResponse:
+        """단일 페이지를 조회하고, 연속조회 cursor가 있으면 요청 헤더에 반영합니다."""
+        extra_headers: dict[str, str] = {}
+        if cont_yn is not None:
+            extra_headers["cont-yn"] = cont_yn
+        if next_key is not None:
+            extra_headers["next-key"] = next_key
+
+        return self.request(
+            api_url=api_url,
+            api=api,
+            api_id=api_id,
+            path=path,
+            body=body,
+            method=method,
+            extra_headers=extra_headers or None,
+        )
+
+    def iterate_pages(
+        self,
+        *,
+        api_url: str | None = None,
+        api: str | None = None,
+        api_id: str | None = None,
+        path: str | None = None,
+        body: dict[str, Any] | None = None,
+        method: str = "POST",
+        max_pages: int = 1,
+        page_delay_seconds: float = 0.2,
+    ) -> Iterator[KiwoomResponse]:
+        """연속조회 cursor를 따라 최대 ``max_pages`` 페이지를 순회합니다.
+
+        ``max_pages=0``은 서버가 continuation을 제공하는 동안 계속 조회합니다.
+        페이지 사이에는 ``page_delay_seconds``만큼 대기해 서버 요청 간격
+        정책을 지킵니다.
+        """
+        if max_pages < 0:
+            raise ValueError("max_pages must be 0 (unlimited) or a positive page count")
+        cont_yn: str | None = None
+        next_key: str | None = None
+        page_count = 0
+        while True:
+            response = self.fetch_page(
+                api_url=api_url,
+                api=api,
+                api_id=api_id,
+                path=path,
+                body=body,
+                method=method,
+                cont_yn=cont_yn,
+                next_key=next_key,
+            )
+            yield response
+            page_count += 1
+            if max_pages and page_count >= max_pages:
+                return
+            if not response.continuation.has_next:
+                return
+            cont_yn = response.continuation.cont_yn or "Y"
+            next_key = response.continuation.next_key or ""
+            if page_delay_seconds:
+                time.sleep(page_delay_seconds)
+
+
+def _validate_extra_headers(extra_headers: dict[str, str] | None) -> None:
+    if not extra_headers:
+        return
+
+    for header_name in extra_headers:
+        if header_name.lower() in RESERVED_REQUEST_HEADERS:
+            raise ValueError(f"extra_headers cannot override reserved header: {header_name}")
+
+
+def _resolve_api_target(
+    *,
+    api_url: str | None,
+    api: str | None,
+    api_id: str | None,
+    path: str | None,
+) -> tuple[str, str]:
+    if api_url is not None:
+        if api is not None or api_id is not None or path is not None:
+            raise ValueError("use only one of api_url, api, or api_id/path")
+        return _parse_api_url_target(api_url)
+
+    if api is not None:
+        if api_id is not None or path is not None:
+            raise ValueError("use only one of api_url, api, or api_id/path")
+        return _parse_api_target(api)
+
+    if not api_id or not path:
+        raise ValueError("api_id and path are required when api is not provided")
+    return api_id, path
+
+
+def _parse_api_url_target(api_url: str) -> tuple[str, str]:
+    normalized = api_url.strip()
+    if not normalized.startswith("/"):
+        raise ValueError("api_url must be in the format '<path>/<api_id>'")
+
+    path, _, api_id = normalized.rpartition("/")
+    if not path or not api_id:
+        raise ValueError("api_url must be in the format '<path>/<api_id>'")
+
+    return api_id, path
+
+
+def _parse_api_target(api: str) -> tuple[str, str]:
+    api_spec = api.strip()
+    parts = api_spec.split(maxsplit=1)
+    if len(parts) != 2:
+        raise ValueError("api must be in the format '<api_id> <path>'")
+
+    api_id, path = parts[0].strip(), parts[1].strip()
+    if not api_id or not path.startswith("/"):
+        raise ValueError("api must be in the format '<api_id> <path>'")
+    return api_id, path
+
+
+def _build_response(data: dict[str, Any], response_headers: Any) -> KiwoomResponse:
+    cont_yn = response_headers.get("cont-yn") or response_headers.get("Cont-Yn")
+    next_key = response_headers.get("next-key") or response_headers.get("Next-Key")
+    continuation = Continuation(
+        has_next=cont_yn == "Y",
+        next_key=next_key or None,
+        cont_yn=cont_yn or None,
+    )
+    return KiwoomResponse(
+        body=data,
+        continuation=continuation,
+        headers=dict(response_headers),
+    )