Poetry - Python 의존성 관리 및 패키징

1 정리 목차

• Poetry소개
  • 핵심 개념
    
  • 3가지 특징: 선언적 의존성, 자동 의존성, 통합 패키징 & 배포
    
• 기본 의존성 관리
  • 패키지 추가 (poetry add)
    
  • 패키지 제거 (poetry remove)
    
  • 버전 제약 문법 (^, ~, ==)
    
• Poetry 설치 및 첫 프로젝트
  • 설치 (pipx, curl)
    
  • 프로젝트 생성 (poetry new)
    
  • 프로젝트 구조 이해
    
• 가상환경 사용
  • poetry install 이해
    
  • poetry shell vs poetry run
    
  • 의존성 잠금 (poetry.lock)
    
• 프로젝트 구성
  • pyproject.toml 상세 이해
    
  • 스크립트 진입점 (script entry point)
    
  • 개발 의존성 분리 (--group dev)

2 Poetry란?

Poetry는 Python 프로젝트의 라이브러리 의존성 관리, 가상환경 구성, 패키징, 배포를 통합으로 관리하는 도구다.

2.1 핵심 개념

개념	설명
의존성 관리	프로젝트가 필요로 하는 라이브러리 버전을 선언하고 자동 설치
가상환경	프로젝트별 독립적인 Python 환경 생성 (의존성 충돌 방지)
Lock file	poetry.lock: 정확히 설치된 버전을 기록 (재현성 보장)
Packaging	poetry build: 프로젝트를 배포 가능한 패키지로 변환
Distribution	poetry publish: 패키지를 PyPI에 배포

2.2 Poetry의 3가지 특장점

2.2.1 선언적 의존성 관리 (Declarative Dependency Management)

기존 방식 (pip):

pip install pandas numpy scikit-learn  
pip freeze > requirements.txt  # 수동으로 50줄 이상 기록  

Poetry 방식:

poetry add pandas numpy scikit-learn  
# pyproject.toml에 자동으로 저장  

결과 (pyproject.toml):

[tool.poetry.dependencies]  
python = "^3.9"  
pandas = "^2.0"  
numpy = "^1.24"  
scikit-learn = "^1.3"  

장점:
- 직접 필요한 패키지만 명시 (간결함)
- 하위 의존성은 자동 관리
- 버전 제약을 명확히 표현

2.2.2 자동 의존성 해석 (Dependency Resolution)

poetry add pandas numpy scikit-learn  

Poetry가 하는 일:
1. pandas, numpy, scikit-learn의 관계 분석
- pandas는 내부적으로 numpy 필요
- scikit-learn도 numpy 필요

2. 모든 버전 제약 검증

   • pandas ^2.0은 numpy ^1.24 요구
     
   • scikit-learn ^1.3은 numpy ^1.20 요구
     
   • 호환 가능한 조합 찾기

3. poetry.lock 생성 (정확한 버전 기록)

   [[package]]  
   name = "pandas"  
   version = "2.0.3"  
   
   [[package]]  
   name = "numpy"  
   version = "1.24.1"  
   
   [[package]]  
   name = "scikit-learn"  
   version = "1.3.0"  

4. 가상환경 생성 + 설치

   poetry install  

재현성 보장:
- 팀원 A가 poetry.lock을 Git에 커밋
- 팀원 B가 poetry install 실행
- → 정확히 동일한 버전이 설치됨 (버전 차이로 인한 버그 없음)

2.2.3 통합 패키징 & 배포

# 1. 패키지 빌드  
poetry build  
# 생성: dist/my_project-0.1.0.tar.gz  
#      dist/my_project-0.1.0-py3-none-any.whl  

# 2. PyPI에 배포  
poetry publish  

# 3. 다른 사람이 설치  
pip install my_project  

기존 방식 (setuptools):

# setup.py, MANIFEST.in, setup.cfg 등 여러 파일 필요  
# 빌드 도구 설정도 복잡  

Poetry 방식:

# pyproject.toml 하나만 있으면 됨  
# metadata는 자동으로 처리  

2.3 버전 제약 문법 (Version Constraints)

Poetry에서 가장 중요한 부분: 버전을 어떻게 해석할 것인가?

문법	의미	예시	설치되는 버전
^	주버전 고정, 나머지 업데이트	^2.0.0	2.0.0 ~ 2.99.99
~	마이너버전까지 고정, 패치만	~2.1.0	2.1.0 ~ 2.1.99
==	정확한 버전	==2.0.3	2.0.3만
>=, <=	범위 지정	>=2.0, <3.0	2.0.0 ~ 2.99.99
*	와일드카드	2.*	2.0.0 ~ 2.99.99

실무 권장:
- 대부분의 경우: ^ 사용 (안전하면서도 버그 수정 반영)
- 매우 신중할 때: ~ 또는 == 사용