pyproject.toml과 Twine을 이용해 PyPI에 올리기

시작하며

파이썬 패키지를 배포할 때, 예전에는 setup.py만으로 빌드부터 업로드까지 손쉽게 진행했습니다.
그러나 최근에는 pyproject.toml을 활용해 메타데이터와 빌드 정보를 분리하고, Twine을 통해 PyPI에 업로드하는 방식이 점차 자리를 잡아가고 있습니다.

본 포스팅에서는 pyproject.toml의 간단한 예시와, TestPyPI를 거쳐 PyPI에 패키지를 업로드하는 과정을 정리해보겠습니다.

---

pyproject.toml 예시

아래는 PEP 621 방식으로 메타데이터를 관리하는 최소 예시입니다.

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "package_name"
version = "0.1.1"
description = "Package Description"
authors = [
  { name = "username", email = "user@email.com" }
]
readme = "README.md"
keywords = ["keywords"]
requires-python = ">=3.7"
classifiers = [
  "Programming Language :: Python :: 3",
  "License :: OSI Approved :: MIT License",
  "Operating System :: OS Independent",
]
license = { file = "LICENSE" }

[tool.setuptools.packages.find]
exclude = ["tests*"]

1. [build-system]: 빌드에 필요한 라이브러리와 빌드 백엔드를 지정합니다.
2. [project]: 패키지명, 버전, 저자 정보 등을 적어둡니다.
3. license: LICENSE 파일을 읽어와 사용하겠다는 설정입니다.
4. classifiers: PyPI 페이지에서 노출되는 분류 정보입니다.

이렇게 하면 setup.py 없이도 패키지 빌드가 가능합니다.

---

패키지 빌드

pyproject.toml가 준비되었으면, 먼저 필요한 툴을 설치합니다.

python3 -m pip install --upgrade build wheel setuptools

 

만약, pip이 없다고 한다면 다음 명령어를 사용할 수 있습니다.

python3 -m ensurepip --upgrade
python3 -m pip install --upgrade pip

 

이후 아래 명령으로 소스 패키지(*.tar.gz)와 휠(*.whl)을 만들 수 있습니다.

python -m build

빌드가 끝나면 dist/ 디렉토리에 두 종류의 배포 파일이 생성됩니다.

---

TestPyPI 업로드

공식 PyPI에 업로드하기 전에 TestPyPI에서 테스트해볼 수 있습니다.

1. TestPyPI 계정을 만들고, API 토큰을 발급받습니다.
2. 홈 디렉토리에 위치한 ~/.pypirc (Windows의 경우 %USERPROFILE%/.pypirc) 파일에 다음과 같이 설정합니다:
3. [testpypi] repository = https://test.pypi.org/legacy/ username = __token__ password = testpypi-AgEI... ; (실제 발급받은 토큰)
4. Twine을 설치하고 업로드합니다.
5. python3 -m pip install --upgrade twine twine upload --repository testpypi dist/*

업로드가 정상적으로 끝나면 아래 명령으로 설치 테스트를 해볼 수 있습니다.

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple pa

---

실제 PyPI 업로드

TestPyPI에서 문제없이 동작한다면, 이제 공식 PyPI에 배포합니다.

1. PyPI용 계정(또는 토큰)을 발급받고, .pypirc에 [pypi] 섹션을 추가합니다.
2. [pypi] repository = https://upload.pypi.org/legacy/ username = __token__ password = pypi-AgEI... ; (PyPI에서 발급받은 토큰)
3. twine 명령으로 업로드합니다.
4. twine upload dist/*
5. 업로드한 뒤에는 pip install package_name 명령으로 언제든 설치할 수 있습니다.

---

마무리

pyproject.toml과 Twine을 활용하면, 메타데이터 관리와 배포 과정을 좀 더 명확하게 분리할 수 있습니다.
특히 PEP 621 방식을 사용하면, 기존 setup.py 의존도를 줄이면서도 패키지 빌드를 깔끔하게 진행할 수 있습니다.

본 과정은 파이썬 3.7+ 환경, setuptools>=61.0 버전 이상을 가정하고 있으니, 필요에 따라 환경을 점검해보시기 바랍니다.