Python 패키지 빌드 설정 파일

📌 pyproject.toml 설명

pyproject.toml은 Python 패키지 빌드를 위한 표준 설정 파일입니다.
기존 setup.py와 setup.cfg를 대체하며, PEP 518 / 517 / 621에서 정의되었습니다.

📌 pyproject.toml 기본 구조

[build-system]   # 빌드 시스템 정의
[project]        # 패키지 기본 정보
[tool.setuptools] # setuptools 관련 설정
[tool.setuptools.package-data] # 추가 데이터 파일 설정
[project.scripts] # 실행 가능한 CLI 명령어 설정

📌 주요 섹션 상세 설명

1️⃣ [build-system] (필수)

패키지를 빌드할 때 사용할 빌드 시스템을 지정합니다.

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

• requires → 패키징을 위해 필요한 라이브러리 지정
• build-backend → 패키징을 수행할 엔진 지정 (setuptools.build_meta 권장)

2️⃣ [project] (패키지 기본 정보)

패키지의 메타데이터를 정의하는 섹션입니다.

[project]
name = "my_package"   # 패키지 이름
version = "0.1.0"     # 버전
description = "My Python package" # 설명
readme = "README.md"  # 설명 파일
authors = [{ name = "Your Name", email = "your@email.com" }]
license = { file = "LICENSE" }
dependencies = [      # 패키지 설치 시 필요한 의존성 목록
    "requests",
    "pydantic"
]

• name → 패키지 이름
• version → 버전 (0.1.0, 1.0.0 등)
• description → 패키지 설명
• readme → 패키지 설명 문서 (README.md 사용 가능)
• authors → 저자 정보 (이메일 포함 가능)
• license → 라이선스 (MIT, Apache-2.0 등)
• dependencies → 패키지 설치 시 필요한 의존성 목록

3️⃣ [tool.setuptools] (패키지 관리)

Setuptools를 사용할 때 패키지를 어떻게 찾을지 정의합니다.

[tool.setuptools]
packages = ["my_package"]  # 포함할 패키지 목록
package-dir = { "" = "src" }  # 소스 코드 위치 지정
include-package-data = true  # 추가 파일 포함 여부

• packages → 포함할 패키지 리스트 (find_packages() 대체)
• package-dir → 패키지의 루트 디렉토리 (src 폴더를 사용할 경우 설정)
• include-package-data → package_data에서 정의한 추가 파일 포함 여부

4️⃣ [tool.setuptools.package-data] (추가 데이터 파일 포함)

패키징할 때 .env, .json, .yaml 등의 비코드 파일을 포함하는 설정입니다.

[tool.setuptools.package-data]
"my_package" = ["config.json", "settings.yaml"]

• my_package → 패키지명 ("" 대신 실제 패키지명 사용)
• config.json, settings.yaml → 패키징할 추가 파일 목록

5️⃣ [project.scripts] (CLI 실행 파일)

패키지를 설치하면 실행할 수 있는 CLI 명령어를 정의합니다.

[project.scripts]
my-tool = "my_package.main:run"

위 설정이 있으면, 설치 후 아래 명령어를 실행 가능합니다.

my-tool  # my_package.main.run() 실행됨

📌 pyproject.toml vs setup.py 비교

pyproject.toml은 정적인 설정 파일이기 때문에 빌드 속도가 더 빠르고, 유지보수가 쉽습니다.

📌 패키징 빌드 & 설치 명령어

1️⃣ 패키지 빌드

pip install build
python -m build

📌 dist/ 폴더에 .whl 및 .tar.gz 파일 생성됨

2️⃣ 로컬 설치

pip install .

3️⃣ PyPI 업로드

pip install twine
twine upload dist/*

📌 정리

이제 pyproject.toml을 활용하여 빠르고 간편하게 Python 패키징을 할 수 있습니다! 🚀

📌 pyproject.toml 변경 배경 및 역사

Python 패키징 방식이 기존 setup.py에서 pyproject.toml로 변경된 주요 시점은 PEP 518 (2018년) 이후입니다.

📌 주요 PEP 및 내용

1️⃣ PEP 518 (2018년) – pyproject.toml 기본 도입

• pyproject.toml을 패키지 빌드 설정 파일로 정의
• 기존 setup.py가 아닌 TOML 형식으로 빌드 시스템을 명확하게 설정 가능
• [build-system] 섹션을 추가하여 빌드 시스템을 명확히 지정

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

2️⃣ PEP 517 (2019년) – 빌드 백엔드 표준화

• pyproject.toml을 사용하여 커스텀 빌드 시스템 지원
• 기존 setup.py 없이 flit, poetry, setuptools 등 다양한 빌드 시스템을 지원
• build-backend 필드 추가

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

📌 setuptools 대신 flit 사용 가능

[build-system]
requires = ["flit_core>=3.2,<4"]
build-backend = "flit_core.buildapi"

3️⃣ PEP 621 (2020년) – project 섹션 표준화

• 패키지 메타데이터를 pyproject.toml에서 직접 설정 가능 (setup.py 없이 가능)
• [project] 섹션을 추가하여 패키지명, 버전, 의존성 등 설정 가능
• setup.py, setup.cfg 없이 패키징 가능하게 변경됨

[project]
name = "my_package"
version = "0.1.0"
description = "My Python package"
dependencies = ["requests", "pydantic"]

📌 현재 (setuptools >= 61.0.0 이후)

• 2022년 이후 setuptools 61.0.0부터 setup.py 없이 pyproject.toml 만으로 패키징 가능
• setuptools.build_meta가 기본 백엔드로 지정됨
• setup.py 사용이 점차 줄어들고 있음

📌 최신 방식 (setuptools 61.0.0+)

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

[project]
name = "my_package"
version = "0.1.0"
dependencies = ["requests", "pydantic"]

📌 정리

이제 setup.py 없이 pyproject.toml만으로 Python 패키지를 빌드 및 배포하는 것이 표준이 되었습니다. 🚀