Metadata-Version: 2.4
Name: contracts-hj3415
Version: 0.5.4
Summary: DTO pakages for hj3415
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: logging-hj3415

# contracts-hj3415 배포 가이드

`contracts-hj3415`는 프로젝트 간 데이터 교환에 사용하는 DTO/타입 계약 패키지입니다.
현재 `pyproject.toml` 기준 빌드 백엔드는 `flit_core`, 최소 Python 버전은 `3.11`, 현재 버전은 `0.5.3`입니다.

## 1. 프로젝트 구조 (사용자 빠른 이해용)

이 패키지는 “데이터를 어떻게 주고받을지”를 고정하는 계약 레이어입니다.
실제 수집/저장/분석 로직은 없고, envelope/payload 타입과 생성 함수에 집중되어 있습니다.

```text
contracts-hj3415/
├─ pyproject.toml                  # 패키지 메타/버전/빌드 설정(flit_core)
└─ src/contracts_hj3415/
   ├─ common/
   │  ├─ types.py                  # 공통 타입(Topic, Endpoint 등)
   │  ├─ payload.py                # 공통 payload 검증
   │  └─ envelope.py               # 핵심: Envelope DTO + make_*_envelope
   ├─ nfs/
   │  ├─ c101.py ~ c108.py         # 엔드포인트별 contents 타입
   │  ├─ types.py                  # labels 등 NFS 전용 타입
   │  └─ payloads.py               # NfsPayloadDTO, build_nfs_payload_dto
   ├─ universe/
   │  ├─ krx300.py                 # 유니버스 contents 타입
   │  └─ payloads.py               # UniversePayloadDTO
   ├─ analysis/
   │  ├─ features.py, red.py       # 분석 결과 contents 타입
   │  └─ payloads.py               # AnalysisPayloadDTO
   └─ dart/
      ├─ types.py
      └─ payloads.py
```

데이터 흐름은 아래 3가지 envelope로 통일됩니다.

- `NfsEnvelopeDTO`: 스크래핑 계열 데이터
- `UniverseEnvelopeDTO`: 유니버스(종목군) 데이터
- `AnalysisEnvelopeDTO`: 분석 결과 데이터

대표 진입점(`common/envelope.py`)의 생성 함수:

- `make_nfs_envelope(...)`
- `make_universe_envelope(...)`
- `make_analysis_envelope(...)`

간단 사용 예시:

```python
from datetime import datetime, UTC
from contracts_hj3415.common.envelope import make_nfs_envelope

env = make_nfs_envelope(
    code="005930",
    asof=datetime.now(UTC),
    endpoint="c101",
    labels={},
    contents={"summary_cmp": {"market_cap": 100}},
)
```

## 2. 요구사항

- Python `>=3.11`
- 배포 도구: `build`, `twine`, `flit`
- PyPI 토큰(또는 사내 인덱스 계정)

```bash
python -m pip install -U pip build twine flit
```

## 3. 로컬 설치

소스 기준 설치:

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

개발 모드 설치:

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

## 4. 배포 아티팩트 빌드

기존 빌드 산출물 정리 후 재빌드:

```bash
cd packages/contracts-hj3415
rm -rf dist build *.egg-info
python -m build
```

생성 결과:

- `dist/contracts_hj3415-<version>-py3-none-any.whl`
- `dist/contracts_hj3415-<version>.tar.gz`

## 5. 업로드 (PyPI)

토큰 환경 변수 설정:

```bash
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=<PYPI_API_TOKEN>
```

업로드 실행:

```bash
cd packages/contracts-hj3415
python -m twine check dist/*
python -m twine upload dist/*
```

테스트 저장소(TestPyPI) 업로드:

```bash
python -m twine upload --repository testpypi dist/*
```

## 6. 배포 버전 갱신 절차

1. `pyproject.toml`의 `[project].version`을 새 버전으로 변경
2. `python -m build`로 아티팩트 재생성
3. `twine check` 통과 확인
4. `twine upload`로 배포

버전은 재업로드가 불가하므로, 이미 업로드한 버전이면 반드시 새 버전으로 올려야 합니다.

## 7. 배포 후 검증

깨끗한 가상환경에서 설치 확인:

```bash
python -m pip install contracts-hj3415==0.5.3
python -c "import contracts_hj3415; print('ok')"
```

로컬 wheel 검증:

```bash
python -m pip install dist/contracts_hj3415-0.5.3-py3-none-any.whl
python -c "from contracts_hj3415.common.envelope import make_nfs_envelope; print('ok')"
```

