가상환경 - Poetry

파이썬 프로젝트 관리 도구, Poetry에 대한 완벽 안내서

Poetry는 파이썬 프로젝트의 종속성 관리와 격리된 가상 환경을 효율적으로 제어하는 데 특화된 현대적인 도구입니다. 기존에 널리 쓰이던 pip, virtualenv 또는 pipenv의 기능을 통합하며, 프로젝트의 초기 설정부터 패키징 및 배포에 이르는 전 과정을 간소화합니다.

Poetry의 핵심 특징 및 이점

1. 단일 설정 파일과 재현 가능한 빌드

Poetry는 pyproject.toml 파일 하나로 프로젝트의 모든 설정을 통합 관리합니다. 이 파일은 프로젝트명, 버전, 설명, 그리고 필요한 종속성을 선언적으로 정의하며, 이는 PEP 518 및 PEP 621과 같은 최신 표준을 준수합니다. 이로써 여러 개의 설정 파일(setup.py, requirements.txt 등)을 관리하는 번거로움이 사라집니다.

pyproject.toml: 프로젝트의 기본 정보와 종속성을 명시하는 설정 파일입니다.
poetry.lock: poetry install 또는 poetry add 명령을 실행하면, Poetry는 필요한 모든 패키지와 그 하위 종속성들의 정확한 버전을 확인하여 poetry.lock 파일에 기록합니다. 이 파일 덕분에 어떤 환경에서든 프로젝트의 종속성 구조를 정확하게 복제할 수 있어 팀원 간의 환경 불일치 문제를 효과적으로 해결합니다.

2. 자동화된 가상 환경 관리

Poetry는 프로젝트별로 독립적인 가상 환경을 자동으로 생성하고 관리합니다. 사용자가 직접 virtualenv나 venv를 생성하고 활성화할 필요가 없습니다. Poetry의 명령어 실행 시 필요에 따라 자동으로 가상 환경을 구축하고 사용합니다.

poetry shell: 프로젝트의 가상 환경을 직접 활성화하여 셸 세션에 진입합니다.
poetry run <command>: 가상 환경을 명시적으로 활성화하지 않고도 해당 환경 내에서 특정 명령어를 실행할 수 있습니다. 예를 들어, poetry run python my_script.py와 같이 사용합니다.

3. 직관적인 CLI (Command Line Interface)

Poetry는 사용자가 쉽게 접근할 수 있는 명령어를 제공하여 개발 효율을 높입니다.

poetry init: 새로운 프로젝트를 시작할 때 기본 설정을 위한 pyproject.toml 파일을 만듭니다.
poetry add <package>: 새 패키지를 설치하고 pyproject.toml에 추가하며, poetry.lock 파일을 업데이트합니다.
poetry remove <package>: 패키지를 삭제하고 설정 파일을 정리합니다.
poetry install: poetry.lock 파일에 명시된 종속성들을 설치합니다.
poetry update: pyproject.toml의 제약 조건 내에서 패키지를 최신 버전으로 업데이트합니다.

4. 강력한 종속성 해결기 (Dependency Resolver)

복잡하게 얽힌 패키지들의 버전 충돌 문제를 해결하는 강력한 알고리즘을 내장하고 있습니다. 호환 가능한 패키지 조합을 찾아내며, 해결이 불가능할 경우 구체적인 오류 원인을 알려줍니다.

5. 패키징 및 배포 지원

파이썬 프로젝트를 패키지화하여 PyPI(Python Package Index)에 배포하는 과정을 간소화합니다.

poetry build: 프로젝트를 sdist와 wheel 형식의 배포 가능한 파일로 만듭니다.
poetry publish: 빌드된 패키지를 PyPI에 업로드합니다.

Poetry 설치 및 활용 가이드

1. Poetry 설치하기

pipx를 사용하여 설치하는 것이 권장됩니다. pipx는 애플리케이션을 격리된 환경에 설치해 전역 패키지와의 충돌을 막습니다.

# pipx가 없다면 먼저 설치
pip install pipx

# pipx 실행 경로 설정
pipx ensurepath

# Poetry 설치
pipx install poetry

# pipx가 없다면 먼저 설치
pip install pipx

# pipx 실행 경로 설정
pipx ensurepath

# Poetry 설치
pipx install poetry

설치가 완료되면 poetry --version 명령어로 버전을 확인합니다.

2. 새로운 프로젝트 시작하기

새 프로젝트는 poetry new 명령어로 시작합니다.

poetry new my-blog-app

poetry new my-blog-app

이 명령은 my-blog-app 폴더를 생성하고, 내부에 다음과 같은 기본 구조를 자동으로 만들어줍니다.

my-blog-app/
├── my_blog_app/
│   └── __init__.py
├── tests/
│   └── __init__.py
├── pyproject.toml
└── README.md

my-blog-app/
├── my_blog_app/
│   └── __init__.py
├── tests/
│   └── __init__.py
├── pyproject.toml
└── README.md

3. 기존 프로젝트에 Poetry 적용하기

기존 프로젝트에 Poetry를 사용하고 싶다면, 프로젝트 루트에서 poetry init 명령어를 실행합니다.

cd my-old-project
poetry init

cd my-old-project
poetry init

이 명령은 대화형으로 프로젝트 정보를 물어보며 pyproject.toml 파일을 생성합니다.

4. 종속성 추가하기

새 패키지는 poetry add로 설치합니다. Poetry는 자동으로 패키지를 설치하고, 설정 파일을 갱신합니다.

# requests 패키지 추가
poetry add requests

# 개발용 종속성 (예: pytest) 추가
poetry add pytest --group dev

# requests 패키지 추가
poetry add requests

# 개발용 종속성 (예: pytest) 추가
poetry add pytest --group dev

--group dev 옵션을 사용하면 pyproject.toml 파일의 [tool.poetry.group.dev.dependencies] 섹션에 종속성이 분리되어 관리됩니다.

5. 종속성 설치하기

poetry.lock 또는 pyproject.toml에 명시된 종속성을 설치하려면 poetry install을 사용합니다.

poetry install

poetry install

poetry.lock 파일이 있으면 해당 파일의 정확한 버전대로 설치하며, 없으면 pyproject.toml을 기반으로 설치하고 poetry.lock을 생성합니다.

개발용 종속성을 포함해 설치하려면:

poetry install --with dev

poetry install --with dev

6. 가상 환경 및 명령어 실행

Poetry는 가상 환경을 자동으로 관리하므로 별도의 활성화 과정이 필요하지 않습니다.

명령어 직접 실행: poetry run python app.py와 같이 poetry run을 사용하여 가상 환경 내에서 스크립트를 실행합니다.
가상 환경 셸 활성화: poetry shell 명령을 사용해 가상 환경 내부의 셸에 진입할 수 있습니다.

7. 종속성 업데이트 및 제거

업데이트: poetry update 명령어로 pyproject.toml에 정의된 범위 내에서 패키지를 최신 버전으로 업데이트합니다. 특정 패키지만 업데이트하려면 poetry update requests와 같이 패키지 이름을 명시합니다.
제거: poetry remove <package> 명령으로 패키지를 삭제합니다.

결론

Poetry는 파이썬 개발자들이 종속성 문제에서 벗어나 프로젝트 관리에 집중할 수 있도록 돕는 강력한 도구입니다. 단일 설정 파일, 완벽한 재현성, 그리고 자동화된 가상 환경 관리 기능은 팀 협업과 프로젝트의 안정성을 크게 향상시킵니다. 직관적인 명령어 구조로 누구나 쉽게 적응할 수 있어, 보다 효율적이고 안정적인 파이썬 개발 환경을 구축하고자 한다면 Poetry를 적극적으로 활용해 보시길 권장합니다.

가상환경 – Poetry