[pyproject.toml 완전 정복 3편] [project] 섹션: PEP 621 표준 메타데이터 정의

PEP 621은 pyproject.toml을 통해 패키지 메타데이터(이름, 버전, 라이선스, 종속성 등)를 표준화하는 제안으로, 이전 setup.py에서 하던 패키지 정보 정의를 더욱 일관되고 선언적인 형태로 바꾸어줍니다. 이를 통해 빌드 백엔드별 메타데이터 정의 방식의 차이를 줄이고, 프로젝트 정보가 한눈에 들어오는 장점을 누릴 수 있습니다.

이번 글에서는 [project] 섹션 필드들, PEP 621에서 권장하는 메타데이터 정의 방법, 및 의존성과 optional dependencies 선언 방식 등을 살펴봅니다.

[project] 섹션 개요

[project] 섹션은 PEP 621에 따라 다음과 같은 패키지 메타데이터 필드를 포함할 수 있습니다.

• name: 패키지 이름
• version: 패키지 버전 문자열(PEP 440 준수)
• description: 짧은 패키지 설명
• readme: 프로젝트 README 파일 경로 또는 내용
• license: 라이선스 정보(문자열 또는 파일 경로)
• authors, maintainers: 저자/유지보수자 정보 (이름, 이메일)
• keywords, classifiers, urls: PyPI 메타데이터 개선용
• dependencies: 런타임 의존성 리스트
• optional-dependencies: 선택적 의존성 그룹 정의

예시:

[project]
name = "my_package"
version = "0.1.0"
description = "A wonderful Python package"
readme = "README.md"
license = "MIT"
authors = [
  {name="Alice", email="alice@example.com"}
]
maintainers = [
  {name="Bob", email="bob@example.com"}
]
keywords = ["example", "tutorial"]
classifiers = [
  "Programming Language :: Python :: 3",
  "License :: OSI Approved :: MIT License",
]

dependencies = [
  "requests>=2.26.0,<3.0.0",
  "numpy>=1.20.0"
]

[project.optional-dependencies]
dev = [
  "pytest",
  "mypy"
]
docs = [
  "sphinx"
]

이런 식으로 [project] 섹션이 setup.py 없이도 패키지 정보를 일원화합니다.

주요 필드 상세 설명

• name: PyPI에 등록할 공식 패키지 이름, 소문자와 하이픈 사용 권장
• version: PEP 440 규칙 준수(예: "0.1.0", "1.0.0rc1")
• authors, maintainers: 리스트 형태로 사람 정보 기재, PyPI에 표시
• dependencies: 런타임 시 필요한 패키지, 버전 범위 명시 가능
• optional-dependencies: 추가 기능용 별도 의존성 그룹(예: dev, docs, test) 정의

이렇게 하면 pip install my_package[dev] 형태로 선택적 의존성 그룹을 설치할 수도 있습니다.

PEP 621의 의의

PEP 621은 프로젝트 메타데이터를 빌드 백엔드와 독립적으로 표준화하려는 시도입니다. 이전에는 setuptools나 flit, poetry 등 각 빌드 백엔드마다 메타데이터 정의 방식이 달랐고, setup.py 코드로 임의 로직을 추가하는 경우도 많았습니다. 이제 pyproject.toml 내 [project] 섹션을 사용하면 빌드 백엔드가 무엇이든 표준화된 필드로부터 메타데이터를 가져갈 수 있어, 도구 상호 호환성과 단순성이 향상됩니다.

의존성 관리 전략

dependencies 필드에 런타임 의존성을 나열하고, optional-dependencies로 추가 기능별 의존성 그룹화하면 사용자나 개발자가 특정 기능에 필요한 의존성만 설치할 수 있습니다. 이는 패키지 유연성 및 유지보수성 증가에 기여합니다.

테스트나 문서 빌드를 위해 dev나 docs 그룹을 정의하면, pip install .[dev] 또는 Poetry, Flit 등 빌드 툴 명령을 통해 쉽게 해당 그룹 설치 가능.

주의사항

• PEP 621을 지원하는 빌드 백엔드 사용 필요. Poetry, Hatch, setuptools(최신 버전), Flit 등 대부분 지원
• version 필드에 동적으로 버전 설정을 원하는 경우 PEP 621 표준에는 명시적 버전 지정 권장. Poetry 등 도구에서 version = "0.1.0" 대신 version = {from=...}같은 방식도 있으나 빌드 백엔드별 지원 여부 확인 필요.
• authors, maintainers 등 필수는 아니지만 PyPI 메타데이터를 풍성히 하면 사용자 경험 개선

결론

• [project] 섹션은 PEP 621에 따른 표준 메타데이터 정의 공간
• 이름, 버전, 의존성, 라이선스 등 패키지 핵심 정보를 한 곳에 명시, setup.py 없이도 일관성 유지
• 의존성 및 optional-dependencies로 기능별 의존성 관리 용이, 도구 간 호환성↑

다음 글에서는 [project.dependencies]와 [project.optional-dependencies] 설정을 비롯한 의존성 관리와 스크립트 정의를 더 구체적으로 다루며, pyproject.toml을 통한 의존성 처리 패턴을 심화해보겠습니다.