여기서는 설정 항목을 외우기보다 무엇으로 빌드하는지, 무슨 프로젝트인지, 어떤 의존성을 선언하는지를 먼저 봅니다.
pyproject.toml은 패키징 파일이면서 동시에 프로젝트 설정의 중심점으로 읽는 편이 맞습니다.
빠른 설정
[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "sample-app"
version = "0.1.0"
dependencies = ["requests>=2.32"]기본 구조
기본형은 [build-system], [project], dependencies, [tool.*]까지 같이 보면 됩니다.
[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "sample-app"
version = "0.1.0"
dependencies = ["requests>=2.32"]
[tool.pytest.ini_options]
addopts = "-q"[build-system]은 빌드 도구를, [project]는 프로젝트 메타데이터를, [tool.*]는 도구별 설정을 담습니다.
그래서 파일을 읽을 때도 "빌드 방식 -> 프로젝트 정보 -> 도구 설정" 순서로 보면 정리가 빠릅니다.
빌드 방식
무엇으로 빌드하는지는 [build-system]에서 본다
[build-system]은 무엇으로 패키지를 빌드할지 정합니다.
[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.build_meta"즉 "어떤 도구가 이 프로젝트를 빌드하나"를 설명하는 영역입니다.
프로젝트 정보
프로젝트 자체 정보와 의존성은 [project]에서 읽는다
프로젝트 이름, 버전, 설명, 의존성 같은 메타데이터는 [project] 아래에 둡니다.
[project]
name = "sample-app"
version = "0.1.0"
dependencies = [
"requests>=2.32",
]즉 "어떻게 빌드하는가"와 "무슨 프로젝트인가"를 분리해 읽으면 구조가 명확해집니다.
의존성 선언을 코드 바깥에 모아 두면 환경 재현과 배포가 쉬워집니다.
도구 설정
formatter, linter, test 설정도 [tool.*]에 모일 수 있다
실제 프로젝트에서는 formatter, linter, test 도구 설정이 [tool.*] 섹션에 같이 모이는 경우가 많습니다.
그래서 이 파일은 패키징만이 아니라 프로젝트 운영 중심 파일처럼 보이기도 합니다.
[tool.pytest.ini_options]
addopts = "-q"
testpaths = ["tests"]즉 pyproject.toml은 패키징 정보만 담는 파일이 아니라, 프로젝트 도구 설정을 한곳에 모으는 허브 역할도 합니다.
선언 위치
README가 아니라 공식 설정 파일에 선언해야 재현 가능하다
의존성이나 메타데이터를 README에만 적어 두면 설치와 재현이 어렵습니다.
실제로 설치/빌드에 필요한 정보는 pyproject.toml 같은 공식 설정 파일에 있어야 합니다.
주의할 점
의존성을 코드 주석이나 README에만 적어 두면 환경 재현이 어렵습니다. 설치에 필요한 정보는 pyproject.toml 같은 공식 설정 파일에 있어야 합니다.
# ❌ 의존성이 선언되지 않음
[project]
name = "sample-app"
version = "0.1.0"
# ✅ 필요한 런타임 의존성을 명시
[project]
name = "sample-app"
version = "0.1.0"
dependencies = ["requests>=2.32"]
# ❌ 빌드 방식이 빠져 있으면 패키징 도구가 무엇을 써야 할지 불분명
[project]
name = "sample-app"
version = "0.1.0"
# ✅ 빌드 시스템과 프로젝트 메타데이터를 함께 선언
[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.build_meta"참고 링크
2 sources