poetry 의 거의 모든것 (튜토리얼)

Python 개발에 있어서 poetry는 매우 강력한 도구로, 프로젝트의 의존성 관리와 패키지 배포를 간소화하는 데 큰 도움을 줍니다. 지금부터 poetry 활용 튜토리얼을 살펴 보겠습니다.

poetry란?

poetry는 Python 프로젝트의 의존성 관리와 패키지 배포를 도와주는 도구입니다. 기존의 pip 와 virtualenv 를 대체할 수 있으며, pyproject.toml 파일을 사용하여 프로젝트 설정과 의존성을 관리합니다.

poetry 의 가장 주요한 특징은 pyproject.toml 파일을 사용하여 프로젝트 설정과 의존성을 선언적으로 관리합니다.

poetry.lock 파일은 프로젝트의 의존성이 해결된 후 생성되어, 의존성 트리에 있는 모든 패키지의 정확한 버전을 잠그고(즉, 고정하고) 기록합니다. 이러한 방식은 프로젝트가 다른 환경에서 동일한 의존성을 정확히 재현할 수 있도록 보장합니다.

poetry의 의존성 관리

• 선언적 의존성 관리: pyproject.toml 파일을 통해 의존성을 선언합니다. 개발자는 필요한 패키지와 버전 범위를 지정하고, poetry가 이를 해결하고 관리합니다.
• 의존성 해결 및 잠금(poetry.lock): poetry는 의존성 해결 과정을 거쳐 호환 가능한 패키지 버전을 찾습니다. 이 정보는 poetry.lock 파일에 저장되어, 프로젝트가 다양한 환경에서도 일관된 의존성을 유지할 수 있게 합니다.
• 가상 환경 관리: poetry는 프로젝트별 가상 환경을 자동으로 생성하고 관리합니다. 이는 프로젝트의 의존성이 시스템의 다른 Python 프로젝트와 충돌하지 않도록 격리합니다.

poetry 설치

poetry는 Python 3.6 이상 버전에서 사용할 수 있습니다.

설치는 아래 명령어로 쉽게 할 수 있습니다.

Linux, macOS, Windows (WSL)

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

Windows Powershell

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

설치가 완료된 후에는, 쉘을 재시작하거나 설치 스크립트에서 제공하는 명령어를 실행하여 설치를 완료해주세요.

poetry 업데이트

poetry 를 업데이트하려면 다음의 명령어를 입력합니다.

poetry self update

poetry 프로젝트 생성

poetry init

poetry init 명령어는 기존 디렉토리 내에서 새로운 poetry 프로젝트를 초기화하는 데 사용됩니다.

poetry init

이 명령어는 pyproject.toml 파일을 생성하고, 사용자로부터 프로젝트의 의존성, 버전, 설명 등에 대한 정보를 대화형으로 입력받습니다. 하지만, 새로운 디렉토리나 소스 코드 파일을 생성하지는 않습니다.

기존 프로젝트에 poetry를 도입하거나, 이미 생성된 디렉토리에 프로젝트 설정을 추가 하려는 경우에 주로 사용됩니다.

poetry new

poetry new 명령어는 새로운 디렉토리에 poetry 프로젝트를 생성하는 데 사용됩니다.

이 명령어는 프로젝트 이름으로 지정된 새 디렉토리를 생성하며, 기본적인 프로젝트 구조(예: 소스 디렉토리, 테스트 디렉토리 등)와 함께 pyproject.toml 파일을 자동으로 생성합니다(완전히 새로운 Python 프로젝트를 시작하려는 경우에 주로 사용됩니다).

새 프로젝트를 시작하려면 다음 명령어를 사용합니다.

poetry new 프로젝트이름

poetry-demo 라는 예제 프로젝트를 생성해 보겠습니다.

poetry new poetry-demo

위의 명령어는 프로젝트 구조를 생성하고, pyproject.toml 파일을 초기화합니다.

프로젝트 구조

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

pyproject.toml 파일

[tool.poetry]
name = "poetry-demo"
version = "0.1.0"
description = ""
authors = ["teddy <teddylee777@gmail.com>"]
readme = "README.md"

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


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

poetry는 프로젝트 루트에 tool.poetry.name 으로 명명된 패키지가 있다고 가정합니다.

만약 프로젝트 구조가 다르다면, tool.poetry.packages를 통해 패키지들의 위치를 직접 지정해야 합니다. tool.poetry.exclude 는 자동으로 .gitignore 파일에 기반하여 설정됩니다.

poetry를 사용하면 지원하고자 하는 Python 버전 을 명확히 지정해야 합니다.

버전 명시

python 3.7 ~ 3.9

[tool.poetry.dependencies]
python = ">=3.7,<3.10"

python 3.7 이상

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

캐럿(^) 표기법을 사용하는 경우는 다음과 같습니다.

python 3.7 이상 (python 4.0 미만)

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

캐럿(^) 표기법은 주로 세마틱 버저닝(Semantic Versioning) 의 메이저 버전 내에서 호환 가능한 변경사항들을 허용하는 데 사용됩니다. 따라서, 마이너 버전의 범위를 제한할 떄는 적합하지 않습니다.

의존성 관리

poetry 를 활용하여 패키지를 추가 및 삭제하는 방법을 알아보겠습니다.

패키지 추가

poetry를 사용하여 패키지를 추가

poetry add 패키지명

개발 의존성으로 패키지를 추가하고 싶다면 --dev 플래그를 사용합니다

poetry add --dev 패키지명

poetry를 사용하여 특정 버전의 패키지를 프로젝트에 설치하는 방법은 명령어와 함께 패키지 이름과 그 버전을 지정하는 것입니다.

poetry add <패키지명>@<버전>

requests 의 특정 버전을 설치하는 방법은 다음과 같습니다.

poetry add requests@2.25.0

세마틱 버저닝을 사용하여 호환 가능한 버전 범위를 지정할 수도 있습니다.

flask 패키지의 1.1.x 어떤 버전이든 설치

poetry add "flask@^1.1"

이 명령은 flask의 1.1.0 이상 및 2.0.0 미만 버전을 설치하도록 합니다.

패키지 삭제

패키지를 삭제하려면 poetry remove 명령어를 사용하면 됩니다.

poetry remove <패키지명>

만약 requests 패키지를 삭제하고 싶다면 다음과 같이 명령어를 입력하면 됩니다.

poetry remove requests

설치된 패키지 목록 조회

poetry를 사용하여 설치된 패키지 목록을 조회하는 방법은 다음과 같습니다.

poetry show

--tree 옵션을 사용하면, 의존성 트리를 계층적으로 보여줍니다. 이는 패키지 간의 의존성 관계를 이해하는 데 유용합니다.

poetry show --tree

--latest 옵션을 추가하면, 각 패키지의 최신 버전도 함께 표시됩니다. 이는 프로젝트의 의존성을 최신 상태로 유지하고 싶을 때 유용할 수 있습니다.

poetry show --latest

--outdated 명령어는 현재 프로젝트에 설치된 패키지 중에서 업데이트가 가능한 패키지의 목록을 보여줍니다. 이 명령은 각 패키지의 현재 버전과 최신 버전을 비교하여, 사용 가능한 새로운 버전이 있는 경우 그 정보를 제공합니다.

poetry show --outdated

--no-dev 옵션을 사용하면, 개발용 의존성을 제외하고 메인 의존성만 표시합니다. 프로덕션 환경에서 필요한 의존성만 확인하고 싶을 때 사용할 수 있습니다.

poetry show --no-dev

가상환경

poetry는 프로젝트별로 자동으로 가상 환경을 생성하고 관리합니다.

가상환경 활성화

poetry shell 명령어는 poetry가 관리하는 프로젝트의 가상 환경을 활성화 하는 데 사용됩니다.

이 명령어를 실행하면 poetry는 프로젝트의 의존성이 설치된 가상 환경을 생성하거나 이미 존재하는 경우 해당 환경을 활성화합니다.

poetry shell

poetry shell 명령어로 가상환경 진입한 결과

가상환경 비활성화

활성화된 가상환경을 비활성화 하려면 다음의 명령어를 입력합니다.

deactivate

혹은

exit

가상환경 Cache 경로 변경

Linux/macOS

~/.bash_profile, ~/.bashrc, 또는 ~/.zshrc 파일 (사용하는 쉘에 따라 다름)에 다음과 같이 추가합니다.

export POETRY_CACHE_DIR="원하는 경로"

Windows

시스템 환경 변수 설정에서 POETRY_CACHE_DIR 변수를 추가하고, 값을 새 캐시 디렉토리 경로로 설정합니다.

Cache 디렉토리를 변경 후 poetry shell 을 실행하면 변경된 디렉토리에 가상환경 캐시 파일을 생성합니다.

가상환경 정보

현재 활성화된 가상 환경에 대한 기본 정보를 얻고 싶다면, env info 명령어를 사용할 수 있습니다.

poetry env info

현재 프로젝트와 연관된 모든 가상 환경을 나열하려면 env list 명령어를 사용할 수 있습니다.

poetry env list

가상환경 삭제

마지막으로, env remove를 사용하여 기존의 가상 환경을 삭제할 수 있습니다.

poetry env remove 가상환경이름

poetry run

스크립트를 실행하려면 poetry run python your_script.py 명령어를 사용하세요

만약 별도로 가상 환경을 관리하고 있고, 가상 환경을 이미 활성화한 상태라면 poetry run 을 사용할 필요가 없습니다.

가상환경이 활성화되지 않은 상태에서 실행하려는 경우

poetry run your_script.py

가상환경이 (poetry shell로) 이미 활성화 되어 있다면

poetry shell
python your_script.py

설치

프로젝트에 정의된 의존성을 설치하려면, 그냥 설치 명령어를 실행하면 됩니다.

poetry install

의존성 내보내기

poetry export 명령은 poetry로 관리되는 프로젝트의 의존성 목록을 requirements.txt 형식으로 내보내는 데 사용됩니다.

다음의 명령어는 현재 프로젝트의 의존성을 requirements.txt 파일 형식으로 내보내고, 파일을 현재 디렉터리에 requirements.txt 라는 이름으로 저장합니다.

poetry export -f requirements.txt --output requirements.txt

기타 옵션

• -f, --format: 내보낼 파일의 형식을 지정합니다. 현재는 requirements.txt 형식만 지원합니다.
• --output, -o: 내보낸 의존성 목록을 저장할 파일의 경로를 지정합니다. 지정하지 않으면 표준 출력으로 결과가 나타납니다.
• --without-hashes: 이 옵션을 사용하면, 의존성 목록에서 해시값을 제외할 수 있습니다. 일부 환경이나 도구에서는 해시값이 문제를 일으킬 수 있기 때문에 유용할 수 있습니다.
• --dev: 이 옵션을 사용하면, 개발용 의존성도 포함하여 내보냅니다.
• --with, --without: 특정 의존성 그룹을 포함하거나 제외할 때 사용합니다.

개발용 의존성을 제외하고 해시값 없이 의존성 목록을 내보내려면 다음의 명령어를 사용합니다.

poetry export -f requirements.txt --output requirements.txt --without-hashes --without dev

프로젝트 빌드 및 배포

프로젝트를 빌드하려면 다음 명령어를 사용합니다.

poetry build

이 명령어는 wheel과 source archive를 생성합니다. PyPI에 배포하려면 먼저 PyPI 계정이 있어야 하며, 다음과 같이 배포할 수 있습니다.

poetry publish