[Python] 의존성 관리툴 poetry

파이썬 의존성 관리툴 Poetry

 Poetry는 python 의존성 관리 및 패키징을 위한 관리툴로서 프로젝트에 사용하는 라이브러리를 체계적으로 관리할 수 있고 패키지를 PyPI에 쉽게 배포할 수 있는 강력한 도구다. 의존성 관리가 약한 venv모듈의 단점을 해결한 모습을 보여준다. 

First commit of Poetry

 2018년 2월 21일에 첫 커밋이 올라온 비교적 따끈따끈한 프로젝트인만큼 2023년 5월 현재 1.5버전까지 출시됐고 파이썬 3.7 이상에서만 사용가능하다.

 

 

---

설치

 Unix 기반 진영과 Windows 기반 진영의 설치 차이가 있다.

 

 

Linux, macOS, Windows(WSL, Windows Subsystem for Linux)

 

curl -sSL https://install.python-poetry.org | python3 -

 몇몇 시스템에서 Python 3 대신 Python 2를 참조하는 경우가 있기 때문에 명령어에 python3를 명시해 주는 것을 권장하고 있다.

 

 

 

Windows (PowerShell)

 

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

❗ 안되면 py 대신 python

 

 

 

 

 위 명령어로 설치하면 환경변수에 poetry가 추가되고 poetry 명령어를 사용해 호출할 수 있다. 아래 명령어를 CLI에 입력해 poetry 버전이 출력되는지 확인해보자.

 

poetry --version

Poetry (version 1.4.2)

 

 만약 출력되지 않았다면

1. 컴퓨터를 재부팅하거나
2. C:/Users/(사용자 이름)/AppData/Roaming/Python/Scripts에 poetry.exe가 설치되어 있는지 확인해 보고 설치되어 있다면 시스템 환경변수 Path에 %APPDATA%/Python/Scripts를 추가

 

 이렇게 했는데도 실행이 안 된다면 여기의 2, 3번 항목을 참조해 해결해보자.

 

 

---

시작하기

 

 패키지 배포를 위한 프로젝트를 만들고자 한다면 다음과 같은 명령어로 시작해보자

---

poetry new <패키지 이름>

대부분의 프로젝트에 적합한 폴더 구조를 가진 파이썬 프로젝트를 생성

 

poetry new poetry-test

 

poetry new

 다음과 같이 최상위 폴더 아래 poetry-test라는 이름의 패키지를 위한 프로젝트가 생성되고 의존성 관리를 위한 pyproject.toml 파일과 README.md도 함께 생성된다. 프로젝트를 완성하고 poetry 명령어를 사용해 build하고 publish하면 PyPI에 패키지를 배포할 수 있다

 

 

 

 기존에 존재하는 프로젝트에 poetry를 이용한 의존성 관리를 시작하고 싶다면 다음과 같은 명령어를 사용할 수 있다.

---

poetry init

 기존 프로젝트에 poetry 초기 구성 진행

 

poetry init

 

 위 명령어를 실행하면 pyproject.toml을 구성하기 위한 정보를 기입하는 절차를 진행한다. 

 

poetry init

 Enter를 계속 누르면 기본 정보가 입력되고 스킵된다.

 

❗ 그마저도 귀찮으면 -n 옵션으로 전부 skip 가능

 

poetry init -n

 

 패키지 배포가 목적이 아니라면 위 명령어를 권장한다.

 

 

---

실행하기

 poetry 환경으로 파일을 실행하고 싶다면 다음과 같은 명령어를 활용할 수 있다

 

 

---

poetry run <명령어>

 poetry 환경에서 명령어를 실행

 

poetry run python --version

 

 

---

poetry shell

 poetry 가상 환경 내에서 shell을 생성하고 실행해 가상환경에서 명령어들을 실행

 

poetry shell

Creating virtualenv test-1Hx-mXa0-py3.11 in .venv

shell이 실행되면 위와 같은 코드가 출력되고 이제부터는 poetry run같은 명령어 없이 shell 내에서 명령어를 쓸 수 있다

 

python --version

 

 

---

패키지 설치하기

 python venv모듈에서 pip install django와 같은 명령어로 PyPI의 패키지를 설치했다면 poetry에서는 아래와 같은 명령어로 패키지를 설치할 수 있다.

 

---

poetry add <패키지>

 패키지를 의존성 관리파일인 pyproject.toml에 추가하고 패키지를 설치

 

poetry add django requests

 pip install 명령어처럼 간단하게 여러 개의 패키지를 설치할 수 있다.

 

 

 

 특정 버전 이상이나 특정 버전만을 선택해 설치할 수도 있는데 명령어는 다음과 같다.

 

# 3.1버전 이상 4.0.0버전 미만
poetry add django@^3.1

# 3.1버전 이상 3.2.0버전 미만
poetry add django@~3.1

# 3.1버전 이상 (상한선 없음)
poetry add "django>=3.1"

# 3.1버전만
poetry add django==3.1

Installing django (3.2.19)

Installing django (3.1.14)

Installing django (4.2.1)

Installing django (3.1)

 제한에 따라 적절한 패키지의 버전을 poetry가 알아서 설치해준다. pyproject.toml에도 ^3.1이나, ~3.1처럼 프로젝트의 버전 제한이 붙는다. 따라서 패키지의 최소 사양을 설정해 줄 수 있다.

 

 당연하게도 pip install 명령어처럼 git+ssh주소나 .tar.gz, .whl파일을 이용한 패키지 설치도 같은 명령어를 이용하면 된다.

 

또한 개발을 위한 패키지 관리를 별도로 하고 싶다면 의존성 그룹을 나눠줄 수도 있는데, 다음과 같은 옵션을 이용하면 된다

poetry add --group devs django==4.2

 

pyproject.toml의 의존성 그룹

 기본 그룹의 의존성과 별도로 devs라는 이름의 의존성 그룹이 새로 생성됐고 서로 다른 버전을 요구할 수 있다. 이제 다음과 같은 명령어로 의존성 그룹에 따라 다른 패키지 버전들을 설치할 수 있다

 

poetry install --with devs

 

 

---

poetry install

현재 프로젝트에서 pyproject.toml파일을 읽고 의존성을 해결한 뒤 설치

 

poetry install

 pyproject.toml에 각 패키지들간의 의존성 관계에 따라 적절한 버전을 찾아낸 뒤 설치한다. 만약 poetry.lock파일이 있다면 pyproject.toml을 확인하는 대신 poetry.lock파일을 확인해 정확한 버전을 설치하고 poetry.lock파일이 없다면 의존성 해결 후 poetry.lock파일을 새로 생성한다. 이를 이용하면 프로젝트 참여자들이 정확히 같은 버전의 패키지들을 사용할 수 있게 된다.

 

---

의존성 확인하기

 poetry가 python venv와 다른 장점은 하나의 패키지를 설치할 때 함께 설치되는 서브 패키지들의 의존성 관계를 확실히 할 수 있다는 것이다. 이를 통해 서로 다른 버전의 서브 패키지들이 중복되어 프로젝트가 꼬이는 일이 현저하게 줄어들 수 있다.

 

---

poetry show <패키지>

특정 패키지의 정보를 볼 수 있다

 

poetry show sqlparse

name : sqlparse
version : 0.4.4
description : A non-validating SQL parser.

required by
- django >=0.3.1

 django의 서브 패키지인 sqlparse의 정보를 볼 수 있다. 패키지 이름을 적지 않으면 패키지 전체의 정보를 볼 수 있다.

또한 --tree 옵션을 이용하면 패키지들 간의 의존성을 트리 구조로 확인할 수 있다.

 

poetry show --tree

django 4.2 A high-level Python web framework that encourages rapid development and clean, pragmatic design.
├── asgiref >=3.6.0,<4
├── sqlparse >=0.3.1
└── tzdata *

 

---

가상환경의 파이썬 버전 변경하기

 poetry는 가상환경을 구성할 때 기본적으로 컴퓨터에 설치되어 있는 파이썬을 찾아서 구성한다. 설치되어 있지 않은 파이썬 버전을 사용해 가상환경을 구성하고 싶다면 pyenv와 같은 파이썬 버전 관리 툴을 사용해서 다른 파이썬 버전의 가상환경을 구성할 수도 있다.

 

---

poetry env use <python.exe 경로>

가상환경을 구성하고자 하는 python버전을 바꾸기

 

poetry env use C:/python39/python.exe

위와 같이 코드를 구성하면 컴퓨터에 설치되어 있는 다른 버전의 파이썬으로 가상환경을 구성할 수 있다

 

 

 

---

VScode가 poetry 가상환경을 인식 못할 때

 vscode에서 poetry 가상환경을 구성하고 poetry shell로 가상환경에 접근했음에도 불구하고 vscode에서 제대로 인식하지 못할 때가 있다. 그럴 때는 poetry의 가상환경을 아예 프로젝트 폴더로 옮기는 방법이 있다

 

poetry config --list

위 명령어를 입력하면 poetry의 설정을 볼 수 있다. 그 중 virtualenvs.in-project가 false로 설정되어 있다면 poetry의 가상환경인 .venv는 poetry가 설치된 폴더 안에 별도로 저장되어 있다. 이 때문에 vscode가 제대로 인식 못하는 것 같은데 이럴 때 virtualenvs.in-project 옵션을 true로 바꿔주고 가상환경을 다시 만들어주면 vscode가 잘 인식한다.

 

poetry config virtualenvs.in-project true

 

poetry shell

 

vscode 가상환경 인식

위와 같이 vscode가 poetry 가상환경을 인식한 것을 볼 수 있다. 만약 아직 인식하지 못했다면 Ctrl+Shift+P -> Python: Select Interpreter에서 poetry환경이 있는지 확인해보자

 

Python: Select Interpreter

 

이외에도 패키지 배포를 위한 poetry build명령어나 poetry publish명령어도 있고 더 편리한 사용을 위한 다양한 기능들이 아직 많다. 더 자세한 내용은 poetry docs를 참조