[PYTHON] 라이브러리 개발을 위한 pyproject.toml 표준 활용 방법 5가지와 해결 전략의 차이

pyproject.toml 표준 활용

 

과거 파이썬 패키징의 세계는 setup.py, setup.cfg, requirements.txt 등이 뒤섞인 혼란스러운 상태였습니다. 하지만 PEP 517과 PEP 518의 도입 이후, pyproject.toml은 파이썬 프로젝트의 설정을 통합 관리하는 표준으로 완전히 자리 잡았습니다. 특히 오픈 소스 라이브러리를 개발하고 PyPI에 배포하려는 개발자에게 이 파일을 올바르게 구성하는 것은 배포 자동화와 사용자 경험을 결정짓는 핵심 요소입니다. 오늘 이 글에서는 현대적 라이브러리 개발을 위한 pyproject.toml 표준 활용 방법과 기존 방식과의 결정적 차이를 심도 있게 분석합니다.

---

1. pyproject.toml 표준의 핵심 가치와 도입 배경

왜 우리는 더 이상 setup.py를 사용하지 말아야 할까요? 기존 방식은 실행 가능한 파이썬 스크립트였기 때문에 보안에 취약하고, 빌드 도구(Build Backend)를 미리 알 수 없다는 구조적 결함이 있었습니다. pyproject.toml은 선언적(Declarative) 방식을 채택하여 빌드에 필요한 의존성을 명확히 규정하고, 도구 간의 상호운용성을 극대화하는 해결책을 제시합니다.

---

2. 패키징 도구별 특징 및 pyproject.toml 활용 차이

라이브러리의 목적과 팀의 선호도에 따라 선택할 수 있는 빌드 백엔드는 다양합니다. 주요 도구들의 특성을 비교 분석하였습니다.

빌드 도구 (Backend)	표준 활용 방식	장점 및 차이점	적합한 대상
Hatch	hatchling.build	동적 버전 관리, 강력한 환경 관리	현대적 고성능 라이브러리
Poetry	poetry.core.masonry.api	의존성 해결사가 매우 강력함	애플리케이션 및 일반 라이브러리
Flit	flit_core.buildapi	극도로 단순하고 빠름	순수 파이썬 소규모 모듈
Setuptools	setuptools.build_meta	C 확장 모듈 지원이 우수함	레거시 호환성 및 복잡한 빌드

---

3. 라이브러리 개발자를 위한 5가지 표준 활용 전략

3.1. [build-system]의 엄격한 정의

프로젝트를 빌드하기 위해 어떤 도구가 필요한지 명시하는 가장 중요한 섹션입니다. requires 필드에 빌드 백엔드 패키지를 명시함으로써 환경에 구애받지 않는 일관된 빌드를 보장합니다.

3.2. [project] 메타데이터 표준 준수 (PEP 621)

라이브러리의 이름, 버전, 설명, 저자 정보 등을 특정 도구에 종속되지 않은 표준 포맷으로 작성하십시오. 이는 향후 빌드 도구를 교체하더라도 메타데이터를 재사용할 수 있게 해주는 핵심 해결책입니다.

3.3. 동적 의존성 및 버전 관리 (Dynamic Fields)

소스 코드 내의 __version__ 변수와 파일의 설정값을 동기화하려면 dynamic 필드를 활용하십시오. Hatch나 Flit과 같은 도구는 이를 통해 소스 코드에서 직접 버전을 읽어와 배포 시 반영합니다.

3.4. Entry Points를 통한 CLI 인터페이스 제공

라이브러리가 명령행 도구(CLI)를 포함한다면 [project.scripts] 섹션을 사용하십시오. 사용자가 패키지를 설치할 때 자동으로 실행 파일이 생성되도록 돕습니다.

3.5. 개발 도구 설정 통합 (Tool Integration)

Ruff, Black, Mypy, Pytest 등 다양한 개발 도구의 설정을 [tool.*] 섹션에 통합하십시오. 여러 개의 .ini나 .yaml 파일을 관리할 필요 없이 하나의 파일로 프로젝트 환경을 완결할 수 있습니다.

---

4. Sample Example: 표준 기반 pyproject.toml 구성

다음은 Hatch 백엔드를 사용하며 Ruff와 Pytest 설정을 포함한 고도화된 라이브러리 설정 예제입니다.

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-awesome-lib"
dynamic = ["version"]
description = "표준을 준수하는 강력한 파이썬 라이브러리"
readme = "README.md"
requires-python = ">=3.8"
license = "MIT"
authors = [
    { name = "Chaewon", email = "dev@example.com" },
]
dependencies = [
    "requests>=2.28.0",
    "pydantic>=2.0.0",
]

[project.scripts]
my-cli = "my_lib.cli:main"

[tool.hatch.version]
path = "src/my_lib/__about__.py"

[tool.ruff]
line-length = 88
target-version = "py310"

[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["src"]

---

5. 기존 setup.py 방식과의 결정적 해결 차이

과거의 setup.py는 빌드 시점에 코드를 실행해야 했으므로, 해당 코드가 의존하는 라이브러리가 미리 설치되어 있어야 하는 '닭이 먼저냐 달걀이 먼저냐'의 문제를 일으켰습니다. pyproject.toml은 빌드에 필요한 도구를 선언적으로 나열하여 pip나 build 도구가 격리된 가상 환경을 먼저 만들고 필요한 것을 설치한 뒤 빌드를 시작하게 하므로, 의존성 지옥을 원천적으로 차단합니다.

6. 결론: 표준이 주는 라이브러리 생태계의 안정성

pyproject.toml 표준을 수용하는 것은 단순히 유행을 따르는 것이 아니라, 파이썬 생태계의 건전한 발전에 기여하는 일입니다. 선언적 메타데이터와 통합된 도구 설정은 팀원 간의 협업 효율을 높이고, 사용자에게는 신뢰할 수 있는 설치 경험을 제공합니다. 지금 바로 귀하의 라이브러리에서 setup.py를 걷어내고, 현대적인 pyproject.toml 체계로 전환해 보시길 권장합니다.

---

내용 출처 및 참고 문헌

• Python Packaging User Guide: "Project specification (pyproject.toml)" (2026)
• PEP 621: "Storing project metadata in pyproject.toml"
• PyPA: "Building and Distributing Packages with Modern Tooling"