contracts-hj3415 배포 가이드

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

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

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

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(...)

간단 사용 예시:

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 토큰(또는 사내 인덱스 계정)

python -m pip install -U pip build twine flit

3. 로컬 설치

소스 기준 설치:

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

개발 모드 설치:

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

4. 배포 아티팩트 빌드

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

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)

토큰 환경 변수 설정:

export TWINE_USERNAME=__token__
export TWINE_PASSWORD=<PYPI_API_TOKEN>

업로드 실행:

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

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

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

6. 배포 버전 갱신 절차

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

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

7. 배포 후 검증

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

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

로컬 wheel 검증:

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')"