[pyproject.toml 완전 정복 5편] [tool.*] 섹션으로 빌드 백엔드 및 린터·포매터 설정 통합

기존 파이썬 프로젝트에서는 setup.cfg, .flake8, mypy.ini, tox.ini 등 다양한 도구별 설정 파일이 난립하는 경우가 많았습니다. 하지만 pyproject.toml의 [tool.*] 섹션을 이용하면, 이러한 도구 설정을 한 파일로 모아 프로젝트 구성이 훨씬 단순해집니다.

이번 글에서는 [tool] 섹션의 개념과 활용법, Poetry나 Flit, Hatch 등 빌드 백엔드별 설정 예제, 그리고 린터/포매터/테스트 도구 설정을 pyproject.toml에 통합하는 방법을 살펴봅니다.

[tool.*] 섹션 개념

pyproject.toml는 [tool]이라는 상위 테이블을 제공하며, 하위에 도구명(예: poetry, flit, hatch, black, isort, mypy)을 붙여 [tool.poetry], [tool.black] 처럼 특정 도구의 설정을 모듈화할 수 있습니다.

예:

[tool.poetry]
name = "my_package"
version = "0.1.0"
dependencies = ["requests"]

[tool.black]
line-length = 88
target-version = ["py39"]

[tool.isort]
profile = "black"

이렇게 하면 poetry 관련 설정, black 포매터 설정, isort 정렬 옵션을 한 곳에서 관리할 수 있습니다.

빌드 백엔드별 설정 예제

Poetry 설정

Poetry는 tool.poetry 하위에 패키지 정보, 의존성, 스크립트 등 다양한 설정을 담을 수 있습니다. 사실 [project]와 [project.*]를 쓰는 PEP 621 방식을 Poetry도 지원하지만, 구버전 Poetry 프로젝트나 추가 Poetry 전용 옵션을 [tool.poetry] 섹션에 둘 수도 있습니다.

[tool.poetry]
name = "my_package"
version = "0.1.0"
description = "My fancy package"
authors = ["Alice <alice@example.com>"]

[tool.poetry.dependencies]
requests = "^2.26.0"

[tool.poetry.dev-dependencies]
pytest = "^6.2"

[tool.poetry.scripts]
mytool = "my_package.cli:main"

Poetry는 이 정보를 바탕으로 poetry install, poetry build 등을 실행할 때 필요한 정보를 얻습니다.

Flit 설정

Flit은 [tool.flit.metadata] 섹션에 메타데이터를, [tool.flit.sdist] 등에 빌드 관련 옵션을 정의합니다.

[tool.flit.metadata]
module = "my_package"
author = "Bob"
author-email = "bob@example.com"
requires = ["requests"]

Flit은 간결한 패키징에 특화되어 있어 프로젝트 설정이 매우 최소화될 수 있습니다.

Hatch, Black, isort 등 기타 도구 설정

• Hatch: [tool.hatch.*] 섹션에 버전 관리, 릴리스 전략, 환경 설정 등
• Black 포매터: [tool.black] 섹션에 line-length, exclude 경로 등 포맷팅 옵션
• isort: [tool.isort] 섹션에 import 정렬 규칙
• mypy: [tool.mypy] 섹션에 타입 체크 옵션

예:

[tool.black]
line-length = 88
exclude = "build/"

[tool.isort]
profile = "black"

[tool.mypy]
strict = true
disallow_untyped_defs = true

이렇게 하면 black, isort, mypy 명령어 실행 시 pyproject.toml에서 설정을 읽어들여 일관된 규칙을 적용합니다.

장단점

장점:

• 설정 중앙화: 빌드, 의존성, 도구 설정을 pyproject.toml 하나로 관리
• 파일 개수 감소: 별도 .flake8, mypy.ini 없이도 pyproject.toml에 통합 가능
• 도구 간 호환성↑: 많은 도구들이 pyproject.toml 지원
• 명확한 버전관리 및 CI/CD 파이프라인 단순화

단점:

• 모든 도구가 pyproject.toml 지원하는 것은 아님(점차 증가 추세)
• 대규모 프로젝트에서 pyproject.toml이 방대해질 수 있으므로 섹션별 명확한 구조화 필요

결론

• [tool.*] 섹션을 통해 빌드 백엔드 설정뿐 아니라 린터, 포매터, 테스트 툴 설정을 한 곳에 모아 관리
• 기존에 산재해 있던 INI, cfg, RC파일 등을 없애거나 최소화 가능
• 프로젝트 설정 및 유지보수성 획기적 개선

다음 글에서는 다양한 빌드 백엔드를 비교(Flit, Poetry, Hatch 등)하고 pyproject.toml을 활용한 빌드/배포 전략을 제시하며, 프로젝트 특성에 맞는 빌드 백엔드 선택 방법을 알아보겠습니다.