파이썬 패키지 배포: PyPI 게시 및 버전 관리

파이썬의 방대한 생태계는 파이썬 패키지 인덱스(PyPI)를 통해 쉽게 사용할 수 있는 광범위한 패키지 컬렉션에 의해 구동됩니다. 이 가이드는 전 세계 개발자들이 접근할 수 있도록 PyPI를 통해 자신의 파이썬 패키지를 배포하는 방법에 대한 포괄적인 개요를 제공합니다. 고품질 파이썬 패키지를 만들고 게시하기 위한 필수 도구, 버전 관리 모범 사례 및 워크플로우를 살펴보겠습니다.

왜 파이썬 패키지를 배포해야 할까요?

자신의 파이썬 패키지를 배포하면 여러 가지 이점이 있습니다:

• 작업 공유: 다른 개발자들이 코드를 쉽게 재사용하여 협업과 혁신을 촉진할 수 있습니다. 전 세계 팀이 파이썬으로 만든 전문 데이터 분석 도구를 사용한다고 상상해 보세요.
• 의존성 관리: 다른 프로젝트에서 의존성을 관리하는 과정을 단순화합니다. 패키지는 모든 의존성과 함께 단일 명령어로 설치할 수 있습니다.
• 오픈소스 기여: 오픈소스 커뮤니티에 기여하고 작업에 대한 인정을 받을 수 있습니다. 많은 핵심 소프트웨어 구성 요소는 전 세계 개발자들이 유지 관리하는 오픈소스 패키지입니다.
• 버전 관리 및 업데이트: 버전을 관리하고, 업데이트를 릴리스하며, 버그 수정을 처리하는 구조화된 방법을 제공합니다. 이를 통해 사용자는 항상 최신이고 가장 신뢰할 수 있는 버전의 패키지에 접근할 수 있습니다.
• 쉬운 설치: `pip install your-package-name`을 통해 사용자의 설치를 간소화합니다.

파이썬 패키지 배포를 위한 필수 도구

파이썬 패키지를 만들고 배포하는 데 필수적인 몇 가지 도구가 있습니다:

• setuptools: 이름, 버전, 의존성, 진입점(entry points) 등 패키지 메타데이터를 정의하는 데 널리 사용되는 라이브러리입니다. 파이썬 프로젝트 패키징의 사실상 표준입니다.
• wheel: 소스 배포판에 비해 더 효율적이고 신뢰할 수 있는 설치 프로세스를 제공하는 배포 형식입니다. 휠(Wheel)은 컴파일 없이 설치할 수 있는 사전 빌드된 배포판입니다.
• twine: 패키지를 PyPI에 안전하게 업로드하기 위한 도구입니다. Twine은 전송 중 자격 증명과 패키지 데이터를 암호화하여 도청 및 중간자 공격으로부터 보호합니다.
• venv/virtualenv: 격리된 파이썬 환경을 만들기 위한 도구입니다. 가상 환경을 사용하는 것은 의존성을 관리하고 다른 프로젝트 간의 충돌을 피하는 데 매우 중요합니다.

프로젝트 설정하기

패키지를 배포하기 전에 프로젝트를 올바르게 구조화해야 합니다.

프로젝트 구조 예시

my_package/
├── my_package/
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
├── tests/
│   ├── __init__.py
│   ├── test_module1.py
│   └── test_module2.py
├── README.md
├── LICENSE
├── setup.py
└── .gitignore

설명:

• my_package/: 패키지의 소스 코드를 포함하는 주 디렉터리입니다.
• my_package/__init__.py: `my_package` 디렉터리를 파이썬 패키지로 만듭니다. 비어 있거나 초기화 코드를 포함할 수 있습니다.
• my_package/module1.py, my_package/module2.py: 실제 코드를 포함하는 파이썬 모듈입니다.
• tests/: 단위 테스트를 포함하는 디렉터리입니다. 패키지의 품질과 신뢰성을 보장하기 위해 테스트를 작성하는 것이 매우 중요합니다.
• README.md: 패키지 설명, 사용법 및 기타 관련 정보를 제공하는 마크다운 파일입니다. 이는 사용자가 PyPI에서 가장 먼저 보게 되는 내용인 경우가 많습니다.
• LICENSE: 패키지가 배포되는 라이선스(예: MIT, Apache 2.0, GPL)를 포함하는 파일입니다. 다른 사람들이 코드를 어떻게 사용할 수 있는지 명시하기 위해 적절한 라이선스를 선택하는 것이 필수적입니다.
• setup.py: 패키지의 메타데이터와 빌드 지침을 정의하는 주 설정 파일입니다.
• .gitignore: Git이 무시해야 할 파일 및 디렉터리(예: 임시 파일, 빌드 아티팩트)를 지정합니다.

`setup.py` 파일 만들기

`setup.py` 파일은 패키지 배포의 핵심입니다. 패키지에 대한 메타데이터와 빌드 및 설치 지침을 포함합니다. 다음은 예시입니다:

import setuptools

with open("README.md", "r") as fh:
    long_description = fh.read()

setuptools.setup(
    name="my_package",  # 여러분의 패키지 이름으로 바꾸세요
    version="0.1.0",
    author="Your Name",  # 여러분의 이름으로 바꾸세요
    author_email="your.email@example.com", # 여러분의 이메일로 바꾸세요
    description="A small example package",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/yourusername/my_package", # 여러분의 저장소 URL로 바꾸세요
    packages=setuptools.find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',
    install_requires=[
        "requests", # 예시 의존성
    ],
)

설명:

• name: PyPI에서 사용될 패키지의 이름입니다. 고유하고 설명적인 이름을 선택하세요.
• version: 패키지의 버전 번호입니다. 유의적 버전 관리(아래 참조)를 따르세요.
• author, author_email: 여러분의 이름과 이메일 주소입니다.
• description: 패키지에 대한 짧은 설명입니다.
• long_description: 일반적으로 `README.md` 파일에서 읽어오는 더 길고 상세한 설명입니다.
• long_description_content_type: 긴 설명의 형식(예: "text/markdown")을 지정합니다.
• url: 패키지 홈페이지의 URL(예: GitHub 저장소)입니다.
• packages: 배포판에 포함할 패키지 목록입니다. `setuptools.find_packages()`는 프로젝트의 모든 패키지를 자동으로 찾습니다.
• classifiers: 사용자가 PyPI에서 패키지를 찾는 데 도움이 되는 메타데이터입니다. Trove 분류자 목록에서 적절한 분류자를 선택하세요. 지원되는 파이썬 버전, 운영 체제 및 라이선스에 대한 분류자를 포함하는 것을 고려하세요.
• python_requires: 패키지를 사용하는 데 필요한 최소 파이썬 버전을 지정합니다.
• install_requires: 패키지에 필요한 의존성 목록입니다. 이 의존성들은 패키지가 설치될 때 자동으로 설치됩니다.

버전 관리: 유의적 버전 관리(Semantic Versioning)

유의적 버전 관리(SemVer)는 패키지의 변경 사항의 성격을 명확하고 일관된 방식으로 전달하는 널리 채택된 버전 관리 체계입니다.

SemVer 버전 번호는 `주(MAJOR).부(MINOR).수(PATCH)`의 세 부분으로 구성됩니다.

• 주(MAJOR): 하위 호환되지 않는 API 변경이 있을 때 올립니다. 이는 사용자가 코드를 업데이트해야 할 수 있는 중대한 변경을 나타냅니다.
• 부(MINOR): 하위 호환성을 유지하면서 기능을 추가할 때 올립니다. 이는 기존 코드를 손상시키지 않는 새로운 기능이나 개선 사항을 의미합니다.
• 수(PATCH): 하위 호환성을 유지하는 버그를 수정할 때 올립니다. 이는 새로운 기능을 추가하거나 기존 기능을 손상시키지 않는 작은 수정을 위한 것입니다.

예시:

• 1.0.0: 첫 번째 릴리스.
• 1.1.0: 기존 코드를 손상시키지 않고 새로운 기능을 추가했습니다.
• 1.0.1: 1.0.0 릴리스의 버그를 수정했습니다.
• 2.0.0: 하위 호환되지 않는 API 변경이 있었습니다.

SemVer를 사용하면 사용자가 패키지의 새 버전으로 업그레이드할 때의 영향을 이해하는 데 도움이 됩니다.

패키지 빌드하기

`setup.py` 파일 구성이 완료되면 패키지를 빌드할 수 있습니다.

1. 가상 환경 생성: 패키지의 의존성을 격리하기 위해 가상 환경을 만드는 것을 강력히 권장합니다. `python3 -m venv .venv` (또는 `virtualenv .venv`)를 사용한 다음 활성화하세요 (`source .venv/bin/activate` on Linux/macOS, `.venv\Scripts\activate` on Windows).
2. 빌드 의존성 설치: `pip install --upgrade setuptools wheel`을 실행하세요.
3. 패키지 빌드: `python setup.py sdist bdist_wheel`을 실행하세요. 이 명령어는 `dist` 디렉터리에 소스 배포판(sdist)과 휠 배포판(bdist_wheel)이라는 두 개의 배포 파일을 생성합니다.

`sdist`는 소스 코드와 `setup.py` 파일을 포함합니다. `bdist_wheel`은 더 빠르게 설치할 수 있는 사전 빌드된 배포판입니다.

PyPI에 패키지 게시하기

패키지를 게시하기 전에 PyPI (https://pypi.org/)에 계정을 만들고 API 토큰을 생성해야 합니다. 이 토큰은 업로드를 인증하는 데 사용됩니다.

1. PyPI에 등록: https://pypi.org/account/register/로 이동하여 계정을 만드세요.
2. API 토큰 생성: https://pypi.org/manage/account/로 이동하여 "API tokens" 섹션까지 스크롤한 다음 새 토큰을 만드세요. 이 토큰은 패키지를 업로드하는 데 필요하므로 안전하게 보관하세요.
3. Twine 설치: `pip install twine`을 실행하세요.
4. 패키지 업로드: `twine upload dist/*`를 실행하세요. 사용자 이름(__token__)과 비밀번호(생성한 API 토큰)를 입력하라는 메시지가 표시됩니다.

중요 보안 참고: API 토큰을 저장소에 절대 커밋하지 마세요. 안전하게 보관하고 업로드 과정에서 환경 변수나 다른 보안 방법을 사용하여 접근하세요.

패키지 설치 테스트하기

패키지를 게시한 후에는 올바르게 설치되는지 테스트하는 것이 필수적입니다.

1. 새 가상 환경 생성: 깨끗한 환경에서 설치를 테스트하기 위함입니다.
2. 패키지 설치: `pip install your-package-name`을 실행하세요.
3. 패키지 가져오기 및 사용: 파이썬 인터프리터에서 패키지를 가져와 예상대로 작동하는지 확인하세요.

지속적인 통합 및 지속적인 배포(CI/CD)

패키지의 빌드, 테스트 및 게시 프로세스를 자동화하기 위해 GitHub Actions, GitLab CI 또는 Travis CI와 같은 CI/CD 도구를 사용할 수 있습니다.

다음은 패키지를 빌드하여 PyPI에 게시하는 GitHub Actions 워크플로우 예시입니다:

name: Publish to PyPI

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Set up Python 3.x
      uses: actions/setup-python@v2
      with:
        python-version: 3.x
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install setuptools wheel twine
    - name: Build package
      run: python setup.py sdist bdist_wheel
    - name: Publish package to PyPI
      run: |
        twine upload dist/* \
          -u __token__ \
          -p ${{ secrets.PYPI_API_TOKEN }}

설명:

• 이 워크플로우는 GitHub에서 새 릴리스가 게시될 때 트리거됩니다.
• 코드를 체크아웃하고, 파이썬을 설정하고, 의존성을 설치하고, 패키지를 빌드한 다음 PyPI에 업로드합니다.
• secrets.PYPI_API_TOKEN은 PyPI API 토큰을 저장하는 GitHub 시크릿입니다. 이 시크릿은 GitHub 저장소 설정에서 구성해야 합니다.

파이썬 패키지 배포 모범 사례

• 포괄적인 문서 작성: 상세한 `README.md` 파일과 Sphinx와 같은 도구를 사용한 API 문서를 포함하세요. 명확하고 완전한 문서는 패키지를 사용하기 쉽게 만드는 데 매우 중요합니다.
• 단위 테스트 작성: 코드의 품질과 신뢰성을 보장하기 위해 철저히 테스트하세요. pytest나 unittest와 같은 테스트 프레임워크를 사용하세요.
• PEP 8 스타일 가이드라인 준수: 일관되고 읽기 쉬운 코드를 위해 파이썬 개선 제안 8(PEP 8) 스타일 가이드를 따르세요.
• 라이선스 사용: 다른 사람들이 코드를 어떻게 사용할 수 있는지 명시하기 위해 적절한 오픈소스 라이선스를 선택하세요.
• 의존성을 최신 상태로 유지: 버그 수정, 보안 패치 및 새로운 기능의 이점을 얻기 위해 패키지의 의존성을 정기적으로 업데이트하세요.
• 가상 환경 사용: 의존성을 격리하기 위해 항상 가상 환경 내에서 패키지를 개발하고 테스트하세요.
• 국제화(i18n) 및 현지화(l10n) 고려: 패키지가 사용자에게 표시되는 텍스트나 데이터를 처리하는 경우, 다른 언어와 지역에 적응할 수 있도록 만드세요. 이는 잠재적인 전 세계 사용자 기반을 확장합니다. Babel과 같은 도구가 도움이 될 수 있습니다.
• 다양한 시간대 및 통화 처리: 패키지가 날짜, 시간 또는 금융 거래를 다루는 경우, 전 세계의 다양한 시간대와 통화를 염두에 두세요. 이러한 복잡성을 올바르게 처리하기 위해 적절한 라이브러리와 API를 사용하세요.
• 명확한 오류 메시지 제공: 사용자가 무엇이 잘못되었고 어떻게 수정해야 하는지 이해하는 데 도움이 되는 유익한 오류 메시지를 작성하세요. 가능하다면 이러한 오류 메시지를 다른 언어로 번역하세요.
• 접근성 고려: 패키지의 인터페이스와 문서를 디자인할 때 장애가 있는 사용자를 고려하세요. 모든 사람이 패키지를 사용할 수 있도록 접근성 가이드라인을 따르세요.

고급 주제

• 네임스페이스 패키지: 단일 파이썬 패키지를 여러 디렉터리 또는 여러 배포판에 걸쳐 분할할 수 있습니다.
• 진입점(Entry points): 다른 패키지나 명령줄에서 호출할 수 있는 함수나 클래스를 정의할 수 있습니다.
• 데이터 파일: 파이썬이 아닌 파일(예: 데이터 파일, 설정 파일)을 배포판에 포함할 수 있습니다.
• 조건부 의존성: 특정 조건(예: 특정 운영 체제)에서만 필요한 의존성을 지정할 수 있습니다.

결론

PyPI에 파이썬 패키지를 배포하는 것은 여러분의 작업을 전 세계와 공유하고 파이썬 생태계에 기여하는 훌륭한 방법입니다. 이 가이드에서 설명한 단계와 모범 사례를 따르면 설치, 사용, 유지 관리가 쉬운 고품질 파이썬 패키지를 만들고 게시할 수 있습니다. 패키지의 성공을 위해 명확한 문서화, 철저한 테스트, 일관된 버전 관리를 우선시하는 것을 잊지 마세요.