[모던 Python 6편] pyproject.toml와 Poetry로 패키징 현대화하기

예전에는 파이썬 패키지를 만들 때 setup.py, requirements.txt, MANIFEST.in 등 여러 파일을 관리해야 했고, 의존성 관리도 pip와 virtualenv로 수동 처리하곤 했습니다. PEP 518로 제안된 pyproject.toml은 프로젝트 빌드 시스템 표준을 정의하고, Poetry 같은 툴을 이용하면 의존성 관리, 빌드, 배포까지 한 번에 해결할 수 있습니다.

이번 글에서는 기존 방식과 새 방식의 비교, pyproject.toml과 Poetry의 장단점, 기본 사용법을 다룹니다.

이전에는 어떻게 했을까?

setup.py + requirements.txt 방식

• setup.py로 패키지 메타데이터(이름, 버전, 의존성) 정의
• requirements.txt로 개발 의존성 관리
• 패키지 빌드/배포 시 python setup.py sdist bdist_wheel 등 명령 실행
• 의존성 추가/삭제 시 requirements.txt 수정 후 pip install -r requirements.txt 재실행

단점:

• 여러 파일 관리 필요
• 표준화된 빌드/런타임 환경 정의 어려움
• 의존성 충돌 시 해결 과정 번거로움

pyproject.toml 표준과 Poetry 소개

pyproject.toml는 PEP 518에 정의된 표준 빌드 설정 파일로, 빌드 도구(예: Poetry, Flit, setuptools) 설정을 담을 수 있습니다. Poetry는 이 파일을 기반으로 의존성 정리, 패키지 빌드, 퍼블리시를 체계적으로 처리합니다.

Poetry 장점

• 모든 설정 centralization: pyproject.toml 하나로 의존성, 메타데이터, 스크립트 정의 가능
• 의존성 관리 자동화: poetry add package_name으로 의존성 추가, poetry.lock로 재현성 있는 빌드
• 가상환경 자동 관리: poetry install 시 자동으로 venv 생성, 의존성 설치
• 빌드/배포 단순화: poetry build, poetry publish로 손쉽게 패키지화

단점:

• Python 3.7+ 등 비교적 최신 환경 필요(실제는 Python 3.7 이하에서도 동작 가능하지만 권장버전은 최신)
• 기존 setup.py 기반 워크플로우에서 전환 시 초기 학습 필요
• Poetry 외에도 Flit, Hatch 등 다양한 빌드도구 존재 → 도구 선택 고민 가능

간단한 예제

프로젝트 디렉토리에서 Poetry 초기화:

pip install poetry
poetry init

질문에 답하면 pyproject.toml 생성. 이후 의존성 추가:

poetry add requests

pyproject.toml에는 다음과 같이 의존성이 기록됨:

[tool.poetry.dependencies]
python = "^3.9"
requests = "^2.26.0"

poetry install 명령으로 모든 의존성 설치, poetry shell로 가상환경 활성화. 이로써 설치, 가상환경, 의존성 정리가 자동화됨.

기존 방식 대비 장단점 정리

장점:

• 중앙 집중식 설정: 하나의 파일(pyproject.toml)에 프로젝트 정보, 빌드/런타임 의존성 모두 명시
• 재현성: poetry.lock로 특정 의존성 버전 고정, 누구나 동일한 환경 재현
• 명령어 직관성: poetry add, poetry remove, poetry build 등 명령어로 작업 간소화

단점:

• 전환 비용: 기존 프로젝트를 Poetry로 전환 시 pyproject.toml 작성, 기존 요구사항 변환 필요
• 학습 필요: Poetry CLI 사용법, pyproject.toml 문법 숙지 필요

대부분의 현대 파이썬 프로젝트는 pyproject.toml 기반 환경을 채택하는 추세이며, Poetry는 의존성 관리와 패키지화에서 큰 편의를 제공한다는 점에서 점점 더 인기가 많아지고 있습니다.

결론

• 기존 setup.py, requirements.txt 등 분산된 설정에서 벗어나 pyproject.toml + Poetry를 도입하면, 패키징과 의존성 관리를 표준화하고 자동화할 수 있음
• 명확한 버전 고정, 쉽게 의존성 추가/삭제, 재현성 높은 환경 구성 등 현대적 파이썬 프로젝트 관리에 유리
• 점진적 전환 가능: 기존 프로젝트도 천천히 Poetry로 이동 가능

다음 글에서는 Python 3.10 이상의 패턴 매칭(Pattern Matching) 기능을 통해 복잡한 조건문을 현대적으로 단순화하는 방법을 다루겠습니다.