Poetry 소개 및 간단한 사용법 정리

Poetry는 Python용 패키징 겸 의존성 관리를 도와주는 도구로 pip나 virtualenv를 좀 더 포괄적으로 그리고 현대적으로 사용할 수 있게 도와준다. 이 Poetry의 사용법을 간단히 알아보자.

프로젝트 시작하기

Poetry는 당연하겠지만 프로젝트 단위로 사용할 수 있다. 그래서 사용하기 위해선 아래와 같이 new 커맨드로 프로젝트를 생성해야 한다.

poetry new PROJECT_NAME

이렇게 하면 몇몇 확인 단계를 거쳐 새로운 파이썬 프로젝트를 생성할 수 있다.

만약 이미 존재하는 프로젝트에 Poetry 환경만 구성하고 싶다면 아래와 같이 init 커맨드를 사용해 보자.

poetry init

위 두 커맨드 모두 핵심으로 프로젝트 루트에 pyproject.toml이라는 파일을 생성한다. 이름대로 프로젝트 정의 및 의존성 목록을 담은 중요한 파일이다.

의존성 관리하기

프로젝트에 의존성을 추가하려면 아래와 같이 add 커맨드를 사용하면 된다. 여기에 특정 버전을 명시할 수도 있고, 개발 모드 전용 의존성일 경우 --dev 플래그도 추가해 줄 수 있다.

poetry add PACKAGE_NAME
poetry add ANOTHER_PACKAGE_NAME==x.y.z
poetry add --dev PACKAGE_NAME

이 명령들은 프로젝트의 virtualenv 환경에 자동으로 설치까지 진행된다.

의존성 패키지를 삭제하려면 remove 커맨드를 사용할 수 있다.

poetry remove PACKAGE_NAME

이 외에 사용하는 의존성 패키지들의 버전을 일괄적으로 업데이트 하려면 update 커맨드를 사용할 수 있다.

poetry update

물론 pyproject.toml 스펙에 적힌 한도 내에서 최신 버전으로 업데이트 된다.

수작업으로 의존성 관리하기

CLI 커맨드 보다 수작업을 좋아한다면 pyproject.toml 파일을 열어서 직접 명시해 주는 방법도 있다. 예를 들자면 이런 식이다.

[tool.poetry.dependencies]
python = "^3.8"
somepackage = "^3.10.0"

[tool.poetry.dev-dependencies]
pytest = "^5.2"

버전 앞에 붙인 꺽쇠(^)의 의미는 '메이저 업데이트를 제외한 최신 버전' 이라는 의미이다. 즉 ^3.10.0이라는 의미는 3.x.y 버전 중 가장 최신 버전을 사용한다는 의미다.

이렇게 작성한 후 install 커맨드를 사용하면 프로젝트의 virtualenv 환경에 일괄 패키지 설치가 가능하다.

poetry install

위 커맨드를 보고 pip install -r requirements.txt라는 커맨드가 떠오른다면 정답이다. 즉 이 커맨드를 poetry install 커맨드로 완전히 대체할 수 있다.

프로젝트 실행하기

프로젝트를 실행시키기 위해서는 run 커맨드를 사용하면 된다. 예를 들어 실행시킬 엔트리포인트 파일이 main.py라면 아래와 같은 식이다.

poetry run python main.py

이 경우 해당 프로젝트의 virtualenv 환경에서 run 뒤의 커맨드가 실행되는 식이다.

virtualenv 셸 얻기

프로젝트의 virtualenv 환경에서 여러 가지를 시험해 보기 위해 셸을 얻고 싶다면 단순하게 shell 커맨드를 사용하면 된다.

poetry shell

Docker와 Poetry

Poetry의 특징은 virtualenv 환경을 자동으로 통합하는 것이다. 그리고 Docker 컨테이너는 프로젝트 단위로 독립된 환경을 구축하려는 의도가 있다. 결과적으로 해당 프로젝트를 Docker 컨테이너 내에서 돌린다면 Poetry의 virtualenv 환경 통합 기능은 불필요할 수도 있다.

그럴 때는 간단하게 아래 커맨드로 virtualenv 환경을 생성하지 않도록 설정해 줄 수 있다.

poetry config virtualenvs.create false

위 커맨드는 Poetry의 virtualenv를 비활성화 시키므로 Dockerfile 등에 poetry install 커맨드를 실행하기 전에 동작하도록 작성하면 될 것 같다.

기타

Poetry 자체를 업그레이드 하려면 self update 커맨드를 사용해 보자.

poetry self update

다만 Homebrew 등의 다른 패키지 매니저를 통해 Poetry를 설치했다면 위 커맨드를 신경 쓸 필요는 없을 것 같다.