[Programming/Python] Poetry

poetry 란?

poetry는 python 프로젝트의 의존성을 관리하고, 패키지를 빌드 및 배포할 수 있도록 도와주는 도구이다.

poetry는 `pyproject.toml` 파일을 사용하여 프로젝트의 의존성, 패키지 메타데이터, 그리고 빌드 시스템을 정의한다.

https://github.com/python-poetry/poetry

GitHub - python-poetry/poetry: Python packaging and dependency management made easy

---

poetry 공식 사이트의 설치

https://python-poetry.org/docs/#installing-with-the-official-installer

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

---

poetry 장점 및 사용하는 이유

• 단순성
  • 의존성 관리와 패키지 배포를 쉽게 설정하고 관리할 수 있다.
• 가상 환경 관리
  • 별도의 도구 없이 프로젝트에 맞는 가상 환경을 자동으로 생성한다.
  • virtualenv를 생성하여 격리된 환경에서 빠르게 개발을 진행할 수 있다.
• 일관성
  • pyproject.toml과 poetry.lock을 통해 일관된 개발 및 배포 환경을 유지한다.
  • pyproject.toml 파일로 인하여 여러 프로젝트의 config를 명시적으로 관리할 수 있다.
• 배포
  • 기존 파이썬 패키지 관리 도구에서 지원하지 않는 build, publish가 가능하다.
  • dependency resolver로 복잡한 의존성들의 버전 충돌을 방지한다.

---

poetry의 주요 기능

• 의존성 관리
  • "poetry add" 명령어를 사용하여 패키지를 추가하고, "poetry remove" 로 패키지를 제거한다.
• 가상 환경 관리
  • poetry는 프로젝트마다 별도의 가상 환경을 자동으로 생성하고 관리한다. 이를 통해 패키지 간의 충돌을 방지하고, 일관된 개발 환경을 유지할 수 있다.
  • "poetry shell" 명령어를 사용하여 프로젝트의 가상 환경에 진입할 수 있다.
• 패키지 빌드 및 배포
  • poetry는 프로젝트를 패키징하고 배포하는 데 필요한 기능을 제공한다. "poetry build" 명령어로 패키지를 빌드하고, "postry publish" 로 PyPI (또는 다른 패키지 인덱스)로 패키지를 배포할 수 있다.
• Dependency Locking
  • "poetry.lock" 파일을 생성하여, 의존성 버전과 해시를 고정한다. 이를 통해 환경에 따라 일관된 패키지 버전을 보장한다.
• 환경 설정
  • 프로젝트 설정 및 패키지 메타데이터는 "pyproject.toml" 파일에 정의된다. 이 파일은 PEP 518 및 PEP 621 표준에 기반하여 다양한 도구와 호환된다.

---

Poetry 기본적인 사용 방법

• 설치
  • pip를 통해 설치
    
    • pip install poetry
  • shell을 통해 설치
    • curl -sSL https://install.python-poetry.org | python3 -
      • https://python-poetry.org/docs/#installing-with-the-official-installer
• 프로젝트 생성
  • poetry new <my-project>
    • 해당 명령어는 기본 디렉토리 구조와 파일이 포함된 새 프로젝트를 생성한다.
    • 즉, 백지 상태에서 시작할 때 사용하는 명령어이다. 이 명령어는 새로운 프로젝트 디렉토리와 파일 구조를 자동으로 만들어주기 때문이다.
  • poetry init
    • 기존의 python 프로젝트 디렉토리에서 poetry를 설정하는데 사용된다. 
    • 즉, 기존 python 프로젝트를 pyproject.toml파일로 의존성 관리할 수 있도록 해준다.
    • init을 사용하면 대화 형식으로 패키지를 설치할 수 있다.
  • "poetry new", "poetry init" 모두 프로젝트를 시작하는 데 유용하지만, 새로 시작하는 프로젝트에는 "poetry new" 를 사용하고 기존 프로젝트에 poetry를 적용하고자 할 때는 "poetry init"을 사용하면 된다.
• 의존성 추가
  • poetry add <package name>
    • 패키지를 프로젝트의 의존성으로 추가한다.
  • 버전 명시
    • poetry add numpy@^1.0.0
      • 1.0.0 이상, 2.0.0 미만
    • poetry add "numpy~1.0.0"
      • 1.0.0 이상, 1.1.0 미만
    • poetry add numpy==1.0.0
      • 버전을 명확히 명시
    • poetry add "numpy>=1.0.0"
      • 해당하는 버전 이상 (1.0.0 이상의 버전 제한 없음)
    • poetry add numpy@latest
      • 최신 버전
  • Git 저장소에 있는 패키지 설치
    • poetry add git+https://github.com/abc/abc.git
  • 로컬에 위치한 디렉토리나 파일로 설치
    • poetry add ./my-packages/
    • poetry add ../my-package/dist/my-package-0.1.0-.tar.gz 
  • --dev or -D 옵션을 통해 개발 환경에서만 사용할 패키지 추가
    • poetry add --dev numpy
  • -G <group name> 옵션을 통한 개발 환경에서만 사용할 패키지를 그룹에 추가
    • poetry add -G dev numpy
  • requirements.txt에서 dependency 추가
    • poetry add $(cat requirements.txt)
    • xargs poetry add < requirements.txt
• 의존성 설치
  • poetry install
    • pyproject.toml에 정의된 모든 의존성을 설치한다.
  • options
    • --no-dev
      • 개발환경의 라이브러리는 빼고 설치
    • --no-cache
      • 캐쉬를 저장하지 않는다.
    • --no-root
      • 현재 작업 중인 코드와 관련된 패키지 설치를 건너뛰고, 오직 pyproject.toml에 명시된 외부 라이브러리만 설치
• 의존성 업데이트
  • poetry update
    • dependencies를 최신버전으로 업데이트하고, poetry.lock 파일을 최신화한다.
      • lock파일을 삭제한 후 다시 install 해준다.
    • poetry update pandas numpy
      • 이렇게하면 해당 패키지의 의존성만 업데이트 해준다.
• 패키지 제거
  • poetry remove <package name>
    • 설치된 패키지를 삭제한다.
  • poetry remove -D <package name>
    • --dev or -D 옵션을 통해 Dev 환경에서 패키지를 삭제
  • poetry remove -G dev <package name>
    • -G dev 옵션을 통해 설치된 패키지를 삭제
• 패키지 출력
  • poetry show
    • 사용 가능한 모든 패키지를 출력한다.
  • options
    • --tree
      • 패키지 의존성을 tree 형태로 출력
    • --only main
      • 메인 패키지만 출력
• poetry 속성
  • poetry config --list
    • config 출력
  • poetry config [options] [setting-key] [settig-value1] ... [setting-valueN]
    • config 변경
  • poetry config virtualenvs.in-project true
    • 프로젝트 내부에 가상환경이 잡히도록 설정
  • poetry config virtualenvs.path "./.venv"
    • 가상환경 경로가 현재 프로젝트의 ".venv"로 잡히도록 설정
• virtualenv 명령 실행
  • poetry run python -V
    • virualenv 내의 존재하는 명령을 실행한다.
• 패키지 검색
  • poetry search
    • 사용 가능한 패키지를 찾는다.
    • poetry search numpy pandas
• .lock 파일 내보내기
  • poetry export
    • poetry의 ".lock" 파일을 다른 형식으로 변환하여 내보낸다.
  • options
    • -f
      • -f 옵션으로 format을 지정(default: requirements.txt) 하여 내보낸다.
      • poetry export -f requirements.txt --output requirements.txt
• 패키지 빌드
  • poetry build
    • 프로젝트를 패키징하여 배포 가능한 형식으로 만든다.
• 가상 환경 진입
  • poetry shell
    • 프로젝트의 가상 환경으로 들어간다.
• 패키지 배포
  • poetry publish --repository pypi
    • PyPI에 패키지를 배포한다.
• Poetry 가상 환경 명령어
  • poetry env info
    • 현재 활성화된 가상환경에 대한 정보를 얻는다.
  • poetry env use
    • poetry로 가상환경을 생성한다.
      • poetry env use </full/path/to/python>
    • 만약 파이썬이 path에 잡혀있다면, 다음 명령어만 입력하여 가상환경을 생성한다.
      • poetry env use python3.11
  • poetry env list
    • 가상 환경 리스트를 출력한다.
  • poetry env remove
    • 가상 환경을 삭제한다.
      • poetry env remove poetry-test-py3.11

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

 

 

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

 

---

Poetry 설치

공식 문서를 기반으로 본인의 운영체제에 맞게 설치하는 것이 좋다.

https://python-poetry.org/docs/#installing-with-the-official-installer

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

위의 링크를 가보면 설치 방법이 나와 있지만 여기에도 적어 본다.

# 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 --version

poetry self update

참고로 poetry uninstall은 다음과 같다 (공식 문서에도 나와 있음).

curl -sSL https://install.python-poetry.org | python3 - --uninstall
curl -sSL https://install.python-poetry.org | POETRY_UNINSTALL=1 python3 -

Shell에서 Poetry 자동 완성 기능 설정

# Bash
poetry completions bash >> ~/.bash_completion

# Zsh
poetry completions zsh > ~/.zfunc/_poetry

# Oh My Zsh
mkdir $ZSH_CUSTOM/plugins/poetry
poetry completions zsh > $ZSH_CUSTOM/plugins/poetry/_poetry
# oh-my-zsh은 .zshrc 파일안의 plugins에 추가해야 한다.
plugins(
	poetry
	...
	)

---

poetry로 프로젝트 셋팅

poetry init

poetry init 명령으로 셋업한 모습

필수가 아닌 이상 엔터로 기본 값을 설정하면 된다.

"python = "^3.11" 의 의미는 python 3.11버전보다 높은 버전은 다 허용한다는 의미이다 (3.11 이상 4.0 미만).

poetry로 파이썬 패키지를 추가하는 것은 다음과 같다.

poetry add fastapi aiohttp

위의 명령을 실행하면 pyproject.toml에 자동을 추가된다.

fastapi, aiohttp가 추가된 모습

poetry shell로 진입하여 패키지가 잘 설치되었는지 확인할 수 있다.

poetry shell

---

개발 환경과 배포 환경의 분리

만약 개발 환경과 배포 환경을 따로 따로 분리하고 싶다면 다음과 같은 명령으로 분리시킬 수 있다.

dev group 생성

poetry add -G dev aiosqlite pytest-asyncio

"poetry add -G dev" 명령에서 "-G" 옵션은 그룹을 만들라는 옵션이다. 이 옵션으로 인하여 다음과 같은 라인들이 pyproject.toml 파일에 입력된다. 

dev group 생성 모습

이것으로 인하여 배포 환경에서는 aiosqlite, pytest-asyncio 모듈들은 설치되지 않고 개발 환경에서만 해당 패키지들을 설치할 수 있다. 그리하여 더 가볍게 배포 환경을 만들 수 있는 이점이 있다.

poetry new

poetry new 명령을 이용하면 다음과 같은 디렉토리 구조와 파일들을 자동으로 만들 수 있다.

poetry new

poetry new 명령의 결과를 보면 알 수 있듯, 아무 것도 없는 백지 상태에서 사용하면 좋을 명령이다. 

poetry init 명령은 기존 프로젝트를 poetry로 관리하고 싶을 때 사용하면 좋은 명령이다.

---

이슈

poetry add로 패키지 추가 시 작동이 멈추는 현상

poetry init이나 poetry add로 패키지를 추가할 때 작동이 멈추는 현상이 나타나면 다음과 같이 환경 변수를 설정한 후, poetry add를 시도해보자.

export PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring

VSCode에서 poetry 가상환경 인터프리터가 잡히지 않는 현상

생성되는 virtualenv 환경을 프로젝트 폴더 내부에 생성(.venv)되게 설정하면 된다.

# config 변경
poetry config virtualenvs.in-project true
poetry config virtualenvs.path "./.venv"