Poetry를 사용한 Python 패키지 PyPI 게시 | 가이드

# PyPI에 Python 패키지 배포하기: Poetry를 사용한 프로세스 자동화

자신의 Python 패키지를 PyPI 저장소에 배포하는 것은 코드를 재사용하고자 하는 개발자에게 필수적인 단계입니다. Poetry 도구는 의존성을 처리하고 빌드 아티팩트를 생성함으로써 이 프로세스를 크게 단순화합니다. 이 가이드는 프로젝트 준비, 환경 설정, 패키지 배포를 상세히 설명하며, API 토큰 사용과 선택적 의존성을 포함합니다.

계정 설정 및 API 토큰 생성

첫 번째 단계는 공식 PyPI 웹사이트에서 계정을 만드는 것입니다. 등록 후 배포 시 인증을 위해 API 토큰을 생성하세요. 계정 대시보드에서 API 토큰 섹션으로 이동해 Generate API token을 클릭합니다. 토큰 이름을 지정하고 범위를 선택하세요. 새 프로젝트의 경우 등록된 패키지가 없으므로 계정 수준 토큰(Entire account)이 적합합니다. 중요: 생성 직후 토큰을 복사하세요. 다시 표시되지 않습니다.

생성 프로세스는 다음과 같습니다:

• PyPI 계정에 로그인
• API 토큰 관리 섹션으로 이동
• 토큰 이름과 범위 지정
• 생성 확인 및 토큰 값 저장

Poetry는 이 토큰을 사용하여 로그인과 비밀번호 없이 안전하게 배포합니다. 비밀번호처럼 안전하게 보관하세요.

Poetry로 프로젝트 초기화

프로젝트 루트 디렉터리를 만들고 가상 환경을 설정하세요:

python3 -m venv .venv
source .venv/bin/activate

pip를 통해 Poetry를 설치하고 초기화를 실행하세요:

pip install poetry
poetry init

대화형 모드에서 기본 매개변수를 입력하세요: 패키지 이름, 버전, 설명, 작성자, 지원 Python 버전. 생성된 pyproject.toml 파일의 주요 필드:

• name — PyPI의 고유 패키지 이름 (코드 디렉터리의 snake_case 이름과 일치해야 함)
• version — 패키지의 의미적 버전
• python — 지원 인터프리터 버전 범위
• readme — 설명 파일 경로
• packages — 소스 코드 디렉터리 포인터

초기화 후 코드 디렉터리를 만들고 (하이픈을 언더스코어로 변환), 기본 파일 구조를 추가하세요.

프로젝트 구조 및 구성

전형적인 프로젝트 구조는 다음과 같습니다:

my-package/
├── LICENSE
├── poetry.lock
├── pyproject.toml
├── README.md
└── my_package/
    ├── __init__.py
    └── core.py

pyproject.toml의 패키지 이름이 코드 디렉터리 이름과 정확히 일치하는 것이 매우 중요합니다. 예를 들어 name = "my-package"인 경우 디렉터리는 my_package이어야 합니다. __init__.py 파일에서는 사용 편의를 위해 주요 함수를 가져오는 것이 좋습니다.

core.py의 예시 구현:

PREPEND_STR = 'prepend_'

def modify_str(string: str) -> str:
    return f'{PREPEND_STR}{string}'

MIT 라이선스 파일과 기능 설명이 포함된 README.md를 반드시 추가하세요. 배포 전에 poetry lock으로 의존성을 잠그세요.

패키지 빌드 및 배포

저장소에 업로드하기 전에 아티팩트를 빌드하세요:

poetry build

이 명령은 dist/ 디렉터리에 소스 배포판(.tar.gz)과 휠 파일(.whl)을 생성합니다. 다음으로 Poetry에 API 토큰을 설정하세요:

poetry config pypi-token.pypi pypi-XXXXXXXX

pypi-XXXXXXXX을 실제 토큰으로 교체하세요. 이제 배포하세요:

poetry publish

성공 시 PyPI 업로드 확인 메시지를 볼 수 있습니다. PyPI 사이트에서 검색하거나 로컬에 설치하여 확인하세요:

pip install my-package

선택적 의존성 작업

선택적 구성 요소(pip install package[extra]로 설치)를 구현하려면 pyproject.toml을 다음과 같이 구성하세요:

[tool.poetry.dependencies]
python = "^3.10"
pydantic = {version=">=1.9", optional = true}

[tool.poetry.extras]
pydantic = ["pydantic"]

여기서 pydantic 의존성은 optional = true로 선택적으로 표시되며, extras 섹션은 이 라이브러리를 포함하는 pydantic 그룹을 만듭니다. 사용자는 pip install my-package[pydantic]로 extras를 설치할 수 있습니다.

주요 사항

• pyproject.toml의 패키지 이름이 코드 디렉터리 이름과 엄격히 일치해야 함 (하이픈 → 언더스코어)
• 사용자 신뢰를 위해 라이선스와 상세한 README.md를 항상 포함
• 안전한 배포를 위해 로그인/비밀번호 대신 API 토큰 사용
• 선택적 의존성의 경우 dependencies와 extras 섹션을 적절히 구성
• 배포 전에 poetry build로 빌드 확인

— Editorial Team