Metadata-Version: 2.4
Name: krx-hj3415
Version: 2.4.2
Summary: KRX300 code scraper
Keywords: example,demo
Author-email: Hyungjin Kim <hj3415@gmail.com>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Typing :: Typed
License-File: LICENSE
Requires-Dist: requests>=2.32.5
Requires-Dist: pandas>=2.3.3
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: xlrd>=2.0.2
Requires-Dist: typer>=0.21.1
Requires-Dist: db2-hj3415
Requires-Dist: logging-hj3415
Requires-Dist: contracts-hj3415
Requires-Dist: common-hj3415

# krx-hj3415 README

`krx-hj3415`는 KRX 유니버스(현재 `krx300`)를 수집하고, DB의 기존 최신 데이터와 비교(diff)해서 `latest`/`snapshot`을 갱신하는 CLI 프로젝트입니다.

`pyproject.toml` 기준:
- 패키지명: `krx-hj3415`
- 버전: `2.4.0`
- Python: `>=3.11`
- CLI 엔트리포인트: `krx = krx_hj3415.cli:app`

## 1. 프로젝트 기능 설명

이 프로젝트의 핵심 기능은 `krx sync` 명령 하나로 정리됩니다.

1. 외부 소스에서 KRX300 종목 목록을 수집
2. DB의 기존 universe latest와 비교(diff)
3. universe latest 저장
4. 옵션에 따라 universe snapshot 저장
5. 옵션에 따라 제거된 종목을 NFS 저장소에서도 실제 삭제

즉, 유니버스 동기화와 정리 작업을 한 번에 수행하는 운영용 CLI입니다.

## 2. 프로젝트 구조 설명

```text
krx-hj3415/
├─ pyproject.toml
└─ src/krx_hj3415/
   ├─ cli.py                       # krx CLI 엔트리
   ├─ app/
   │  ├─ settings.py               # .env / 환경변수 설정 로딩
   │  ├─ composition.py            # DB/리소스/어댑터 조립
   │  ├─ usecases/sync_universe.py # 유니버스 동기화 유스케이스
   │  ├─ provider/                 # 외부 KRX 데이터 수집 구현
   │  ├─ adapters/                 # db2 어댑터
   │  ├─ domain/                   # diff 등 도메인 로직
   │  └─ ports/                    # 포트 인터페이스
   └─ .env
```

사용자는 보통 `cli.py`의 `krx sync`만 실행하면 되고, 코드 재사용 시 `app/usecases`와 `app/composition`을 사용하면 됩니다.

## 3. CLI 명령어 사용법 (예시 포함)

설치:

```bash
cd packages/krx-hj3415
python -m pip install -e .
```

도움말:

```bash
krx --help
krx sync --help
```

기본 실행:

```bash
krx sync
```

옵션 예시:

```bash
# snapshot 저장 안 함
krx sync --no-snapshot

# 유효 엑셀 URL 탐색 범위를 30일로 확장
krx sync --max-days 30

# removed 종목을 NFS latest/snapshot에서도 실제 삭제
krx sync --apply
```

옵션 설명:
- `--apply`: removed 종목 NFS 삭제 적용
- `--snapshot/--no-snapshot`: universe snapshot 저장 여부 (기본: `--snapshot`)
- `--max-days`: 엑셀 URL 탐색 최대 일수

주의:
- `--max-days`는 `MAX_DAYS_MIN`~`MAX_DAYS_MAX` 범위를 벗어나면 실패합니다.
- `--apply`는 실제 삭제 작업이므로 운영 환경에서 주의해서 사용해야 합니다.

## 4. 다른 프로젝트에서 임포트해서 사용하는 예시

CLI 대신 코드로 직접 실행할 수 있습니다.

```python
import asyncio

from krx_hj3415.app.composition import build_components
from krx_hj3415.app.domain.types import UniverseEnum
from krx_hj3415.app.settings import get_settings
from krx_hj3415.app.usecases.sync_universe import run_sync


async def main() -> None:
    settings = get_settings()
    components = build_components(settings)
    try:
        await components.resources.bootstrap()
        result = await run_sync(
            components.universe_store,
            universe=UniverseEnum(settings.default_universe),
            max_days=15,
            snapshot=True,
        )
        print(result.universe, len(result.added), len(result.removed))
    finally:
        await components.resources.aclose()


asyncio.run(main())
```

## 5. 환경변수 설정 예시

이 프로젝트는 `src/krx_hj3415/.env`와 OS 환경변수를 함께 읽습니다.

```env
# app
APP_NAME=krx
APP_ENV=prod
LOG_LEVEL=INFO

# db
MONGO_URI=mongodb://localhost:27017
MONGO_DB_NAME=hj3415
MONGO_CONNECT_TIMEOUT_MS=5000
MONGO_SERVER_SELECTION_TIMEOUT_MS=5000
SNAPSHOT_TTL_DAYS=730

# krx
DEFAULT_UNIVERSE=krx300
DEFAULT_MAX_DAYS=15
MAX_DAYS_MIN=1
MAX_DAYS_MAX=60
SOURCE_NAME=samsungfund
PRINT_LIMIT=50
```

운영 시 핵심:
- `DEFAULT_UNIVERSE`는 현재 구현상 `krx300`만 유효합니다.
- MongoDB 연결 정보가 없거나 잘못되면 동기화가 실패합니다.

## 7. Dockerfile + docker-compose.yml 사용 예시

이 프로젝트는 CLI 기반 단독 실행이 가능하므로 컨테이너 실행 예시를 함께 제공합니다.

`Dockerfile` 예시 (`packages/krx-hj3415/Dockerfile`):

```dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY . /app

RUN python -m pip install --upgrade pip && \
    python -m pip install .

ENTRYPOINT ["krx"]
```

`docker-compose.yml` 예시 (모노레포 루트 기준):

```yaml
version: "3.9"

services:
  mongo:
    image: mongo:7
    ports:
      - "27017:27017"
    volumes:
      - mongo_data:/data/db

  krx:
    build:
      context: ./packages/krx-hj3415
      dockerfile: Dockerfile
    environment:
      APP_NAME: krx
      APP_ENV: prod
      LOG_LEVEL: INFO
      MONGO_URI: mongodb://mongo:27017
      MONGO_DB_NAME: hj3415
      DEFAULT_UNIVERSE: krx300
      DEFAULT_MAX_DAYS: "15"
      MAX_DAYS_MIN: "1"
      MAX_DAYS_MAX: "60"
      PRINT_LIMIT: "50"
    depends_on:
      - mongo
    command: ["sync", "--max-days", "15", "--snapshot"]

volumes:
  mongo_data:
```

실행:

```bash
docker compose up --build
```

단발성 명령 실행:

```bash
docker compose run --rm krx sync --max-days 30 --no-snapshot
docker compose run --rm krx sync --apply
```

