파이썬의 새로운 의존성 관리자 Poetry

Poetry는 파이썬(Python)용 패키징 겸 의존성 관리를 도와주는 도구입니다. pip와 virtualenv를 합쳐놓은 듯한 pyenv와 비슷하게 생각되는 도구네요. 최근에는 1.0으로 버전이 올라가면서 이제 쓸만해진 것 아닌가 하는 생각이 듭니다.

공식 홈페이지: https://python-poetry.org

굳이 pip나 virtualenv와 다른 점이 뭐가 있냐면 좀 더 통일화된 관리 방식을 제공해 준다는 점이 차이가 있으려나요?

실제로 poetry는 완전히 새로운 것이 아니라 기존에 제공되던 pip나 pipx, virtualenv 등을 그대로 사용하는 관리 방식을 제공합니다. 대신 npm이나 Cocoapods처럼 하나의 스펙 파일로 패키지 및 프로젝트 엔트리 포인트 등을 관리할 수 있게 해 준다는 점이 큰 특징이겠네요.

참고로 이 글은 여러 패키지를 이용해 자체 프로젝트를 하려는 분들을 대상으로 합니다. 개별 패키지를 개발하시는 분들이라면 공식 사이트의 문서에서 build 와 publish 항목을 참고해 보시기 바랍니다.

설치하기

설치는 pip 등을 통해서도 할 수 있습니다만, 이 경우 함께 설치되는 각종 의존성이 걸린 패키지가 프로젝트에 문제를 일으킬 가능성이 없지는 않으므로 공식 사이트에서는 추천하지 않고 있습니다.

추천되는 방식은 셸 등의 커맨드라인에서 아래 커맨드로 설치하는 방법입니다.

curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python

이 경우 설치는 $HOME/.poetry/bin 이라는 디렉터리에 설치됩니다. 따라서 사용하는 셸 환경에서 이 디렉터리를 PATH 환경변수에 등록해 주어야 합니다. .zshrc 이든 .bashrc 이든 사용하는 셸 설정을 열어서 아래와 같은 방식으로 경로를 추가해 줍시다.

export PATH="$PATH:$HOME/.poetry/bin"

설정이 끝났다면 위 환경이 적용될 셸로 아래 커맨드를 이용해서 동작한다면 기본 설치는 끝입니다.

poetry --version

추가 설정하기

이후 필요하다면 탭 자동완성 기능도 추가할 수 있습니다. 공식 홈페이지에서 다양한 셸 용으로 설치 방법을 설명하고 있습니다. 여기서는 맥의 기본 셸인 zsh용 방법만 별도로 살펴봅시다.

대충(?) 아래 커맨드를 실행시킵니다.

poetry completions zsh > ~/.zfunc/_poetry

그리고 .zshrc 파일에 아래 한 줄을 추가합니다.

fpath+=~/.zfunc

혹시나 oh-my-zsh를 사용 중이라면 플러그인화 하기 위해 아래 커맨드를 추가로 실행시킬 수 있습니다.

mkdir $ZSH/plugins/poetry
poetry completions zsh > $ZSH/plugins/poetry/_poetry

이후 .zshrc 파일을 열어서 plusins 항목에 poetry 를 추가해 줍니다.

plugins=(
    ...
    poetry
    ...
)

이후 zsh를 새롭게 기동 하면 탭 자동완성이 지원됩니다.

다른 셸은 공식 문서에서 찾아봅시다.

새 프로젝트 시작하고 패키지 추가해보기

아래 커맨드를 입력하면 새로운 파이썬 프로젝트를 시작할 수 있습니다.

poetry new PROJECT_NAME

이렇게 하면 현재 디렉터리에 PROJECT_NAME에 해당하는 디렉터리가 생성되며 안에 몇 가지 보일러 플레이트 코드가 생성됩니다. 이 중 가장 중요한 것은 pyproject.toml 이라는 파일입니다. 이 파일에는 각종 패키지 의존 설정이 기록되어 있습니다.

일단 이 파일은 나중에 봅시다.

이미 존재하는 프로젝트에 poetry 끼얹기(?)

이미 존재하는 프로젝트라면 다음 커맨드로 환경을 생성할 수 있습니다.

poetry init

위 커맨드는 대화형으로 몇 가지를 정보를 물어옵니다. 당황하지 말고 찬찬히 읽어보고 답변(?)해 주시면 됩니다.

의존 패키지 추가해보기

프로젝트를 시작했으니 필요한 패키지가 있을 것입니다. 이 패키지를 설치하기 위해서 add 커맨드를 사용합니다.

poetry add PACKAGE_NAME

이렇게 하면 자동으로 패키지가 설치되며 동시에 위 pyproject.toml 파일에 의존성이 추가됩니다. 이 파일을 열어서 살짝 살펴보면 추가한 패키지가 목록에 추가되어 있는 것을 볼 수 있습니다.

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

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

위의 예는 add 커맨드로 somepackage 라는 것을 추가했다는 가정 하에 작성된 예제입니다.

패키지 이름 오른쪽에 버전 스펙이 표시되어 있는데 꺽쇠의 의미는 메이저 업데이트를 제외한 최신 버전이라는 의미입니다. 즉 ^3.10.0 이라는 의미는 3.x.y 버전 중 가장 최신 버전을 사용한다는 의미입니다. 다르게 표현하면 >=3.10.0 과 <4.0.0 을 만족하는 버전이라는 의미입니다.

만약 add 커맨드로 특정 버전 패키지를 설치하고 추가하려면 아래처럼 할 수 있습니다.

poetry add PACKAGE_NAME==x.y.z

마치 pip로 특정 버전 패키지를 설치하는 것과 동일하기 때문에 어색하지는 않은 커맨드입니다.

개발 전용 의존성으로 패키지를 추가하려면 --dev 옵션을 사용할 수 있습니다.

poetry add --dev PACKAGE_NAME

의존 패키지 몽땅 설치하기

만약 남이 생성한 프로젝트를 처음 받았다면 아래 커맨드로 pyproject.toml에 명시된 패키지를 일괄 설치할 수 있습니다.

poetry install

기존 같았으면 pip install -r requirements.txt 같은 커맨드를 썼었을 텐데 poetry의 방식이 더 편해 보이기는 합니다.

프로젝트 실행시키기

poetry로 생성된 프로젝트에는 동일한 이름의 디렉터리가 하나 더 들어있는데 여기에다 구현을 하면 됩니다만 어차피 디렉터리 구성은 마음대로이니 이제 적당히 구현을 하면 됩니다.

그리고 구현이 끝났다면 실행을 해 봐야겠지요. 만약 엔트리 포인트가 main.py 파일이라면 아래처럼 실행시킬 수 있습니다. 관련 의존성 환경이 갖춰진 별도의 환경에서 해당 스크립트다 실행됩니다.

poetry run python main.py

main.py 첫 라인에 실행 환경이 명시되어 있다면 2번째 파라미터인 python 인터프리터를 명시하지 않아도 관계는 없겠지요.

만약 엔트리 포인트를 특정 패키지로 하고 싶다면 pyproject.toml 파일을 열어서 아래와 같은 항목을 추가합니다.

[too.poetry.scripts]
my-script = "package_name:main"

그리고 난 뒤 아래처럼 실행시킬 수 있습니다.

poetry run my-script

의존 패키지 삭제하기

만약 특정 패키지의 의존성을 제거하고 싶다면 remove 커맨드를 사용하면 됩니다.

poetry remove PACKAGE_NAME

의존 패키지 최신 버전으로 올리기

패키지를 최신 버전으로 업데이트하려면 아래 커맨드를 사용합니다.

poetry update

이 커맨드는 아래 축약어도 제공합니다.

poetry up

뭘 쓰든 pyproject.toml 스펙에 명시된 조건에 맞는 한도 내에서의 최신 버전으로 업데이트됩니다.

virtualenv 셸 얻기

만약에 해당 프로젝트 환경을 셸에서 실행시키고 싶다면, 즉 virtualenv 환경을 얻고 싶다면 아래 커맨드를 사용합니다.

poetry shell

virtualenv를 사용해서 셸을 띄운 것과 동일한 환경을 사용할 수 있습니다.

Poetry 업그레이드 하기

poetry 자체를 업그레이드하고 싶다면 아래 커맨드를 사용합니다.

poetry self update

그냥 업데이트가 아니라 self 업데이트라는 것에 주의합시다.

Docker에서 사용하기 팁

Docker 컨테이너는 독립된 환경이므로 딱히 virtualenv 환경을 사용할 이유가 없습니다. 따라서 도커 이미지를 만들 때 virtualenv 환경을 만들지 않도록 해야 합니다.

poetry config virtualenvs.create false

위 커맨드는 virtualenv를 비활성화시키므로 Dockerfile 등에 poetry install 하기 전에 미리 동작하도록 넣어두면 될 것 같습니다.

기타 설정은 아래 커맨드로 확인해봅시다.

poetry config --list

마무리

일부 분야(?)에서만 간략히 정리해 봤는데도 생각보다 글이 길어졌네요. 이 외에도 많은 기능이 제공되니 공식 사이트의 매뉴얼을 참고해 봅시다. 그 외에 uv라는 다른 대안도 참고해 봅시다.

uv - Python의 대안 패키지 및 프로젝트 관리자