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/profile 명령어
├── client.py            # KiwoomClient — httpx 동기 클라이언트, 페이지네이션
├── api_spec.py          # API_REGISTRY (217개 REST API ID 매핑)
├── config.py            # 멀티 프로필, 키체인 저장, 레거시 형식 감지
├── auth.py              # 토큰 관리 (keyring)
├── output.py            # Rich Console 인스턴스
├── formatters.py        # 테이블/JSON/CSV 출력, 공유 헬퍼
├── streaming.py         # WebSocket 클라이언트
└── commands/
    ├── _constants.py    # 공유 룩업맵 (MARKET_ALL 등)
    ├── stock.py         # 종목 조회
    ├── account.py       # 계좌
    ├── order.py         # 주문
    ├── market.py        # 시장
    ├── stream.py        # 스트리밍 CLI
    ├── watch.py         # TUI 대시보드
    ├── dashboard.py     # 계좌+거래량 한화면
    └── us/              # 미국주식 (detect/order_ops/stock_ops/account_ops/exchange)

v2.1에서 secure_store.py(Fernet 암호화 계층)와 cryptography 의존성이 제거되었습니다. 인증정보는 config.py가 keyring으로 직접 저장합니다.

커맨드 추가 방법

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 (Python 3.10~3.13 매트릭스)
• Publish: v* 태그 push 시 PyPI 자동 배포
• Branch protection: main 브랜치는 PR + CI 통과 필요
• Code scanning: CodeQL 자동 실행

Test Suite

pytest tests/ -v                  # 246개 테스트
pytest tests/test_cli.py          # CLI 테스트
pytest tests/test_credentials.py  # 키체인 인증정보 테스트
pytest tests/test_migration.py    # 레거시 형식 마이그레이션 테스트

Scripts

• scripts/regen_excel.py — kiwoom_cli_commands.xlsx 재생성 (CLI 명령어 추가/변경 시 실행)

  python scripts/regen_excel.py

Community

• CODE_OF_CONDUCT.md — 행동 강령
• CONTRIBUTING.md — 기여 가이드
• SECURITY.md — 보안 정책 및 취약점 제보
• .github/ISSUE_TEMPLATE/ — 이슈 템플릿 (버그 리포트, 기능 요청)
• .github/pull_request_template.md — PR 템플릿

라이선스

v2.0부터 Source-Available License가 적용됩니다. 기여 시 CONTRIBUTING.md를 확인하세요.