portfolio-hub/docs/technical/python-runtime-and-packaging.md

Python Runtime and Packaging

• Related REQ: N/A

목표

Python 3.11+ 및 pyproject.toml 중심 패키징 기준을 유지하고, 로컬/CI/운영의 실행 환경 편차를 줄인다.

Runtime Baseline

• 공식 지원 런타임은 Python 3.11 이상이다.
• 로컬 개발은 venv 기반 실행을 기본으로 한다.
• 개발/테스트 의존성은 editable install(pip install -e .[dev])로 일관화한다.

Required Files

파일	책임	필수 내용
pyproject.toml	프로젝트 메타데이터와 의존성 기준	requires-python >=3.11
README.md	설치/실행/테스트 진입점	venv 생성 및 실행 절차
alembic.ini	DB migration 런타임 설정	Alembic 동작 기준

Packaging Rules

• 패키징 source of truth는 pyproject.toml로 유지한다.
• CLI 엔트리포인트 portfoliohub는 패키지 설치 후 동일하게 동작해야 한다.
• 운영 이미지/환경에서도 개발과 동일한 Python major/minor를 사용한다.

Validation Notes

• pip install -e .[dev] 후 uvicorn app.main:app --reload와 pytest가 실행 가능해야 한다.
• portfoliohub --help가 정상 출력되어야 한다.
• Alembic 명령(upgrade head)이 현재 마이그레이션 체인에서 실패하지 않아야 한다.

Open Implementation Points

• 락파일 기반 재현성(uv lock, poetry.lock 등) 도입 여부는 팀 운영 정책에 따라 확정한다.
• 배포 환경 컨테이너 표준화 시 base image pinning 정책을 문서화한다.