pyproject.toml: 현대 파이썬 의존성 관리

I’m ready to translate the article for you, but I’ll need the text you’d like translated. Could you please paste the content (or the portion you want translated) here? I’ll keep the source line unchanged and preserve all formatting, markdown, and code blocks as requested.

소개

pyproject.toml은 현대 파이썬 의존성 관리의 계약입니다.
오래된 프로젝트들은 setup.py에 의존하거나 빌드 요구사항을 추측했으며, 이는 깨지기 쉬운 빌드와 재현 불가능한 환경을 초래했습니다. 이 글에서는 주요 PEP(518, 517, 621)를 자세히 살펴보고 pyproject.toml이 python -m venv + python -m pip와 함께 어떻게 예측 가능한 설치를 제공하는지 보여줍니다.

실행 가능한 구성에서 정적 메타데이터로의 전환

역사적으로 프로젝트 구성은 실행 가능한 Python 코드로 작성되었습니다. 유연하지만, 이 접근 방식은 부작용을 일으킬 수 있었고 정적 분석을 어렵게 만들어 신뢰할 수 없는 빌드가 발생했습니다.

pyproject.toml은 도구가 코드를 실행하지 않고도 구문 분석할 수 있는 정적이고 선언적인 형식을 도입합니다.

빌드 시스템 선언

[build-system] 테이블은 설치 프로그램에게 프로젝트를 빌드하기 전에 무엇이 필요한지 알려줍니다.

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

인터페이스가 표준화되어 있기 때문에 pip은 공통 API를 통해 여러 백엔드(setuptools, hatchling, flit, poetry‑core)와 함께 작동할 수 있습니다.

프로젝트 메타데이터

[project] 테이블은 이름, 버전, 의존성, 저자 등을 동적 코드 없이 표준화합니다.

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

[project]
name = "my-service"
version = "0.1.0"
description = "Internal API example"
requires-python = ">=3.11"
dependencies = [
  "fastapi>=0.110",
  "uvicorn[standard]>=0.29",
  "pydantic>=2.7"
]

[project.optional-dependencies]
dev = [
  "pytest>=8",
  "ruff>=0.5",
  "mypy>=1.10"
]

선택적 의존성

optional-dependencies 테이블을 사용하면 dev와 같은 그룹을 정의할 수 있으며, 이는 pip install -e ".[dev]" 로 설치할 수 있습니다.

혜택

일반적인 워크플로우

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .          # install in editable mode
python -m pip install -e ".[dev]"    # install optional dev dependencies

편집 가능한 모드에서는 소스 코드 변경이 매번 패키지를 재설치하지 않아도 반영됩니다.

Common pitfalls

• Missing or incorrect [build-system] – 빌드가 실패하거나 머신마다 일관되지 않게 동작합니다.
• Duplicated dependency declarations (예: requirements.txt와 pyproject.toml 모두에 선언) – 의존성 드리프트를 초래합니다.
• Omitting requires-python – 패키지가 호환되지 않는 인터프리터에 설치되어 런타임에 충돌할 수 있습니다.
• Relying on loose version ranges without a lock file – CI와 로컬 환경 사이에 서로 다른 의존성 그래프가 생성됩니다.

도구 환경

이 모든 도구는 pyproject.toml과 함께 사용할 수 있으며, 이는 파이썬 패키징의 공통 언어가 되었습니다.

환경 문제 해결

환경이 여러 패키지 실험 후 “갑자기” 실패하기 시작한다면, 문제는 코드보다 환경 상태에 있는 경우가 많습니다. pyproject.toml에서 가상 환경을 재생성하는 것이 일관되지 않은 설치를 하나씩 고치는 것보다 보통 더 빠릅니다.

• 오래된 환경 – 실험 후 남겨진 일회용 환경이 임포트를 혼란스럽게 만들 수 있습니다. KillPy와 같은 도구는 연령/크기 기준으로 오래된 환경을 스캔하고 목록화하여 안전하게 제거할 수 있게 해줍니다.

결론

pyproject.toml은 일시적인 유행이 아니라 파이썬 환경 및 의존성 관리의 현대적인 기반입니다. 실제 재현성, 팀 간 마찰 감소, 그리고 예측 가능한 빌드를 위해 이 파일을 워크플로우의 중심에 두세요.