🤷‍♂️Poetry의 모든것

Poetry란?

poetry는 Python 프로젝트의 의존성 관리와 패키징을 현대적으로 통합해주는 도구로, 프로젝트의 라이프 사이클 전반 (설정, 개발, 배포, 배포 후 관리)를 일관되고 간편하게 처리할 수 있게 해준다.

Python의 가상환경

poetry를 이해하기 위해서는 Python의 가상환경 개념을 이해해야한다. 

Python으로 여러 프로젝트를 동시에 진행하다보면 다양한 버전의 Python을 사용해야할 때가 온다.

하지만 같은 패키기를 사용하더라도 각각의 프로젝트에서 해당 패키지의 버전을 다르게 해야할 경우가 발생한다. 이럴 때, 가끔 패키지마다 충돌이 발생할 수 있는데, 이를 독립적으로 관리해주는 것이 유지 보수에 유용하다.

가상 환경은 이를 가능하게 해준다. 

 

가상환경을 생성하는 방법은 다양한다.

venv, virtualenv, pyenv, conda, Hatch, poetry, uv ....

오늘 우리는 이중에서 poetry에 대해서 알아볼 것이다.

---

Poetry

poetry는 python 프로젝트의 의존성 관리와 가상환경을 효율적으로 관리하기 위한 도구이다.

이를 통해서 프로젝트마다 필요한 패키지들을 명시적으로 관리할 수 있고, 가상환경을 쉽게 만들 수 있다. 

poetry 설치

poetry는 pip를 사용해서 간단하게 설치할 수 있다.

pip install poetry

 

poetry 사용법

기본 설정

기존에 존재하는 프로젝트 디렉토리로 이동후 아래의 명령어를 입력하면 해당 디렉토리를 위한 poetry 프로젝트가 만들어진다.

poetry init

해당 명령어를 입력하면 프로젝트이름, 버전, 패키지 의존성 등을 설정하는 인터페이스가 나온다.

 

poetry new

poetry new [프로젝트명]

해당 명령어를 통해서 아래의 구조가 만들어진다.

프로젝트명/
├── pyproject.toml    # 설정 파일
├── 프로젝트명/       # 실제 소스 코드 디렉토리
└── tests/            # 테스트 디렉토리

옵션으로 기존에 존재하던 디렉토리와 연동도 가능하다

poetry new --src my_project  # src 디렉토리 구조 사용

 

pyproject.toml

poetry는 pyproject.toml이라는 파일을 통해서 프로젝트의 의존성을 관리한다. 

해당 파일에는 프로젝트에 필요한 패키지들과 해당 패키지들의 버전 정보가 명시된다. 

 

파일 예시

[tool.poetry]
name = "myproject"
version = "0.1.0"
description = ""
authors = ["Your Name <you@example.com>"]

[tool.poetry.dependencies]
python = "^3.9"
requests = "^2.25.0"

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

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

 

poetry install

poetry install

해당 명령어 입력시 pyproject.toml + poetry.lock 기준으로 패키지를 설치한다. 

일반적으로 git clone 하거나 프로젝트를 처음 설치할 때 사용한다.

 

poetry shell

poetry shell

해당 명령어 입력시 의존성으로 구성된 가상 환경에 진입한다.

 

poetry run

poetry run python main.py

굳이 가상환경으로 진입하지 않더라도 단독으로 해당 환경 내에서 명령을 실행할 수 있다.

 

poetry add

poetry add [패키지 이름]

해당 명령어를 입력하면 패키지가 설치되고 pyproject.toml 파일이 업데이트된다.

 

poetry add requests@^2.25.0

물론 특정 버전을 지정할 수 있다.

 

poetry add --dev black

만약 개발용으로만 해당 패키지를 설치하고 싶다면 --dev 옵션을 주면된다.

 

poetry add git+https://github.com/psf/requests.git

git repo에 대해서도 설치가 가능하다

 

poetry add ../my-local-lib

local 파일을 기반으로도 설치가 가능하다

 

poetry remove

poetry remove 패키지명

의존성을 제거하기 위해서는 remove를 사용하면된다.

poetry update

poetry update

update를 통해서 의존성을 최신화 할 수 있다.

 

빌드 및 배포

poetry build

poetry build

dist/ 폴더에 .tar.gz, .whl 파일을 생성한다.

 

PyPI에 배포

poetry publish --username your_username --password your_password

파일 말고 바로 PyPI에 배포도 할 수 있다.

---

Poetry 명령어 전체 정리

1. 의존성 관리

poetry add <패키지>	패키지 설치 및 pyproject.toml에 등록	--dev, --optional, --extras, --source
poetry remove <패키지>	패키지 제거 및 pyproject.toml/lock 갱신	-
poetry install	pyproject.toml/poetry.lock 기준으로 의존성 설치	--no-dev, --only, --sync
poetry update	의존성 최신 버전으로 업데이트 및 poetry.lock 갱신	--lock, --dry-run, --no-dev
poetry lock	poetry.lock 파일만 생성 또는 업데이트	--no-update

 

2. 프로젝트 생성 및 구성

poetry new <이름>	새 프로젝트 생성 (기본 구조 포함)	--src, --name
poetry init	기존 프로젝트에 pyproject.toml 생성	대화형 입력
poetry build	배포용 .whl, .tar.gz 생성	-
poetry publish	PyPI 또는 testPyPI에 업로드	--username, --password, -r testpypi, --dry-run

 

3. 가상환경 및 실행

poetry shell	가상환경 shell 진입	-
poetry run <명령어>	가상환경 안에서 명령 실행	예: poetry run python
poetry env list	생성된 가상환경 목록 보기	-
poetry env info	현재 가상환경 경로 및 정보 출력	--path, --executable
poetry env use <python>	특정 Python 버전으로 가상환경 설정	예: poetry env use python3.11
poetry env remove <interpreter>	가상환경 삭제	-

 

4. 설정 및 정보 조회

poetry config <key> <value>	Poetry 설정값 저장	--local, --global
poetry config --list	설정값 전체 보기	-
poetry show	현재 설치된 패키지 목록 출력	--tree, --no-dev
poetry show <패키지>	특정 패키지 상세 정보 출력	-
poetry check	pyproject.toml과 환경 유효성 검사	-
poetry version	현재 버전 확인 및 변경	patch, minor, major 등
poetry about	Poetry에 대한 정보 표시	-

 

5. 기타

poetry export	requirements.txt 포맷으로 의존성 내보내기 (pip 호환)
poetry debug info	환경 및 디버깅 정보 출력
poetry cache clear	캐시 삭제