Python 프로젝트의 패키지는 보통 requirements.txt로 관리한다. 필요한 패키지 이름과 버전을 한 줄씩 적어 두는 파일이다. 문제는 그게 전부라는 점이다. 개발할 때만 필요한 패키지와 실제 배포에 필요한 패키지가 한 목록에 섞이고, 프로젝트가 커질수록 어느 줄이 왜 들어 있는지 구분하기 어려워진다. 서로 다른 패키지가 같은 라이브러리의 다른 버전을 요구하면 의존성 충돌도 생긴다.
Poetry는 의존성 관리, 가상 환경, 프로젝트 시작을 한 도구로 묶는다. 이 글에서는 Poetry가 requirements.txt의 어떤 부분을 대신하는지 짚고 자주 쓰는 명령어를 정리한다.
(이 글을 쓴 뒤로 명령어가 몇 개 바뀐 것으로 보인다)
파일 두 개가 목록 하나를 대신한다
Poetry는 requirements.txt 대신 파일 두 개를 쓴다.
pyproject.toml: 프로젝트 메타데이터와 의존성을 한 곳에 적는다. 개발용 패키지와 배포용 패키지도 여기서 나뉜다.poetry.lock: 의존성을 풀어서 나온 정확한 버전을 기록한다. 팀원이 같은 lock 파일로 설치하면 환경 차이가 줄어든다.
사람이 적는 목록과 기계가 적는 기록을 분리한 것이 핵심이다. pyproject.toml에는 내가 원하는 패키지와 버전 범위를 적고, 그 범위를 풀어서 나온 정확한 결과는 poetry.lock이 갖는다. requirements.txt 하나로는 이 둘을 동시에 표현할 수 없다.
설치와 프로젝트 시작
Mac OS 기준으로 터미널에서 설치한다.
curl -sSL https://install.python-poetry.org | python3 -
Windows에서는 PowerShell로 설치한다. 설치가 끝나면 쉘을 재시작하거나 설치 스크립트가 안내하는 명령어를 실행해야 poetry가 잡힌다.
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
Poetry 자체를 최신 버전으로 올릴 때는 이렇게 한다.
poetry self update
프로젝트를 시작하는 방법은 두 가지다. 이미 있는 디렉토리에 pyproject.toml을 만들려면 init, 새 디렉토리와 기본 구조까지 만들려면 new를 쓴다.
# 기존 디렉토리 초기화
poetry init
# 새 디렉토리와 기본 구조 자동 생성
poetry new 프로젝트이름
패키지 추가와 삭제
# 패키지 추가
poetry add 패키지명
# 개발 의존성으로 추가
poetry add --dev 패키지명
# 특정 버전 패키지 추가
poetry add [email protected]
# 패키지 삭제
poetry remove 패키지명
--dev는 Poetry 1.2부터 deprecated되었고, 지금은 poetry add --group dev 패키지명이 같은 역할을 한다. 개발용 패키지는 pyproject.toml의 [tool.poetry.group.dev.dependencies] 아래로 들어간다.
가상 환경, 내보내기, 배포
가상 환경을 켜고 끄는 명령어다.
# 가상 환경 활성화
poetry shell
# 비활성화
deactivate
poetry shell은 가상 환경이 활성화된 새 쉘을 띄운다. deactivate는 가상 환경만 끄고 그 쉘에 남으니, 쉘까지 빠져나오려면 exit를 쓴다. 참고로 Poetry 2.0부터 shell 명령은 기본 설치에서 빠졌다. poetry-plugin-shell 플러그인을 추가하거나 eval $(poetry env activate)로 지금 쉘에서 가상 환경을 켠다.
배포 환경이 아직 requirements.txt를 요구하면 의존성을 내보낼 수 있다. 이 명령도 Poetry 2.0부터는 poetry-plugin-export 플러그인이 있어야 한다.
poetry export -f requirements.txt --output requirements.txt
패키지를 빌드하고 PyPI에 배포하는 명령어도 Poetry 안에 있다.
# 빌드
poetry build
# PyPI에 배포
poetry publish
정리
requirements.txt가 불편했던 건 파일 형식보다 한 파일이 너무 많은 역할을 떠안고 있어서였다.
Poetry는 그걸 pyproject.toml과 poetry.lock으로 나눴다.