kwcli 0.1.0__py3-none-any.whl

kiwoom_cli/commands/groups.py

@@ -0,0 +1,281 @@
+"""Table-driven registration for pure mapped command groups.
+
+Each ``MappedGroup`` row declares one market/group CLI subtree; registration
+order stays explicit in ``main.build_parser``. Groups with bespoke behavior
+(stocks, orders, streams, auth, spec) keep their own modules.
+"""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass, field
+
+from kiwoom_cli.commands.mapped import add_mapped_command_parsers, execute_mapped_rest_command
+from kiwoom_cli.output import ACCOUNT_REDACT_FIELDS
+
+
+@dataclass(frozen=True)
+class MappedGroup:
+    market: str
+    name: str
+    help_text: str
+    commands: tuple[tuple[str, str], ...]
+    redact_fields: tuple[str, ...] = field(default=())
+
+    @property
+    def cli_group(self) -> str:
+        """The ``cli_group`` key used in maps/api_commands.csv."""
+        if self.market == "domestic":
+            return self.name
+        return f"{self.market} {self.name}"
+
+    @property
+    def dest(self) -> str:
+        prefix = "" if self.market == "domestic" else f"{self.market}_"
+        return f"{prefix}{self.name.replace('-', '_')}_command"
+
+
+def add_group_parser(subparsers: argparse._SubParsersAction, group: MappedGroup) -> None:
+    group_parser = subparsers.add_parser(group.name, help=group.help_text)
+    group_subparsers = group_parser.add_subparsers(dest=group.dest, required=True)
+    add_mapped_command_parsers(
+        group_subparsers,
+        group=group.cli_group,
+        commands=group.commands,
+        handler=_make_handler(group),
+    )
+
+
+def _make_handler(group: MappedGroup):
+    def handler(args: argparse.Namespace) -> None:
+        execute_mapped_rest_command(
+            group=group.cli_group,
+            command=getattr(args, group.dest),
+            args=args,
+            redact_fields=group.redact_fields,
+        )
+
+    return handler
+
+
+DOMESTIC_GROUPS: dict[str, MappedGroup] = {
+    group.name: group
+    for group in (
+        MappedGroup(
+            market="domestic",
+            name="quotes",
+            help_text="현재가와 시세 조회 명령입니다.",
+            commands=(
+                ("price", "종목 현재가 시세를 조회합니다."),
+                ("balance", "프로그램매매 차익잔고 추이를 조회합니다."),
+                ("by-stock", "종목별 기관 매매 추이를 조회합니다."),
+                ("list", "신주인수권 전체 시세를 조회합니다."),
+                ("gold-price", "금현물 시세를 조회합니다."),
+                ("gold-fills", "금현물 체결 추이를 조회합니다."),
+                ("gold-daily", "금현물 일별 추이를 조회합니다."),
+                ("gold-expected", "금현물 예상체결을 조회합니다."),
+                ("multi-period", "주식 일/주/월/시/분 요약 시세를 조회합니다."),
+                ("intraday-minute", "주식 시분 시세를 조회합니다."),
+                ("institution-daily", "일별 기관 매매 종목을 조회합니다."),
+                ("strength-time", "체결강도 시간별 추이를 조회합니다."),
+                ("strength-daily", "체결강도 일별 추이를 조회합니다."),
+                ("investor-intraday", "장중 투자자별 매매를 조회합니다."),
+                ("investor-after-close", "장마감 후 투자자별 매매를 조회합니다."),
+                ("broker-trend", "증권사별 종목 매매 동향을 조회합니다."),
+                ("daily-price", "일별 주가를 조회합니다."),
+                ("after-hours", "시간외 단일가를 조회합니다."),
+                ("program-time", "프로그램매매 시간대별 추이를 조회합니다."),
+                ("program-cumulative", "프로그램매매 누적 추이를 조회합니다."),
+                ("program-by-stock", "종목 시간별 프로그램매매 추이를 조회합니다."),
+                ("program-daily", "프로그램매매 일자별 추이를 조회합니다."),
+                ("stock-program-daily", "종목 일별 프로그램매매 추이를 조회합니다."),
+            ),
+        ),
+        MappedGroup(
+            market="domestic",
+            name="orderbooks",
+            help_text="호가 조회 명령입니다.",
+            commands=(
+                ("list", "종목 호가를 조회합니다."),
+                ("gold", "금현물 호가를 조회합니다."),
+            ),
+        ),
+        MappedGroup(
+            market="domestic",
+            name="candles",
+            help_text="차트/캔들 조회 명령입니다.",
+            commands=(
+                ("daily", "종목 일봉 차트를 조회합니다."),
+                ("by-stock", "종목별 투자자/기관 차트를 조회합니다."),
+                ("lookup", "장중 투자자별 매매 차트를 조회합니다."),
+                ("stock-tick", "주식 틱 차트를 조회합니다."),
+                ("stock-minute", "주식 분봉 차트를 조회합니다."),
+                ("stock-weekly", "주식 주봉 차트를 조회합니다."),
+                ("stock-monthly", "주식 월봉 차트를 조회합니다."),
+                ("stock-yearly", "주식 년봉 차트를 조회합니다."),
+                ("sector-tick", "업종 틱 차트를 조회합니다."),
+                ("sector-minute", "업종 분봉 차트를 조회합니다."),
+                ("sector-daily", "업종 일봉 차트를 조회합니다."),
+                ("sector-weekly", "업종 주봉 차트를 조회합니다."),
+                ("sector-monthly", "업종 월봉 차트를 조회합니다."),
+                ("sector-yearly", "업종 년봉 차트를 조회합니다."),
+                ("gold-tick", "금현물 틱 차트를 조회합니다."),
+                ("gold-minute", "금현물 분봉 차트를 조회합니다."),
+                ("gold-daily", "금현물 일봉 차트를 조회합니다."),
+                ("gold-weekly", "금현물 주봉 차트를 조회합니다."),
+                ("gold-monthly", "금현물 월봉 차트를 조회합니다."),
+                ("gold-today-tick", "금현물 당일 틱 차트를 조회합니다."),
+                ("gold-today-minute", "금현물 당일 분봉 차트를 조회합니다."),
+            ),
+        ),
+        MappedGroup(
+            market="domestic",
+            name="etfs",
+            help_text="ETF 조회 명령입니다.",
+            commands=(
+                ("info", "ETF 종목정보를 조회합니다."),
+                ("daily", "ETF 일별추이를 조회합니다."),
+                ("profit", "ETF 수익률을 조회합니다."),
+                ("list", "ETF 전체 시세를 조회합니다."),
+                ("intraday-trend", "ETF 시간대별 추이를 조회합니다."),
+                ("intraday-fills", "ETF 시간대별 체결을 조회합니다."),
+                ("daily-fills", "ETF 일자별 체결을 조회합니다."),
+                ("nav", "ETF NAV 관련 정보를 조회합니다."),
+                ("foreign-trend", "ETF 외국인 순매수 추이를 조회합니다."),
+            ),
+        ),
+        MappedGroup(
+            market="domestic",
+            name="elws",
+            help_text="ELW 조회 명령입니다.",
+            commands=(
+                ("daily", "ELW 일별 민감도 지표를 조회합니다."),
+                ("balance", "ELW LP 보유 일별 추이를 조회합니다."),
+                ("conditions", "ELW 조건검색 결과를 조회합니다."),
+                ("sensitivity", "ELW 민감도 지표를 조회합니다."),
+                ("price-move", "ELW 가격 급등락을 조회합니다."),
+                ("broker-net", "거래원별 ELW 순매매 상위를 조회합니다."),
+                ("divergence", "ELW 괴리율을 조회합니다."),
+                ("change-rank", "ELW 등락율 순위를 조회합니다."),
+                ("balance-rank", "ELW 잔량 순위를 조회합니다."),
+                ("proximity", "ELW 근접율을 조회합니다."),
+                ("details", "ELW 종목 상세정보를 조회합니다."),
+            ),
+        ),
+        MappedGroup(
+            market="domestic",
+            name="investors",
+            help_text="기관/외국인 조회 명령입니다.",
+            commands=(
+                ("by-stock", "종목별 외국인 매매동향을 조회합니다."),
+                ("trend", "기관/외국인 연속매매 현황을 조회합니다."),
+                ("gold-status", "금현물 투자자 현황을 조회합니다."),
+            ),
+        ),
+        MappedGroup(
+            market="domestic",
+            name="rankings",
+            help_text="순위 정보 조회 명령입니다.",
+            commands=(
+                ("orderbook-balance", "호가잔량 상위를 조회합니다."),
+                ("orderbook-balance-spike", "호가잔량 급증을 조회합니다."),
+                ("balance-rate-spike", "잔량율 급증을 조회합니다."),
+                ("volume-spike", "거래량 급증을 조회합니다."),
+                ("previous-change-rate", "전일대비 등락률 상위를 조회합니다."),
+                ("list-fills", "예상체결 등락률 상위를 조회합니다."),
+                ("today-volume", "당일 거래량 상위를 조회합니다."),
+                ("previous-volume", "전일 거래량 상위를 조회합니다."),
+                ("amount", "거래대금 상위를 조회합니다."),
+                ("credit-ratio", "신용비율 상위를 조회합니다."),
+                ("foreign-period-trades", "외인 기간별 매매 상위를 조회합니다."),
+                ("foreign-continuous-net", "외인 연속 순매매 상위를 조회합니다."),
+                ("foreign-limit-usage", "외인 한도소진율 증가 상위를 조회합니다."),
+                ("foreign-broker-trades", "외국계 창구 매매 상위를 조회합니다."),
+                ("broker-by-stock", "종목별 증권사 순위를 조회합니다."),
+                ("broker-trades", "증권사별 매매 상위를 조회합니다."),
+                ("stock-main-brokers", "당일 주요 거래원을 조회합니다."),
+                ("net-buy-brokers", "순매수 거래원 순위를 조회합니다."),
+                ("top-exit-brokers", "당일 상위 이탈원을 조회합니다."),
+                ("same-net-trades", "동일 순매매 순위를 조회합니다."),
+                ("investor-intraday", "장중 투자자별 매매 상위를 조회합니다."),
+                ("after-hours-change-rate", "시간외 단일가 등락율 순위를 조회합니다."),
+                ("foreign-institution-trades", "외국인기관 매매 상위를 조회합니다."),
+            ),
+        ),
+        MappedGroup(
+            market="domestic",
+            name="sectors",
+            help_text="업종 조회 명령입니다.",
+            commands=(
+                ("program", "종목 기준 업종 프로그램 매매를 조회합니다."),
+                ("investor-flows", "업종별 투자자 순매수를 조회합니다."),
+                ("price", "업종 현재가를 조회합니다."),
+                ("stocks", "업종별 주가를 조회합니다."),
+                ("indices", "전업종 지수를 조회합니다."),
+                ("daily", "업종 현재가 일별 데이터를 조회합니다."),
+            ),
+        ),
+        MappedGroup(
+            market="domestic",
+            name="short-selling",
+            help_text="공매도 조회 명령입니다.",
+            commands=(("trend", "종목별 공매도 추이를 조회합니다."),),
+        ),
+        MappedGroup(
+            market="domestic",
+            name="securities-lending",
+            help_text="대차거래 조회 명령입니다.",
+            commands=(
+                ("by-stock", "종목별 대차거래 추이를 조회합니다."),
+                ("trend", "대차거래 추이를 조회합니다."),
+                ("list", "대차거래 상위 종목을 조회합니다."),
+                ("lookup", "대차거래 내역을 조회합니다."),
+            ),
+        ),
+        MappedGroup(
+            market="domestic",
+            name="themes",
+            help_text="테마 조회 명령입니다.",
+            commands=(
+                ("by-stock", "테마 구성 종목을 조회합니다."),
+                ("lookup", "테마 그룹을 조회합니다."),
+            ),
+        ),
+        MappedGroup(
+            market="domestic",
+            name="accounts",
+            help_text="계좌 조회 명령입니다.",
+            commands=(
+                ("list", "계좌번호 목록을 조회합니다."),
+                ("daily-balance-return", "일별잔고수익률을 조회합니다."),
+                ("realized-profit-stock-daily", "일자별 종목별 실현손익을 일자 기준으로 조회합니다."),
+                ("realized-profit-period-stock", "일자별 종목별 실현손익을 기간 기준으로 조회합니다."),
+                ("realized-profit-daily", "일자별 실현손익을 조회합니다."),
+                ("realized-profit-today-detail", "당일 실현손익 상세를 조회합니다."),
+                ("return-rate", "계좌수익률을 조회합니다."),
+                ("day-trading-log", "당일매매일지를 조회합니다."),
+                ("cash", "예수금 상세 현황을 조회합니다."),
+                ("estimated-assets-daily", "일별 추정예탁자산 현황을 조회합니다."),
+                ("assets", "추정자산을 조회합니다."),
+                ("valuation", "계좌평가 현황을 조회합니다."),
+                ("fill-balance", "체결잔고를 조회합니다."),
+                ("order-fill-detail", "계좌별 주문체결내역 상세를 조회합니다."),
+                ("next-settlement", "계좌별 익일결제 예정내역을 조회합니다."),
+                ("order-fill-status", "계좌별 주문체결 현황을 조회합니다."),
+                ("credit-margin", "신용보증금율별 주문가능수량을 조회합니다."),
+                ("margin-details", "증거금 세부내역을 조회합니다."),
+                ("transaction-history", "위탁종합 거래내역을 조회합니다."),
+                ("daily-return-detail", "일별 계좌수익률 상세현황을 조회합니다."),
+                ("today-status", "계좌별 당일현황을 조회합니다."),
+                ("holdings", "계좌평가 잔고내역을 조회합니다."),
+                ("gold-balance", "금현물 잔고를 조회합니다."),
+                ("gold-cash", "금현물 예수금을 조회합니다."),
+                ("gold-all-order-fills", "금현물 주문체결 전체를 조회합니다."),
+                ("gold-order-fills", "금현물 주문체결을 조회합니다."),
+                ("gold-transactions", "금현물 거래내역을 조회합니다."),
+                ("gold-open-orders", "금현물 미체결을 조회합니다."),
+            ),
+            redact_fields=ACCOUNT_REDACT_FIELDS,
+        ),
+    )
+}

kiwoom_cli/commands/mapped.py

@@ -0,0 +1,74 @@
+"""Shared helpers for mapped resource command modules."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from kiwoom_cli.argument_maps import add_mapped_arguments, build_body
+from kiwoom_cli.arguments import add_output_format_arg, add_pages_arg, add_runtime_args
+from kiwoom_cli.executor import execute_rest_command
+from kiwoom_cli.output import format_response
+from kiwoom_cli.registry import get_implemented_command
+
+
+CommandHelp = tuple[str, str]
+
+
+def add_mapped_command_parser(
+    subparsers: argparse._SubParsersAction,
+    *,
+    group: str,
+    command: str,
+    help_text: str,
+    handler: Callable[[argparse.Namespace], None],
+    parser_kwargs: dict[str, Any] | None = None,
+) -> argparse.ArgumentParser:
+    definition = get_implemented_command(group, command)
+    kwargs = {"help": help_text}
+    if parser_kwargs:
+        kwargs.update(parser_kwargs)
+    command_parser = subparsers.add_parser(command, **kwargs)
+    add_mapped_arguments(command_parser, definition.command_path)
+    add_pages_arg(command_parser)
+    add_output_format_arg(command_parser)
+    add_runtime_args(command_parser)
+    command_parser.set_defaults(handler=handler)
+    return command_parser
+
+
+def add_mapped_command_parsers(
+    subparsers: argparse._SubParsersAction,
+    *,
+    group: str,
+    commands: Iterable[CommandHelp],
+    handler: Callable[[argparse.Namespace], None],
+) -> None:
+    for command, help_text in commands:
+        add_mapped_command_parser(
+            subparsers,
+            group=group,
+            command=command,
+            help_text=help_text,
+            handler=handler,
+        )
+
+
+def execute_mapped_rest_command(
+    *,
+    group: str,
+    command: str,
+    args: argparse.Namespace,
+    redact_fields: Iterable[str] = (),
+) -> None:
+    definition = get_implemented_command(group, command)
+    body = build_body(definition.command_path, args)
+    response = execute_rest_command(
+        definition,
+        body=body,
+        mode=args.mode,
+        profile=args.profile,
+        pages=getattr(args, "pages", 1),
+    )
+    print(format_response(response, output_format=args.format, redact_fields=redact_fields))

kiwoom_cli/commands/orders.py

@@ -0,0 +1,158 @@
+"""Order commands."""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+
+from kiwoom_cli.argument_maps import add_mapped_arguments, build_body
+from kiwoom_cli.arguments import add_output_format_arg, add_runtime_args
+from kiwoom_cli.commands.mapped import (
+    add_mapped_command_parser,
+    execute_mapped_rest_command,
+)
+from kiwoom_cli.executor import execute_rest_command
+from kiwoom_cli.order_confirmation import (
+    build_order_confirmation,
+    format_order_confirmation,
+)
+from kiwoom_cli.output import ACCOUNT_REDACT_FIELDS, format_response
+from kiwoom_cli.registry import get_implemented_command
+
+
+@dataclass(frozen=True)
+class OrdersMarket:
+    group: str
+    dest: str
+    help_text: str
+    confirm_help: str
+    reads: tuple[tuple[str, str], ...]
+    writes: tuple[tuple[str, str], ...]
+
+
+DOMESTIC_ORDER_READS = (
+    ("chance", "주문 전 주문/인출 가능금액을 조회합니다."),
+    ("margin", "증거금율별 주문가능수량을 조회합니다."),
+    ("list-open", "미체결 주문을 조회합니다."),
+    ("list-fills", "체결 주문을 조회합니다."),
+    ("open-detail", "미체결 분할주문 상세를 조회합니다."),
+)
+
+DOMESTIC_ORDER_WRITES = (
+    ("buy", "매수 주문을 전송합니다 (--confirm 없으면 미전송 주문 확인)."),
+    ("sell", "매도 주문을 전송합니다 (--confirm 없으면 미전송 주문 확인)."),
+    ("modify", "정정 주문을 전송합니다 (--confirm 없으면 미전송 주문 확인)."),
+    ("cancel", "취소 주문을 전송합니다 (--confirm 없으면 미전송 주문 확인)."),
+    (
+        "credit-buy",
+        "신용 매수주문을 전송합니다 (--confirm 없으면 미전송 주문 확인).",
+    ),
+    (
+        "credit-sell",
+        "신용 매도주문을 전송합니다 (--confirm 없으면 미전송 주문 확인).",
+    ),
+    (
+        "credit-modify",
+        "신용 정정주문을 전송합니다 (--confirm 없으면 미전송 주문 확인).",
+    ),
+    (
+        "credit-cancel",
+        "신용 취소주문을 전송합니다 (--confirm 없으면 미전송 주문 확인).",
+    ),
+    (
+        "gold-buy",
+        "금현물 매수주문을 전송합니다 (--confirm 없으면 미전송 주문 확인).",
+    ),
+    (
+        "gold-sell",
+        "금현물 매도주문을 전송합니다 (--confirm 없으면 미전송 주문 확인).",
+    ),
+    (
+        "gold-modify",
+        "금현물 정정주문을 전송합니다 (--confirm 없으면 미전송 주문 확인).",
+    ),
+    (
+        "gold-cancel",
+        "금현물 취소주문을 전송합니다 (--confirm 없으면 미전송 주문 확인).",
+    ),
+)
+
+ORDER_MARKETS: dict[str, OrdersMarket] = {
+    "domestic": OrdersMarket(
+        group="orders",
+        dest="orders_command",
+        help_text="주문 조회 및 주문 전송(--confirm) 명령입니다.",
+        confirm_help="지정하면 실제 주문을 전송합니다. 미지정 시 미전송 주문 확인을 출력합니다.",
+        reads=DOMESTIC_ORDER_READS,
+        writes=DOMESTIC_ORDER_WRITES,
+    ),
+}
+
+
+def add_orders_parser(
+    subparsers: argparse._SubParsersAction, market: str = "domestic"
+) -> None:
+    market_table = ORDER_MARKETS[market]
+    orders_parser = subparsers.add_parser("orders", help=market_table.help_text)
+    orders_subparsers = orders_parser.add_subparsers(
+        dest=market_table.dest, required=True
+    )
+
+    for command, help_text in market_table.reads:
+        command_parser = add_mapped_command_parser(
+            orders_subparsers,
+            group=market_table.group,
+            command=command,
+            help_text=help_text,
+            handler=handle_order_read,
+        )
+        command_parser.set_defaults(
+            order_command=command, orders_group=market_table.group
+        )
+
+    for command, help_text in market_table.writes:
+        definition = get_implemented_command(market_table.group, command)
+        command_parser = orders_subparsers.add_parser(command, help=help_text)
+        add_mapped_arguments(command_parser, definition.command_path)
+        command_parser.add_argument(
+            "--confirm",
+            action="store_true",
+            help=market_table.confirm_help,
+        )
+        add_output_format_arg(command_parser)
+        add_runtime_args(command_parser)
+        command_parser.set_defaults(
+            handler=handle_order_submit,
+            order_command=command,
+            orders_group=market_table.group,
+        )
+
+
+def handle_order_read(args: argparse.Namespace) -> None:
+    execute_mapped_rest_command(
+        group=args.orders_group,
+        command=args.order_command,
+        args=args,
+        redact_fields=ACCOUNT_REDACT_FIELDS,
+    )
+
+
+def handle_order_submit(args: argparse.Namespace) -> None:
+    definition = get_implemented_command(args.orders_group, args.order_command)
+    body = build_body(definition.command_path, args)
+    if not args.confirm:
+        payload = build_order_confirmation(definition, args)
+        print(format_order_confirmation(payload, output_format=args.format))
+        return
+    response = execute_rest_command(
+        definition,
+        body=body,
+        mode=args.mode,
+        profile=args.profile,
+        confirm=True,
+    )
+    print(
+        format_response(
+            response, output_format=args.format, redact_fields=ACCOUNT_REDACT_FIELDS
+        )
+    )

kiwoom_cli/commands/spec.py

@@ -0,0 +1,98 @@
+"""Spec search commands."""
+
+from __future__ import annotations
+
+import argparse
+
+from kiwoom.specs import (
+    format_api_groups,
+    format_api_spec,
+    format_api_summaries,
+    format_search_results,
+    get_api_spec,
+    list_api_groups,
+    list_api_summaries,
+    search_api_specs,
+)
+from kiwoom_cli.output import format_payload
+
+
+def add_spec_parser(subparsers: argparse._SubParsersAction) -> None:
+    spec_parser = subparsers.add_parser("spec", help="API 스펙을 검색합니다.")
+    spec_subparsers = spec_parser.add_subparsers(dest="spec_command", required=True)
+
+    search_parser = spec_subparsers.add_parser(
+        "search", help="API ID, 이름, 요청 필드로 스펙을 검색합니다."
+    )
+    search_parser.add_argument("query", help="검색어")
+    search_parser.add_argument("--limit", type=_positive_int, default=10, help="최대 결과 수")
+    search_parser.set_defaults(handler=handle_spec_search)
+
+    show_parser = spec_subparsers.add_parser("show", help="API ID로 스펙 상세를 표시합니다.")
+    show_parser.add_argument("api_id", help="API ID")
+    show_parser.add_argument(
+        "--format", choices=("pretty", "json", "yaml"), default="pretty", help="출력 형식"
+    )
+    show_parser.set_defaults(handler=handle_spec_show)
+
+    groups_parser = spec_subparsers.add_parser("groups", help="API 그룹과 API 수를 표시합니다.")
+    groups_parser.add_argument(
+        "--format", choices=("pretty", "json", "yaml"), default="pretty", help="출력 형식"
+    )
+    groups_parser.set_defaults(handler=handle_spec_groups)
+
+    apis_parser = spec_subparsers.add_parser("apis", help="API 목록을 표시합니다.")
+    apis_parser.add_argument("--group", help="메뉴 경로에 포함될 그룹명")
+    apis_parser.add_argument("--limit", type=_positive_int, help="최대 결과 수")
+    apis_parser.add_argument(
+        "--format", choices=("pretty", "json", "yaml"), default="pretty", help="출력 형식"
+    )
+    apis_parser.set_defaults(handler=handle_spec_apis)
+
+
+def handle_spec_search(args: argparse.Namespace) -> None:
+    results = search_api_specs(args.query, limit=args.limit)
+    print(format_search_results(results))
+
+
+def handle_spec_show(args: argparse.Namespace) -> None:
+    api_payload = get_api_spec(args.api_id)
+    print(
+        _format_spec_payload(
+            api_payload, output_format=args.format, pretty_formatter=format_api_spec
+        )
+    )
+
+
+def handle_spec_groups(args: argparse.Namespace) -> None:
+    groups = list_api_groups()
+    print(
+        _format_spec_payload(
+            groups, output_format=args.format, pretty_formatter=format_api_groups
+        )
+    )
+
+
+def handle_spec_apis(args: argparse.Namespace) -> None:
+    apis = list_api_summaries(group=args.group, limit=args.limit)
+    print(
+        _format_spec_payload(
+            apis, output_format=args.format, pretty_formatter=format_api_summaries
+        )
+    )
+
+
+def _format_spec_payload(payload, *, output_format: str, pretty_formatter) -> str:
+    if output_format == "pretty":
+        return pretty_formatter(payload)
+    return format_payload(payload, output_format=output_format)
+
+
+def _positive_int(value: str) -> int:
+    try:
+        parsed = int(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("--limit 값은 정수여야 합니다.") from exc
+    if parsed <= 0:
+        raise argparse.ArgumentTypeError("--limit 값은 0보다 커야 합니다.")
+    return parsed