Poetry를 사용하기 위해 다음의 공식문서를 참고하여 학습한 내용을 정리 한 글입니다.

Introduction | Documentation | Poetry - Python dependency management and packaging made easy.

---

Poetry

하나의 기술을 배우기 전에 이 기술이 왜 생겼는지 그 배경을 알게 되면 이 기술을 어떤식으로 활용하는 것이 효율적으로 활용하는것인지에 대한 방향을 잡을 수 있다고 생각한다. 따라서 poetry는 어떠한 장점을 가지고 있는지를 먼저 알 필요가 있다.

poetry는 의존성 관리 및 파이썬 내 패키징을 위한 툴이다. 프로젝트가 의존하고 있는 라이브러리들을 관리(설치, 업데이트 등)해준다.

poetry는 의존성 관리에 굉장히 특화되어 있는 툴이다.

의존성

의존성은 코드에서 두 모듈간의 연결이다. 하나의 모듈이 바뀌면 의존하고 있는 다른 모듈까지 변경이 이루어져 수정이 필요하게 된다.

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

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

따라서 의존성 관리는 프로젝트의 효율적인 관리를 위해서는 선택이 아닌 필수가 될 수 있으며, 이를 지원해주는 poetry는 활용도가 굉장히 높은 툴이라고 볼 수 있다.

의존성 해결

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

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

의존성 잠금

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

가상환경

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

설치

poetry의 장점은 무엇이고 왜 사용하는지를 이해했으니 이제 사용할 줄 알아야한다. 먼저 poetry를 설치해보자.

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"

간단 사용법

설치가 완료됐다면 간단하게 하나의 프로젝트를 생성하여 구조와 사용방법을 알아보자.

프로젝트 생성

poetry를 사용한 프로젝트 생성 명령어는 다음과 같다.

poetry new poetry-demo

이 명령어는 poetry-demo라는 디렉토리를 만들어주고, 해당 디렉토리는 아래와 같은 구조를 가진다.

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

이제 각 파일의 역할을 알아보도록 하자.

pyproject.toml

toml파일은 프로젝트의 의존성을 조율 해 주는 파일이기 때문에 가장 중요한 파일이다.

해당 파일은 다음과 같이 생겼다.

[tool.poetry]
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"

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

poetry는 이 정보를 repositories에서 패키지를 찾을 때 사용하는데, tool.poetry.repositories(=패키지를 찾는 곳)는 기본적으로 PyPI이다.

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에 업데이트 해준다. 이 커맨드는 poetry.lock파일을 삭제한 후 poetry install하는 것과 같다.

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

명령어

new

new 명령어로 새로운 프로젝트를 만들 수 있다.

poetry new my-site

위 명령어를 실행하면 아래와 같은 기본 디렉토리 구성을 만들어준다.

my-site
├── pyproject.toml
├── README.rst
├── src
│ └── my_site
│ └── __init__.py
└── tests ├── __init__.py └── test_my_site.py

init

init 커맨드는 pyproject.toml 파일을 인터렉티브 하게 만들 수 있도록 도와준다.

poetry init

install

install 커맨드는 현재 프로젝트의 pyproject.toml 파일을 읽어서 의존성 패키지를 설치해준다. poetry.lock 이 없으면 만들어 주고 있으면 해당파일을 사용하게 된다.

# 의존성 설치
poetry install
# 개발환경의 의존성은 빼고 설치
poetry install --no-dev
# -E 또는 --extras 로 추가 의존성을 설정가능
poetry install --extras "mysql redis"
poerty install -E mysql -E redis

update

의존성 패키지의 버전을 업데이트하고 poetry.lock 파일을 업데이트 한다.

# 패키지 업데이트
poerty update
# 하나씩 지정해서 업데이트도 가능
poetry update requests toml
# 업데이트는 하지 않고 poetry.lock 만 업데이트
poerty update --lock

add

패키지설정을 pyproject.toml 에 추가한다.

poetry add django
# 개발환경에서 필요한 패키지 설치
poetry add pytest factory-boy --dev
# 버전을 지정가능
poetry add django@^3.0.0
poetry add "django=3.0.0"
# 최신버전을 설치
poetry add django@latest
# 깃 저장소에 있는 패키지 설치
poetry add git+https://github.com/django/django.git
# 깃 저장소의 패키지에서 브랜치를 지정
poetry add git+https://github.com/django/django.git#stable/2.2.x
# 로컬에 디렉토리의 파일로 설치하기
poetry add ./my-package/
poetry add ./my-package/dist/my-package-0.1.0.tar.gz
poetry add ./my-package/dist/my-package-0.1.0.whl

remove

패키지 삭제

poetry remove flask
# 개발환경 패키지 삭제
poetry remove pytest

show

# 설치된 모든 패키지를 보여준다.
poetry show

# 개발환경용 제외하고 보여준다.
poetry show --no-dev

# 특정패키지를 지정하면 상세내용을 보여줍니다.
poetry show django

# 최신 버전을 보여준다.
poetry show --latest (-l)

# 업데이트를 해야하는 패키지들을 보여준다.
poetry show --outdate (-o)

# 의존성 트리를 보여준다.
poetry show --tree

build

소스를 배포가능한 형태로(tarball, wheel)빌드한다.

poetry build

publish

아래 명령어로 PyPI에 배포할 수 있다.

poerty publish

배포를 하려면 PyPI 계정이 필요하다. 계정이 없다면 프로젝트명이 겹치면 배포를 할 수 없으니, 프로젝트 명을 정해서 배포를 해야한다.

config

config 커맨드로 poetry 관련 설정을 변경할 수 있다.

# 설정보기
poetry config --list
# 설정법
poetry config [options] [setting-key] [setting-value1] ... [setting-valueN]

run

프로젝트의 virtualenv 에 커맨드를 전달하여 실행하게 된다.

poetry run python -V

check

pyproject.toml 의 유효함을 체크하는 명령어다.

search

패키지를 찾기위한 커맨드. 예를들어 beautifulsoup 의 패키지명의 철자가 기억이 안나고 beautiful 만 기억나면 아래와 같이 할 수 있다 .

$ poetry search beautiful | grep soup
---------------------------------
# output
beautifulsoup (3.2.2)
beautifulsoup4 (4.9.1)

lock

pyproject.toml 에 설정된 의존성들에 대한 lock 파일을 생성한다. (설치X)

export

export 명령어는 lock 파일을 사용해서 다른 의존성 포맷으로 변경할 수 있다.

poetry export -f requirements.txt > requirements.txt

가상 환경 관리하기

poetry 로 가상환경(virtualenv)을 관리 할 수 있다.

$ poetry env use {파이썬경로}

만약에 python3 이 패스에 잡혀 있는 상황이라면 모든 경로를 적어주지 않아도 된다.

$ poetry env use python3

가상환경 정보보기

poetry env info

커맨드로 환경 정보를 확인할 수 있다.

단순하게 가상환경의 path만 알고 싶은 경우라면 -path 옵션을 주면 된다.

$ poetry env info --path

가상환경 리스트 보기

만들어진 가상환경의 리스트는 아래의 명령어로 확인 가능하다.

$ poetry env list

가상환경 삭제하기

삭제는 아래의 명령어로 가능하다.

$ poetry env remove {python경로}