Development

개발 가이드

개발 환경 설정

git clone https://github.com/gejyn14/kiwoom-cli.git
cd kiwoom-cli
pip install -e ".[dev]"

프로젝트 구조

kiwoom_cli/
├── __init__.py          # 버전 (유일한 소스)
├── main.py              # CLI 엔트리포인트, config/auth 명령어
├── client.py            # KiwoomClient — httpx 동기 클라이언트
├── api_spec.py          # API_REGISTRY (207개 API ID 매핑)
├── config.py            # 멀티 프로필, SecureStore 연동
├── auth.py              # 토큰 관리 (keyring)
├── secure_store.py      # Fernet 암호화 키체인
├── output.py            # Rich Console 인스턴스
├── formatters.py        # 테이블/JSON/CSV 출력, 공유 헬퍼
├── streaming.py         # WebSocket 클라이언트
└── commands/
    ├── _constants.py    # 공유 룩업맵 (MARKET_ALL 등)
    ├── stock.py         # 종목 조회 (57개)
    ├── account.py       # 계좌 (27개)
    ├── order.py         # 주문 (22개)
    ├── market.py        # 시장 (76개)
    ├── stream.py        # 스트리밍 CLI (22개)
    ├── watch.py         # TUI 대시보드
    └── dashboard.py     # 계좌+거래량 한화면

커맨드 추가 방법

1. API ID 등록 (api_spec.py)

"ka99999": ("/api/new/endpoint", "새 API 설명"),

2. 커맨드 작성

from ..client import KiwoomClient
from ..formatters import print_api_response

@group.command("new-cmd")
@click.argument("code")
def new_cmd(code: str):
    """새 명령어 설명. (ka99999)"""
    with KiwoomClient() as c:
        data, _ = c.request("ka99999", {"stk_cd": code})
        print_api_response(data, title="새 데이터")

3. 옵션 규칙

• --from/--to: 날짜 범위
• --date: 단일 날짜
• --market: _constants.MARKET_ALL 사용
• --exchange: _constants.EXCHANGE_TWO 사용
• 함수 내 인라인 dict 금지

4. 테스트 추가

pytest tests/ -v
ruff check kiwoom_cli/

코드 스타일

• Python 3.10+ 타입 힌트 (X | None)
• from __future__ import annotations 모든 파일
• ruff 린터
• 한국어 docstring, 영어 코드
• 버전: __init__.py만 수정 (pyproject.toml은 dynamic)

CI/CD

• CI: pytest + ruff on push/PR
• Publish: v* 태그 push 시 PyPI 자동 배포