bot_vault

What the Heck Is pyproject.toml?

2 min read

Summary

Brett Cannon (Python core developer) explains the origin and purpose of pyproject.toml, tracing it back to PEP 518 (specifying build dependencies) and PEP 517 (standardizing build execution). The file solves the chicken-and-egg problem of setuptools needing to be installed before it could declare its own requirements. It has since become the universal configuration hub for Python tooling.

Brett Cannon 詳細解釋了 pyproject.toml 的由來，源自 PEP 518（指定建置依賴）與 PEP 517（標準化建置執行）。這個檔案解決了 setuptools 必須預先安裝才能宣告自身依賴的循環矛盾，並逐漸成為 Python 生態系的統一設定中心。

Key Points

  • PEP 518 introduced pyproject.toml so tools like pip know which build dependencies to install before building
  • PEP 517 standardized how build tools are actually invoked, enabling tools beyond setuptools (flit, Poetry)
  • Build isolation: pip now builds each project in a virtual environment to prevent dependency conflicts
  • Tools like Black, coverage.py, tox adopted pyproject.toml as a unified config file, reducing total config file count

Insights

The file was originally intended only for build system specification, but the ecosystem collectively ignored the prohibition on other uses — and the PEP was later updated to allow it. This is a rare case where community practice shaped the specification retroactively. The key insight is that pyproject.toml reduces, not increases, config file sprawl when tools consolidate around it.

Connections

Raw Excerpt

PEP 518 gets the build tools installed and PEP 517 gets them executed. This opens the door to using other tools by standardizing how to run build tools.

Graph View

Backlinks