kwcli 0.1.0__py3-none-any.whl

kiwoom/realtime/schemas.py

@@ -0,0 +1,76 @@
+"""Schema registry for Kiwoom realtime WebSocket values.
+
+The packaged Kiwoom API spec is the source of truth. This module exposes the
+spec rows under ``REAL``/``data[*].values`` as a registry that decoders can read
+without embedding FID-specific branching in decode logic.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import Any
+
+
+RealtimeField = dict[str, str]
+RealtimeSchema = dict[str, Any]
+
+
+@lru_cache(maxsize=1)
+def realtime_schemas() -> dict[str, RealtimeSchema]:
+    """Return built-in realtime schemas keyed by realtime type/API ID."""
+    from kiwoom.specs import load_api_specs
+
+    schemas: dict[str, RealtimeSchema] = {}
+    for api_id, payload in load_api_specs().items():
+        fields = _extract_value_fields(payload)
+        if not fields:
+            continue
+        meta = payload.get("meta", {})
+        api_name = str(meta.get("API 명", "")).strip()
+        schemas[api_id] = {
+            "event": api_id,
+            "name": api_name,
+            "fields": fields,
+        }
+    return schemas
+
+
+def get_realtime_schema(real_type: str) -> RealtimeSchema | None:
+    """Return a realtime schema for *real_type*, or ``None`` if unknown."""
+    return realtime_schemas().get(str(real_type).strip())
+
+
+def _extract_value_fields(payload: dict[str, Any]) -> dict[str, RealtimeField]:
+    fields: dict[str, RealtimeField] = {}
+    seen_names: set[str] = set()
+    in_values = False
+    for row in payload.get("response", {}).get("body", []):
+        element = str(row.get("element", "")).strip()
+        depth = row.get("depth")
+        if element == "values" and depth == 1:
+            in_values = True
+            continue
+        if not in_values:
+            continue
+        if depth == 2 and element:
+            korean_name = str(row.get("한글명", "")).strip()
+            if korean_name:
+                field_name = (
+                    korean_name
+                    if korean_name not in seen_names
+                    else f"{korean_name}_{element}"
+                )
+                seen_names.add(field_name)
+                fields[element] = {
+                    # The current official spec provides Korean display names,
+                    # not English field identifiers. Keep the explicit spec name
+                    # as the stable v1 named key instead of guessing. When the
+                    # spec repeats a display name in one schema, suffix the FID
+                    # so named decoding cannot overwrite a previous value.
+                    "name": field_name,
+                    "ko": korean_name,
+                    "type": str(row.get("type", "")).strip() or "String",
+                }
+        elif isinstance(depth, int) and depth <= 1:
+            in_values = False
+    return fields

kiwoom/realtime/stream.py

@@ -0,0 +1,213 @@
+"""In-process pub/sub and collection helpers for Kiwoom realtime streams.
+
+These utilities are API-agnostic. Callers provide the realtime client, the
+control packet(s) to send, and an optional ``{fid: label}`` column map. Message
+decoding and topic routing reuse :mod:`kiwoom.realtime.events`, so examples only
+need to declare their column map and the consumers/topics they care about.
+
+Two delivery models are provided:
+
+* :func:`collect_realtime` - await a bounded number of events and return them as
+  DataFrames or JSON (one-shot collection).
+* :func:`run_pubsub` - fan a single live stream out to multiple topic consumers
+  via an in-process :class:`AsyncPubSub`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections import defaultdict
+from collections.abc import Awaitable, Callable, Mapping
+from typing import Any
+
+import pandas as pd
+
+from kiwoom.realtime.events import (
+    is_terminal_event,
+    normalize_message_events,
+    resolve_topic,
+    topic_fanout,
+)
+
+Consumer = Callable[["asyncio.Queue[Any]"], Awaitable[None]]
+
+
+class AsyncPubSub:
+    """Minimal in-process pub/sub built on ``asyncio.Queue``.
+
+    No external broker (Redis/Kafka) is involved: one received message can be
+    fanned out to several consumers, each reading from its own queue.
+    """
+
+    def __init__(self) -> None:
+        self._subscribers: dict[str, list[asyncio.Queue[Any]]] = defaultdict(list)
+
+    def subscribe(self, topic: str) -> "asyncio.Queue[Any]":
+        """Register interest in *topic* and return the queue to read from."""
+        queue: asyncio.Queue[Any] = asyncio.Queue()
+        self._subscribers[topic].append(queue)
+        return queue
+
+    async def publish(self, topic: str, message: Any) -> None:
+        """Deliver *message* to every queue subscribed to *topic*."""
+        for queue in self._subscribers.get(topic, []):
+            await queue.put(message)
+
+
+def event_to_dataframe(event: dict[str, Any]) -> pd.DataFrame:
+    """Convert one decoded event into a single-row DataFrame."""
+    return pd.DataFrame([event])
+
+
+async def _publish_stream(
+    client: Any,
+    *,
+    api_url: str,
+    bodies: dict[str, Any] | list[dict[str, Any]],
+    columns: dict[str, str],
+    pubsub: AsyncPubSub,
+    max_messages: int | None,
+    close_client: bool,
+) -> None:
+    body_list = [bodies] if isinstance(bodies, dict) else list(bodies)
+    published_realtime = 0
+    try:
+        if not client.is_connected:
+            await client.connect(api_url=api_url)
+        for body in body_list:
+            await client.send(body)
+
+        async for message in client.iter_messages():
+            for event in normalize_message_events(message, columns):
+                for topic in topic_fanout(resolve_topic(event)):
+                    await pubsub.publish(topic, event)
+
+                if str(event.get("trnm", "")).upper() == "REAL":
+                    published_realtime += 1
+                    if max_messages is not None and published_realtime >= max_messages:
+                        return
+
+                if is_terminal_event(event):
+                    return
+    finally:
+        if close_client:
+            await client.close()
+
+
+async def run_pubsub(
+    client: Any,
+    *,
+    api_url: str,
+    bodies: dict[str, Any] | list[dict[str, Any]],
+    consumers: Mapping[str, Consumer],
+    columns: Mapping[str, str] | None = None,
+    pubsub: AsyncPubSub | None = None,
+    max_messages: int | None = None,
+    close_client: bool = True,
+) -> None:
+    """Fan a live Kiwoom realtime stream out to topic *consumers*.
+
+    Each ``{topic: consumer}`` pair gets its own queue; the publisher decodes
+    every received message, routes it to the matching topics (plus the shared
+    ``kiwoom.realtime`` / ``kiwoom.all`` fan-out), and the consumers run as
+    background tasks until the stream ends.
+
+    Args:
+        client: A connected-or-connectable realtime WebSocket client.
+        api_url: Realtime WebSocket API path.
+        bodies: One ``REG`` packet, or a list to combine several on one
+            connection.
+        consumers: ``{topic: async consumer(queue)}`` mapping.
+        columns: Optional ``{fid: label}`` map applied to realtime values.
+        pubsub: Optional shared bus (inject to combine with other streams).
+        max_messages: Stop after this many ``REAL`` events (None = unlimited).
+        close_client: Close *client* when the stream ends.
+    """
+    bus = pubsub or AsyncPubSub()
+    tasks = [
+        asyncio.create_task(consumer(bus.subscribe(topic)))
+        for topic, consumer in consumers.items()
+    ]
+    try:
+        await _publish_stream(
+            client,
+            api_url=api_url,
+            bodies=bodies,
+            columns=dict(columns or {}),
+            pubsub=bus,
+            max_messages=max_messages,
+            close_client=close_client,
+        )
+    finally:
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+
+def _format_collected(
+    rows: list[dict[str, Any]],
+    system_rows: list[dict[str, Any]],
+    output: str,
+) -> pd.DataFrame | dict[str, Any] | list[dict[str, Any]]:
+    if output == "json":
+        if rows and system_rows:
+            return {"system": system_rows, "data": rows}
+        return rows or system_rows
+    result: dict[str, pd.DataFrame] = {"data": pd.DataFrame(rows)}
+    if system_rows:
+        result["system"] = pd.DataFrame(system_rows)
+    return result
+
+
+async def collect_realtime(
+    client: Any,
+    *,
+    api_url: str,
+    body: dict[str, Any],
+    columns: Mapping[str, str] | None = None,
+    output: str = "dataframe",
+    max_messages: int = 10,
+) -> pd.DataFrame | dict[str, Any] | list[dict[str, Any]]:
+    """Collect up to *max_messages* realtime events, then return them.
+
+    REAL events are decoded through *columns* and collected as data rows; other
+    frames (REG/SYSTEM/...) are printed and collected separately. Collection
+    stops at *max_messages* data rows or on a terminal frame.
+
+    Args:
+        client: A connectable realtime WebSocket client.
+        api_url: Realtime WebSocket API path.
+        body: The ``REG`` packet to send.
+        columns: Optional ``{fid: label}`` map applied to realtime values.
+        output: ``"dataframe"`` or ``"json"``.
+        max_messages: Maximum number of REAL events to collect.
+
+    Returns:
+        ``{"data": ..., "system": ...}`` (DataFrames) or the JSON equivalent.
+    """
+    if max_messages < 1:
+        raise ValueError("max_messages must be greater than 0")
+    column_map = dict(columns or {})
+    rows: list[dict[str, Any]] = []
+    system_rows: list[dict[str, Any]] = []
+    try:
+        await client.subscribe(api_url=api_url, body=body)
+
+        async for message in client.iter_messages():
+            for event in normalize_message_events(message, column_map):
+                if str(event.get("trnm", "")).upper() == "REAL":
+                    rows.append(
+                        {key: value for key, value in event.items() if key != "trnm"}
+                    )
+                    if len(rows) >= max_messages:
+                        return _format_collected(rows, system_rows, output)
+                    continue
+
+                system_rows.append(event)
+                print(f"[{event.get('trnm') or 'MESSAGE'}]", event, flush=True)
+                if is_terminal_event(event):
+                    return _format_collected(rows, system_rows, output)
+    finally:
+        await client.close()
+
+    return _format_collected(rows, system_rows, output)

kiwoom/specs.py

@@ -0,0 +1,272 @@
+import json
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_SPEC_PATH = files("kiwoom").joinpath("_data", "kiwoom_api_spec.json")
+
+
+def load_api_specs(spec_path: Path | None = None) -> dict[str, dict[str, Any]]:
+    resolved_path = spec_path or DEFAULT_SPEC_PATH
+    payload = json.loads(resolved_path.read_text(encoding="utf-8"))
+    return {
+        str(api_payload.get("meta", {}).get("API ID", "")).strip(): api_payload
+        for api_payload in payload.get("apis", {}).values()
+        if str(api_payload.get("meta", {}).get("API ID", "")).strip()
+    }
+
+
+def load_search_entries(spec_path: Path | None = None) -> list[dict[str, object]]:
+    entries: list[dict[str, object]] = []
+
+    for api_payload in load_api_specs(spec_path).values():
+        meta = api_payload.get("meta", {})
+        request = api_payload.get("request", {})
+        request_terms: list[str] = []
+
+        for item in request.get("header", []):
+            request_terms.extend(_collect_item_terms(item))
+
+        for item in request.get("body", []):
+            request_terms.extend(_collect_item_terms(item))
+
+        response = api_payload.get("response", {})
+        response_terms: list[str] = []
+
+        for item in response.get("body", []):
+            if str(item.get("element", "")).strip() in _COMMON_RESPONSE_FIELDS:
+                continue
+            response_terms.extend(_collect_item_terms(item))
+
+        entries.append(
+            {
+                "api_id": str(meta.get("API ID", "")).strip(),
+                "api_name": str(meta.get("API 명", "")).strip(),
+                "menu_path": str(meta.get("메뉴 위치", "")).strip(),
+                "url": str(meta.get("URL", "")).strip(),
+                "method": str(meta.get("Method", "")).strip(),
+                "request_terms": list(dict.fromkeys(term for term in request_terms if term)),
+                "response_terms": list(dict.fromkeys(term for term in response_terms if term)),
+            }
+        )
+
+    return entries
+
+
+def get_api_spec(api_id: str, *, spec_path: Path | None = None) -> dict[str, Any]:
+    normalized_api_id = api_id.strip()
+    specs = load_api_specs(spec_path)
+    try:
+        return specs[normalized_api_id]
+    except KeyError as exc:
+        raise ValueError(f"알 수 없는 Kiwoom API ID입니다: {normalized_api_id}") from exc
+
+
+def list_api_groups(*, spec_path: Path | None = None) -> list[dict[str, object]]:
+    counts: dict[tuple[str, str], int] = {}
+    for api_payload in load_api_specs(spec_path).values():
+        major, subcategory = _split_menu_path(str(api_payload.get("meta", {}).get("메뉴 위치", "")))
+        key = (major, subcategory)
+        counts[key] = counts.get(key, 0) + 1
+    return [
+        {"major_category": major, "subcategory": subcategory, "count": count}
+        for (major, subcategory), count in sorted(counts.items())
+    ]
+
+
+def list_api_summaries(
+    *,
+    group: str | None = None,
+    spec_path: Path | None = None,
+    limit: int | None = None,
+) -> list[dict[str, object]]:
+    normalized_group = group.strip().casefold() if group else None
+    summaries: list[dict[str, object]] = []
+    for api_payload in load_api_specs(spec_path).values():
+        meta = api_payload.get("meta", {})
+        menu_path = str(meta.get("메뉴 위치", "")).strip()
+        if normalized_group and normalized_group not in menu_path.casefold():
+            continue
+        summaries.append(
+            {
+                "api_id": str(meta.get("API ID", "")).strip(),
+                "api_name": str(meta.get("API 명", "")).strip(),
+                "menu_path": menu_path,
+                "method": str(meta.get("Method", "")).strip(),
+                "url": str(meta.get("URL", "")).strip(),
+            }
+        )
+    summaries.sort(key=lambda item: str(item["api_id"]))
+    if limit is not None:
+        return summaries[:limit]
+    return summaries
+
+
+def search_api_specs(query: str, *, spec_path: Path | None = None, limit: int = 10) -> list[dict[str, object]]:
+    return search_entries(load_search_entries(spec_path), query=query, limit=limit)
+
+
+def search_entries(entries: list[dict[str, object]], *, query: str, limit: int = 10) -> list[dict[str, object]]:
+    if limit <= 0:
+        raise ValueError("limit 값은 0보다 커야 합니다.")
+
+    normalized_query = query.strip().casefold()
+    if not normalized_query:
+        return []
+
+    query_tokens = [token for token in normalized_query.split() if token]
+    scored: list[tuple[int, dict[str, object]]] = []
+
+    for entry in entries:
+        score = _score_entry(entry, normalized_query, query_tokens)
+        if score <= 0:
+            continue
+        scored.append((score, entry))
+
+    scored.sort(key=lambda item: (-item[0], str(item[1]["api_id"])))
+    return [entry for _, entry in scored[:limit]]
+
+
+def format_search_results(results: list[dict[str, object]]) -> str:
+    if not results:
+        return "검색 결과가 없습니다."
+
+    lines: list[str] = []
+    for entry in results:
+        request_terms = ", ".join(str(term) for term in entry["request_terms"][:6])
+        response_terms = ", ".join(str(term) for term in entry.get("response_terms", [])[:6])
+        lines.extend(
+            [
+                f'{entry["api_id"]} | {entry["api_name"]}',
+                f'  메뉴: {entry["menu_path"]}',
+                f'  호출: {entry["method"]} {entry["url"]}',
+                f"  요청 키워드: {request_terms or '-'}",
+                f"  응답 키워드: {response_terms or '-'}",
+            ]
+        )
+    return "\n".join(lines)
+
+
+def format_api_groups(groups: list[dict[str, object]]) -> str:
+    if not groups:
+        return "API 그룹이 없습니다."
+    return "\n".join(
+        f'{group["major_category"]} > {group["subcategory"]}: {group["count"]}'
+        for group in groups
+    )
+
+
+def format_api_summaries(summaries: list[dict[str, object]]) -> str:
+    if not summaries:
+        return "API 목록이 없습니다."
+    return "\n".join(
+        f'{entry["api_id"]} | {entry["api_name"]} | {entry["method"]} {entry["url"]} | {entry["menu_path"]}'
+        for entry in summaries
+    )
+
+
+def format_api_spec(api_payload: dict[str, Any]) -> str:
+    meta = api_payload.get("meta", {})
+    request = api_payload.get("request", {})
+    response = api_payload.get("response", {})
+    lines = [
+        f'{str(meta.get("API ID", "")).strip()} | {str(meta.get("API 명", "")).strip()}',
+        f'  메뉴: {str(meta.get("메뉴 위치", "")).strip()}',
+        f'  호출: {str(meta.get("Method", "")).strip()} {str(meta.get("URL", "")).strip()}',
+        f"  요청 헤더 필수: {_format_fields(_required_items(request.get('header')))}",
+        f"  요청 바디 필수: {_format_fields(_required_items(request.get('body')))}",
+        f"  요청 바디 선택: {_format_fields(_optional_items(request.get('body')))}",
+        f"  응답 바디: {_format_fields(response.get('body', []))}",
+    ]
+    return "\n".join(lines)
+
+
+_COMMON_HEADER_FIELDS = frozenset({"api-id", "authorization", "cont-yn", "next-key"})
+_COMMON_RESPONSE_FIELDS = frozenset({"return_code", "return_msg", "trnm", "data", "type", "name", "item", "values"})
+
+
+def _split_menu_path(menu_path: str) -> tuple[str, str]:
+    parts = [part.strip() for part in menu_path.split(">") if part.strip()]
+    if not parts:
+        return ("미분류", "미분류")
+    if len(parts) == 1:
+        return (parts[0], "미분류")
+    return (parts[0], parts[1])
+
+
+def _required_items(items: list[dict] | None) -> list[dict]:
+    return [item for item in items or [] if item.get("required") == "Y"]
+
+
+def _optional_items(items: list[dict] | None) -> list[dict]:
+    return [item for item in items or [] if item.get("required") != "Y"]
+
+
+def _format_fields(items: list[dict]) -> str:
+    fields = []
+    for item in items:
+        element = str(item.get("element", "")).strip()
+        if not element:
+            continue
+        korean_name = str(item.get("한글명", "")).strip()
+        field_type = str(item.get("type", "")).strip()
+        label = element
+        if korean_name:
+            label = f"{label}({korean_name})"
+        if field_type:
+            label = f"{label}:{field_type}"
+        fields.append(label)
+    return ", ".join(fields) if fields else "-"
+
+
+def _collect_item_terms(item: dict) -> list[str]:
+    element = str(item.get("element", "")).strip()
+    if element in _COMMON_HEADER_FIELDS:
+        return []
+    terms = [element, str(item.get("한글명", "")).strip()]
+    description = _normalize_description(str(item.get("description", "")).strip())
+    if description and len(description) <= 30:
+        terms.append(description)
+    return terms
+
+
+def _score_entry(entry: dict[str, object], normalized_query: str, query_tokens: list[str]) -> int:
+    api_id = str(entry["api_id"])
+    api_name = str(entry["api_name"])
+    menu_path = str(entry["menu_path"])
+    url = str(entry["url"])
+    request_terms = [str(term) for term in entry["request_terms"]]
+    response_terms = [str(term) for term in entry.get("response_terms", [])]
+
+    score = 0
+    if api_id.casefold() == normalized_query:
+        score += 1000
+    if normalized_query in api_id.casefold():
+        score += 250
+    if normalized_query in api_name.casefold():
+        score += 180
+    if normalized_query in menu_path.casefold():
+        score += 120
+    if normalized_query in url.casefold():
+        score += 80
+
+    for term in request_terms:
+        if normalized_query in term.casefold():
+            score += 40
+
+    for term in response_terms:
+        if normalized_query in term.casefold():
+            score += 30
+
+    searchable_text = " ".join([api_id, api_name, menu_path, url, *request_terms, *response_terms]).casefold()
+    if query_tokens and all(token in searchable_text for token in query_tokens):
+        score += 60
+
+    return score
+
+
+def _normalize_description(description: str) -> str:
+    if not description:
+        return ""
+    return " ".join(part.strip() for part in description.splitlines() if part.strip())