Poetry를 공부하기 위해 공식 문서를 (발)번역해보았다. Poetry는 의존성 관리 및 파이썬 내 패키징을 위한 툴이다. 프로젝트가 의존하고 있는 라이브러리들을 관리(설치, 업데이트 등)해준다.

---

1. 설치

osx / linux / bashonwindows은 아래 curl url을 터미널에 입력해서 설치하면 된다. Poetry bin 디렉토리에 설치되고, 유닉스에서 위치는 $HOME/.poetry/bin 이다.

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

설치 후 shell에 환경 변수를 설정해주고, shell을 닫았다가 열면 poetry를 터미널에 쳤을 때 읽을 수 있게 된다.

vi .zshrc 

# 파일에 아래 command 추가
export PATH="$HOME/.poetry/bin:$PATH"

2. 의존성이란?

정의

좋은 글을 참고했다. 예전에도 블로그에 정리했던 적이 있는 것 같은데, 의존성은 코드에서 두 모듈간의 연결이다. 하나의 모듈이 바뀌면 의존하고 있는 다른 모듈까지 변경이 이루어져 수정이 필요하게 된다.

의존성 관리가 중요한 이유 중 또 다른 하나를 링크의 비유에서 찾았다. 내가 만약 오픈소스 프로젝트를 찾아서 최단경로 API, 음성API 등을 조합해 네이게이션 앱을 만들었다고 가정하자. 만약에 내가 모듈을 직접 포함하면 버그가 있을 가능성, 혹은 구버전일 가능성을 확인하지 못하고 배포하게 될 수 있다.

내가 일일이 모듈을 추가하고 관리하는 것이 아니라, 의존성 관리자가 내가 사용하고 있는 모듈을 일괄적으로 처리해줌으로써 API가 최신인지 확인하고 버그가 없는지 등 모든 것일 방지할 수 있게 된다.

- pip과 차이점

spoqa 기술 블로그를 참고했다. poetry의 장점 뿐 아니라 단점도 담은 사용기인데, PyPI 외의 repository를 사용할 때 버그 등 전반적으로 정리가 잘 되어있다. 나는 custom repo를 사용하진 않을 것이기 때문에 살포시 패스했다. (블로그 링크)

의존성 해결

내 프로젝트에 필요한 패키지1, 패키지2가 있고, 패키지2는 패키지1이 2.0버전 이상을 요구한다고 하자. pip으로 설치하게 되면 내가 패키지1을 1.0버전으로 설치한다고 해도 아무런 문제가 발생하지 않는다.

하지만 poetry는 버전 관련 정보를 확인하고 특정 버전 이상이 아닐 경우에 아예 설치가 되지 않는다.

의존성 잠금

pip은 lock파일이 없고, 직접 requirements.txt를 작성해야 한다. 반면 poetry는 lock 파일과 pyproject.toml(requirements.txt 같이 설치한 패키지를 리스팅해놓은 파일)을 자동으로 생성 및 업데이트해준다.

가상환경

pip은 전역에 패키지를 설치하기 때문에, 해당 설치툴로는 다른 환경에서의 버전 관리가 불가하다. 그래서 미니콘다나 virtualenv 같은 툴이 부가적으로 필요하게 된다. 따로 놀게될 가능성이 크다. 반면 poetry는 가상환경 여부를 확인하고 기존 환경, 혹은 새로 만들어 설치하는 등 자동으로 관리해준다.

3. Basic usage

project setup

아래 명령어를 입력하면 poetry가 tests 파일을 포함한 project 디렉토리 구조를 세팅해준다.

poetry new poetry-demo

poetry-demo
├── pyproject.toml
├── README.rst
├── poetry_demo
│   └── __init__.py
└── tests
    ├── __init__.py
    └── test_poetry_demo.py
    

- pyproject.toml

여기서 가장 중요한 파일이다. 프로젝트와 의존성을 조율해주기 때문이다.

파일은 아래와 같이 생겼다. 만약 의존성을 프로젝트에 추가하고 싶다면, tool.poetry.dependencies에 지정해주면 된다. 아래 tool.poetry.dependencies에서 패키지 이름과 버전 제한을 매핑해준 것을 볼 수 있다.

poetry는 이 정보를 repositories에서 패키지를 찾을 때 사용하는데, tool.poetry.repositories(=패키지를 찾는 곳)는 기본적으로 PyPI이다. 위에서 말했던 spoqa 기술 블로그 버그 내용과 관련되어 있는 부분이다.

name = "poetry-demo"
version = "0.1.0"
description = ""
authors = ["Sébastien Eustace <sebastien@eustace.io>"]

[tool.poetry.dependencies]
python = "*"

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

pyproject.toml 파일을 변경할 필요 없이 아래 command를 통해 수정이 가능하다. requirements.txt는 내가 계속 업데이트를 해줘야 하는 반면, Poetry는 알아서 add해주는게 장점이다.

poetry add pendulum

- poetry.lock

프로젝트에 정의된 의존성 파일들을 설치하기 위해 아래 command를 사용하면 된다. 요 파일은 모두가 같은 의존성 환경에서 개발할 수 있도록 도와준다. install을 했을 때 둘중 하나의 상황이 생길 수 있다.

poetry install

installing without poetry.lock

poetry.lock 파일이 없는 상태에서 install command를 실행했을 경우, poetry는 pyprojet.toml에 있는 패키지들의 모든 의존성을 해결하고 가장 최신 버전으로 다운로드 하게 된다.

설치가 끝나면 패키지의 정확한 버전을 명시해 특정 버전에 프로젝트를 locking한다. lock 파일은 프로젝트 레포에 commit해야 모든 구성원들이 같은 버전의 의존성을 가질 수 있다.

installing with poetry.lock

이미 poetry.lock 파일이 있다면 이전에 나 혹은 프로젝트의 다른 구성원이 install command를 한 이력이 있다는 뜻이다.

이 때 일관성을 유지하기 위해 install command를 하더라도 최신 버전을 다운받는 것이 아니라, 새로운 버전이 Released됐더라도 lock 설정에 맞는 파일을 다운받게 된다. 의존성에서 예상치 못한 변화가 생기지 않도록 관리해주는 것이다.

만약 최신 버전으로 업데이트하고 싶으면 update command를 써주면 된다. 그러면 pyproject.toml을 기반으로 최신 매칭 버전을 lock file에 업데이트 해준다.

만약 pyproject.toml과 poetry.lock이 일치하지 않으면 poetry가 경고를 보낸다.

4. Managing environments

poetry의 핵심적인 기능 중 하나가 바로 프로젝트 환경 독립이다. 다른 말로 파이썬 설치를 전역적으로 하지 않고 분리한다는 의미인데, 이를 위해서는 현재 가상 환경이 돌아가고 있는지를 확인하는 것이 필요하다. 만약 가상환경이 있으면 새로운 환경을 만들지 않고 기존 환경에 패키지를 설치하고, 그게 아니면 환경을 만든 뒤 패키지를 설치하게 된다.

가상 환경을 만들 때 파이썬 버전은 가장 최근에 활성화된 파이썬 버전을 기준으로 한다. 내 프로젝트에 맞는 파이썬 가상환경을 만들기 위해서는 프롬프트에 pyenv를 통해 명시적으로 활성화시켜주는 것이 좋다.

가상환경 이동

미니콘다를 쓸 때는 내가 어떤 디렉토리에 있는지와 상관 없이 가상 환경 리스트를 불러오고 업데이트할 수 있었다. 그런데 poetry는 그냥 홈디렉토리에서 아래 명령어를 치면 에러가 확인됐다.

이 문제는 내가 shell에서 환경 설정을 잘못해서 생긴건지, 아님 poetry 자체가 이런건지 모르겠다. 분명 미니콘다같이 쓸 수 있을 것 같은데 shell에서 path 설정하는거 외에 다른 설정이 있는지 찾아봐야겠다.

poetry env info

[RuntimeError]
Poetry could not find a pyproject.toml file in /Users/yeni or its parents

일단 pyproject.toml 파일이 있는 디렉토리에서 동일한 명령어를 실행하면 다음과 같이 가상환경 정보를 제공한다.

❯ poetry env info

Virtualenv
Python:         3.7.6
Implementation: CPython
Path:           /Users/yeni/Library/Caches/pypoetry/virtualenvs/board-project-YxfDBa-d-py3.7
Valid:          True

System
Platform: darwin
OS:       posix
Python:   /Users/yeni/miniconda3

System에서 왜 Python이 미니콘다꺼를 쓰는지 궁금했는데, 내가 shell base를 미니콘다로 해놔서 파이썬을 미니콘다 base environment에 있는 애를 가져온 것 같다. 가장 최신에 활성화된 파이썬으로 가상환경을 만든다고 했으므로!

가상환경 확인

프로젝트와 연관있는 모든 가상환경을 띄워주는 command도 있다.

poetry env list

test-O3eWbxRl-py2.7
test-O3eWbxRl-py3.6
test-O3eWbxRl-py3.7 (Activated)

5. commands

명령어가 많긴 한데, 초보자로서 내가 사용할만한 것들만 정리해봤다.

new & init & install

처음에 poetry를 접하게 되면 시작하고 설치하는 command가 많아 당황하게 된다.

• new: 프로젝트 디렉토리 구조를 생성해줌. 여기에는 pyproject.toml 등의 파일이 포함되어 있음

• init: pyproject.toml파일을 만들게 해주는 명령어. 프롬프트에서 상호작용을 통해(물어보는 내용을 사용자가 기입) 만들게 된다.

• install: pyproject.toml 파일을 읽고 의존성을 해결하면서 패키지를 설치해준다.

- project_name.egg-info 파일

poetry install이 무엇인지 모르는 상태에서 프로젝트를 만들고, 패키지를 add한 다음에 poetry install 명령어를 쓰니까 egg-info 라는 확장자의 파일이 생겼다.

검색해보니 내용은 잘 모르겠지만 PEP376에 명시된 distutils에 의해 생긴거라고 한다. poetry 1.0.10 버전 이하는 개발 중인 프로젝트의 설치를 수정하기 위해 setuptools라는 것에 의존하고 있어서? 라고 하는데... poetry가 생기기 전부터 egg-info에 대한 질문이 있던 것을 보면 이건 poetry가 아니라 python에서 패키지를 관리할 때 만드는 파일 같다. poetry 버전 1.1.0부터는 setup.py 파일을 만들어야 할 필요에서 완전히 벗어났기 때문에 이런 행동들이 생기지 않는다고 한다. 솔직히 무슨 말인지는 잘 모르겠지만 요런 디렉토리들은 git에 올릴 때 ignore 파일에 포함해야 한다는 점만 참고했다.

- PEP?

Python Enhancement Proposal, 파이썬 커뮤니티에게 제공되는 디자인 문서. 파이썬의 새로운 기능이나 환경을 소개할 때 쓰이는 것이라고 한다. 1번 문서에 나와있다.

add

pip install과 동일한 명령어. potery add를 통해서 설치와 동시에 자동적으로 pyproject.toml 파일이 업데이트된다.

만약 이미 존재하는 패키지를 설치하려고 뜨면 오류 메시지를 보내지만, 특정 버전을 명시하면 그 버전에 맞게 업데이트를 해준다.

show

가능한 모든 패키지들을 리스팅해준다. 만약 패키지 이름으로 command를 치면 해당 패키지에 대해 설명도 해준다. 이 점이 pip에 비해 친절한듯 🤔

poetry show
poetry show pendulum

name        : pendulum
version     : 1.4.2
description : Python datetimes made easy

dependencies:
 - python-dateutil >=2.6.1
 - tzlocal >=1.4
 - pytzdata >=2017.2.2

search

remote index에 있는 패키지들을 찾아주는 명령어. pendulum을 서치하면 더 많은 검색 결과가 나오지만 블로깅을 위해 두 개만 가져왔다.

❯ poetry search pendulum

pendulum (2.1.2)
 Python datetimes made easy

pid-pendulum (0.0.13)
 A PID pendulum controller.

export

만약 다른 형태로 변환하고 싶다면 다음과 같이 입력하면 된다. 다른 형태라고 설명되어 있긴 한데 사실상 현재 기준으로 지원하고 있는 형태는 requirements.txt 뿐이라고 한다 🙄

poetry export -f requirements.txt > requirements.txt