프로젝트 규모가 커지거나 협업 인원이 늘어날수록 단순한 설치/실행만으로는 부족할 수 있습니다.
이번 포스팅에서는 Poetry의 고급 기능, 버전 범위 지정, PyPI 업로드, CI/CD 연동 등 심화 내용을 다룹니다.
1편에서 배운 기본 개념을 바탕으로, 프로덕션 환경에서도 안정적으로 사용할 수 있는 Poetry 활용법을 익혀 보겠습니다.
I. 개요 & 목차
1. 이번 포스팅에서 다루는 내용
- 버전 범위 지정의 원리: 시맨틱 버저닝(semantic versioning)과 버전 범위(^, ~, >= 등)
- 프로젝트 배포(Publish) & PyPI 업로드: 실제로 패키지를 만들어 배포해 보기
- CI/CD 파이프라인 연동: GitHub Actions, GitLab CI, Jenkins 등과의 연동 예시
- 플러그인(Plugin) 활용: Poetry의 기능 확장하기
- Monorepo 구성에서의 Poetry: 여러 패키지를 하나의 저장소에서 관리하기
- Docker 환경 최적화: Dockerfile 안에서 Poetry를 활용하는 방법
II. 버전 범위 지정의 원리
2.1 시맨틱 버저닝(Semantic Versioning) 이해
제목: 시맨틱 버저닝으로 안전한 패키지 관리하기 (#시맨틱버전 #버전범위 #Poetry고급)
시맨틱 버전(semver)은 일반적으로 MAJOR.MINOR.PATCH 형태를 따릅니다.
- MAJOR 버전이 올라가면 호환성이 깨질 수 있다는 의미
- MINOR 버전은 새로운 기능 추가(하위 호환은 유지)
- PATCH 버전은 버그 수정
Poetry에서는 이러한 시맨틱 버전을 해석하여 ^ (Caret), ~ (Tilde), >=, != 등 다양한 표기법을 허용합니다.
2.2 버전 범위 지정 예시
[tool.poetry.dependencies]
# ^2.25.1 은 2.x대에서 2.25.1 이상 ~ 3.0 미만 버전을 의미
requests = "^2.25.1"
# ~1.4.0 은 1.4.x 버전까지만 허용 (1.5.0부터는 호환성 보장 X)
flask = "~1.4.0"
# >=1.0,<2.0 방식
sqlalchemy = ">=1.4,<2.0"
- Caret(^) 범위와 Tilde(~) 범위를 잘 설정하면, 의존성 충돌을 최소화하면서 자동 업데이트를 효과적으로 관리할 수 있습니다.
Tip: #시맨틱버전 #버전범위 #의존성관리 #Poetry고급
III. 프로젝트 배포 & PyPI 업로드
3.1 PyPI 업로드 준비
제목: Poetry로 내 Python 패키지 PyPI에 업로드하기 (#PyPI #배포 #Poetry고급)
Poetry는 pyproject.toml에 프로젝트 메타데이터(이름, 버전, 라이선스 등)와 배포 정보를 넣어서 PyPI 등에 쉽게 업로드할 수 있습니다.
[tool.poetry]
name = "my-awesome-package"
version = "0.1.0"
description = "My awesome python package"
authors = ["Your Name <you@example.com>"]
license = "MIT"
readme = "README.md"
3.2 빌드 & 배포 절차
- 빌드
poetry build- dist/ 폴더에 소스 배포용(.tar.gz)과 휠(.whl)이 생성됩니다.
- PyPI에 업로드
poetry publish --repository pypi- 최초 사용 시 PyPI 계정 정보를 입력해야 하며, Poetry가 이 정보를 저장합니다.
주의: 테스트가 충분히 이루어지지 않은 상태에서 실제 PyPI(https://pypi.org)로 업로드하기보다는, **TestPyPI(https://test.pypi.org)**로 먼저 업로드해 검증한 뒤 올리는 것이 안전합니다.
Tip: #Poetry배포 #PyPI #테스트배포 #Python패키징
IV. CI/CD 파이프라인 연동
4.1 GitHub Actions 예시
제목: 자동화로 편해지는 GitHub Actions: Poetry 기반 CI/CD (#CI_CD #GitHubActions #Poetry고급)
예시 .github/workflows/ci.yml:
name: CI
on: [push, pull_request]
jobs:
build-and-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Set up Python
uses: actions/setup-python@v2
with:
python-version: '3.9'
- name: Install Poetry
run: |
curl -sSL https://install.python-poetry.org | python -
echo "::add-path::$HOME/.poetry/bin"
- name: Install dependencies
run: poetry install
- name: Run tests
run: poetry run pytest
- 자동 빌드, 테스트, 포맷팅 등을 일관성 있게 수행할 수 있어 협업 효율이 크게 높아집니다.
4.2 다른 CI/CD 도구에서의 활용
- GitLab CI/CD: .gitlab-ci.yml 안에서 poetry install, poetry run pytest 등 비슷한 구조
- Jenkins: sh 'poetry install', sh 'poetry run pytest' 등 쉘 스크립트로 실행
- CircleCI, Azure Pipelines 등도 동일 패턴으로 적용 가능
Tip: #CI_CD #GitHubActions #GitLabCI #Jenkins #Poetry고급
V. Poetry 플러그인(Plugin) 활용
5.1 플러그인 소개
제목: Poetry 플러그인으로 작업 효율 2배 올리기 (#Plugin #개발환경 #Poetry고급)
Poetry는 기본 명령어 외에도 **플러그인(Plugin)**을 통해 기능을 확장할 수 있습니다.
- 예: poetry-dynamic-versioning: Git 태그와 같은 정보를 이용해 버전을 자동 업데이트
- 예: poetry-version-plugin: 특정 명령어로 버전을 쉽게 올리거나 내릴 수 있음
5.2 플러그인 설치 & 사용
poetry self add poetry-dynamic-versioning
- poetry self add를 통해 Poetry 자체에 플러그인을 추가할 수 있습니다.
- 플러그인마다 설정이 조금씩 다르므로, 해당 깃허브 레포지토리나 문서를 참고하세요.
Tip: #PoetryPlugin #개발자동화 #버전관리
VI. Monorepo 구성에서의 Poetry
6.1 Monorepo란 무엇인가?
제목: 여러 패키지를 한 저장소에서: Monorepo와 Poetry (#Monorepo #멀티패키지 #Poetry고급)
- Monorepo: 하나의 Git 저장소(Repo) 안에 여러 개의 서브 프로젝트(혹은 패키지)를 두고, 상호 참조나 공유 로직을 관리하는 방식
- 규모가 큰 조직이나 프로젝트(예: 구글, 페이스북 등)는 Monorepo 전략을 사용하기도 합니다.
6.2 Monorepo에서의 Poetry 설정
- 각 서브 프로젝트마다 pyproject.toml을 두되, 루트 디렉터리에 공통 스크립트나 설정 파일을 배치
- Poetry의 dependency 추가 시, 로컬 경로를 지정하여 서로 다른 서브 프로젝트가 참조할 수 있음
[tool.poetry.dependencies] my-library = { path = "../my-library" }
Tip: #Monorepo #Poetry구성 #대규모프로젝트 #Python패키지공유
VII. Docker 환경 최적화
7.1 Dockerfile에서 Poetry 사용하기
제목: Dockerfile에 Poetry를 통합해 효율 극대화 (#Docker #배포 #Poetry고급)
예시 Dockerfile:
FROM python:3.9-slim
# 1. Poetry 설치
RUN pip install --no-cache-dir poetry
# 2. 프로젝트 복사
WORKDIR /app
COPY pyproject.toml poetry.lock /app/
# 3. 의존성 설치
RUN poetry install --no-root
# 4. 실제 소스 복사
COPY . /app
# 5. 실행 명령
CMD ["poetry", "run", "python", "main.py"]
- 주의: 빌드 과정에서 캐시를 효율적으로 사용하기 위해 pyproject.toml과 poetry.lock을 먼저 복사한 뒤, 의존성을 설치한 후 소스를 복사하는 단계를 분리합니다.
- 이렇게 하면 코드만 변경돼도 이미 설치된 의존성 레이어(layer)를 재활용할 수 있어 빌드 속도가 빨라집니다.
Tip: #Docker #컨테이너빌드 #Poetry #개발환경최적화
VIII. 마무리 & 추가 팁
8.1 정리
제목: Poetry 심화 기능: 완벽한 Python 프로젝트 관리의 시작 (#Poetry고급 #정리)
- 이번 글에서는 Poetry를 보다 심층적으로 파고들어, 버전 범위 지정, PyPI 업로드, CI/CD 파이프라인 연동, 플러그인 사용, Monorepo, Docker 최적화까지 알아보았습니다.
- 프로젝트 규모가 커질수록, 제대로 된 버전 관리 및 자동화된 프로세스가 필수라는 점을 다시금 깨닫게 됩니다.
8.2 더 나은 선택을 위한 제안
- Poetry + pyenv: Python 버전을 자주 전환해야 한다면 pyenv(또는 asdf)와 함께 쓰는 것을 강력 추천합니다.
- Poetry Plugins & Ecosystem: Poerty-related 플러그인이 계속해서 늘어나고 있습니다. 필요한 기능이 있다면 검색해 보세요.
- 테스트 자동화 & 코드 품질 도구: pytest, flake8, black 등과 함께 사용하면 프로젝트 품질을 안정적으로 유지할 수 있습니다.
- Monorepo vs Polyrepo: 팀 상황, 배포 전략에 따라 Monorepo가 꼭 정답은 아닙니다. 규모와 협업 방식을 고려해 결정하세요.
8.3 마무리 인사
제목: Poetry 마스터가 되어 더 효율적인 Python 개발자가 되세요! (#Poetry #Python개발 #고급사용법)
Poetry는 의존성 관리부터 빌드, 배포까지 모든 과정을 체계적으로 관리할 수 있게 해주는 강력한 툴입니다. 작은 프로젝트부터 대형 프로젝트까지 다양하게 활용 가능하니, 필요에 따라 적절한 기능을 조합해 보시기 바랍니다.
더 궁금한 점이 있다면 공식 문서(https://python-poetry.org/docs/)나 해당 커뮤니티를 참고하세요!
전체 요약
- 버전 범위 & 시맨틱 버전 관리: ^, ~, >=, < 등의 표기로 의존성 호환성 범위를 유연하게 설정
- PyPI 업로드: poetry build 및 poetry publish로 손쉽게 패키지 배포
- CI/CD 연동: GitHub Actions, GitLab CI, Jenkins 등과 자동화 파이프라인을 구성
- 플러그인(Plugin) 활용: 기본 기능을 확장하여 버전 자동 업데이트, 배포 옵션 다양화 등 가능
- Monorepo에서의 Poetry: 다중 패키지 구조를 한 저장소에서 효율적으로 관리
- Docker 환경 통합: Dockerfile 단계별 구성으로 캐시 활용 극대화
이로써 프로젝트 라이프사이클 전체에서 Poetry를 활용해볼 수 있는 주요 방법을 모두 살펴보았습니다.
Poetry를 통해 더욱 강력하고 효율적인 Python 개발 환경을 만들어 보세요!
부록: 참고 자료
- 공식 문서: Poetry Docs
- Poetry GitHub: https://github.com/python-poetry/poetry
- TestPyPI: https://test.pypi.org
이상으로 Poetry 사용법 2편을 마칩니다.
앞으로 보다 원활하고 안정적인 Python 프로젝트 개발을 위해, 이번 글에서 소개한 고급 기능들을 꼭 활용해 보시기 바랍니다!