[Python] Poetry 사용법

 

[Python] Poetry 설치 :: 지식이 홀쑥

[Python] Poetry 설치

 

이번 글은 poetry Usage( Basic usage | Documentation | Poetry - Python dependency management and packaging made easy)를 정리하는 글이다.

 

Poetry 사용법

Poetry 사용을 위해 pendulum이라는 datetime library를 설치하는 과정이다.

Project 설정

1. 다음과 같은 명령어로 프로젝트를 생성한다.

poetry new poetry-demo

 

2. 명령어 실행 시 다음과 같은 폴더 구조가 생성된다.

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

 

여기에서 pyproejct.toml 파일은 매우 중요한 파일로, 프로젝트 및 종속성을 관리하는 역할이며 다음과 같은 구조를 가진다.

# pyproject.toml

[tool.poetry]
name = "poetry-demo"
version = "0.1.0"
description = ""
authors = ["thinmug <thinmug@tistory.com>"]
readme = "README.md"
packages = [{include = "poetry_demo"}]

[tool.poetry.dependencies]
python = "^3.7"


[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Poetry는 사용자가 만든 프로젝트(poetry-demo)의 root 디렉토리에 만들어진 package명(poetry-demo)의 디렉토리와  tool.poetry 섹션의 name이 동일하다고 가정되어 있다. 이를 바꾸고 싶다면 packages 값에 값을 수정해주면 된다.

비슷하게, 이전에 사용되되던 MANIFEST.in이 tool.poetry 섹션의 readme, include, exclude 로 대체되었다. exclude는 .gitignore의 값으로 채워진다.

 

Python Version 설정

* Poetry는 Python Interpreter를 설치해주진 않아서, Python 스크립트 또는 코드를 실행하고 싶다면 직접 Python을 설치해야 한다.

Poetry는 지원할 Python 버전을 특정해야하며, 이 제한은 지원하는 모든 Python Version이 종속성이 해결된 상태로 설치되도록 도와준다.

# pyproject.toml

[tool.poetry.dependencies]
python = "^3.7.0"

 

다음과 같이 Python버전이 특정되어 있을 때 이 프로젝트는 Python의 3.7.0 이상의 버전을 허용한다.
만약 Poetry install명령어 실행 시, 해당 조건을 만족하는 Python Interpreter가 있어야 한다.

* pyenv를 사용한다면 virtualenvs 섹션의 preper-activate-python 이라는 실험 버전의 설정 사용 할 수 있다고 한다.

 

Poetry의 모드

poetry는 두 가지 모드가 존재한다.

Package 모드(Default)

project를 sdist(source distribution, 소스코드배포방식)나 wheel(binary distribution, 바이너리 배포방식)에 패키징하고, package index(PyPI)에 게시하는 package모드로, 이 모드에선 패키징에 필요한 name이나 version과 같은 metadata가 필수다. 또한 poetry install 명령어를 통해 프로젝트 스스로 편집 가능한 상태로 설치된다.

Non-Package 모드

# pyproject.toml

[tool.poetry]
package-mode = false

다음과 같이 설정할 수 있고, poetry를 단순히 종속성 관리 툴로서 사용할 수 있다.

이 경우, package모드에서 반드시 필요했던 metadata들이 선택적인 항목으로 바뀌고, package index에 게시하거나 배포판 빌드가 불가능해진다. 또한 poetry install가 package모드와 다르게 종속성들만 설치하는 poetry install --no-root 명령어와 같아진다.

 

종속성 추가

project에 종속성을 추가하고 싶으면 tool.poetry 섹션의 dependencies에 추가할 수 있다.

# pyproject.toml

[tool.poetry.dependencies]
pendulum = "^2.1"

.toml 파일엔 package 명과 버전 제약사항이 매핑되어 있다.

Poetry는 이 내용을 tool.poetry 섹션의 source항목에 있는 package repository(default는 PyPI)에 검색하는 데 사용된다.

파일을 직접 수정하는 방법 말고도 poetry add 명령어를 사용할 수 있다.

poetry add pendulum

이 add 명령어는 Python Interpreter에 알맞는 버전을 자동으로 찾아주고, 패키지와 하위 종속성들을 설치해준다.

 Poetry는 종속성을 특정하는 다양한 문법을 지원한다.(https://python-poetry.org/docs/dependency-specification/)

 

가상환경 사용

poetry는 기본적으로 {cache-dir}/virtualenvs에 가상환경을 생성한다. poetry 설정에서 cache-dir을 수정할 수 도 있고, virtualenvs.in-project 항목을 true로 설정 시 프로젝트 디렉토리 내부에 가상환경을 생성한다.

** 개인적으로 vscode를 사용할 땐 사용하는 가상환경을 vscode가 인식할 수 있도록 virtualenvs.in-project항목을 true로 설정하고, virtualenvs.path 항목을 ./.venv로 설정하면 해당 가상환경을 알아서 인식한다.

** vscode의 python.venvFolders 설정값을 {cache-dir}/virtualenvs 디렉토리로 변경하는 방법도 있다.

 

Poetry Run 사용

간단하게 스크립트를 실행하고 싶을 땐 poetry run python {Python파일}을 통해 실행할 수 있다.

같은 방법으로 pytest(테스트, poetry run pytest)나 black(코드Formatter, poetry run black)를 사용할 수 있다. 

가상환경 활성화

poetry shell 명령어를 통해 하위 쉘에서 가상환경을 활성화 할 수 있다.

비활성화를 원한다면 exit으로 쉘을 나갈 수 있고, 쉘을 나가기 싫을 땐 가상환경 디렉토리에서 deactivate를 적용하면 된다.

** Poetry가 하위 쉘을 만드는 이유는 상위 쉘에 영향을 주지 않고 하위 쉘이 종료될 때 이전 환경이 유지되는 상위 쉘로 돌아갈 수 있기 때문이라고 한다.

 

종속성 설치

poetry install 명령어로 정의된 종속성들을 설치한다. 이 때 다음 두 가지 중 한가지가 일어난다.

poetry.lock 파일 없이 설치

poetry install  명령어를 실행한 적이 없거나 poetry.lock파일이 없을 때 poetry는 pyproject.toml파일의 모든 종속성들을 해결하고, 그 패키지들의 가장 마지막 버전을 다운로드한다.

poetry가 설치를 완료했을 때, project를 특정 버전으로 고정하기 위해 poetry.lock파일에 다운로드했던 모든 패키지와 버전들을 기입한다. 이렇게 써진 poetry.lock파일을 프로젝트의 repository에 commit하여 project에 작업하는 모든 사람들을 같은 종속성 버전으로 고정한다.

poetry.lock 파일이 있는 상태에서 설치 

이 때 또한 위의 설치와 같이 pyproject.toml파일에 정의된 모든 종속성을 해결하고 설치한다. 하지만 poetry.lock에 기록된 정확한 버전을 사용하여 프로젝트의 모든 사람들이 같은 package 버전의 사용을 보장한다. 이로 인해 pyproject.toml파일에서 요구되는 모든 종속성 패키지들을 가지게 되지만, 최신 버전이 아닐 수도 있다. (poetry.lock 파일이 생성된 시점보다 더 최신 버전들이 나왔을 수도 있다)

poetry는 project가 종속성 버전들의 의도치 않은 변경으로 프로젝트 종속성이 깨지지 않게 하기 위한 의도적인 설계이다.