现代 Python 项目管理：pyproject.toml 完全指南

Intro

最近打算构建一些开源工具套件，想着能不能把 ruff, darglint, mypy 这些 lint 工具全部 all in one 整合一下，化简配置流程，因此详细看了一下这些框架是怎么做 pyproject.toml 配置的。

在 Python 项目开发的历史长河中，我们经历了从 setup.py 到 requirements.txt，再到 setup.cfg 的变迁。

所以你可以看到到 python 会有各种各样的配置文件，属实有点头疼，各种工具链也到处配置，真的不让人省心…

而现在，pyproject.toml 的出现标志着 Python 项目管理进入了一个新的时代，本文会详细解读一下这个现代 Python 项目管理的核心配置文件。

为什么需要 pyproject.toml？

在传统的 Python 项目中，我们往往需要维护多个配置文件：

• setup.py 用于项目打包
• requirements.txt 管理依赖
• setup.cfg 存放项目元数据
• 各种工具的配置文件（.pylintrc、pytest.ini 等）

这种分散的配置方式带来了几个问题：

1. 配置分散，难以统一管理
2. 不同文件格式增加学习成本
3. 工具配置可能存在冲突
4. 项目结构不够清晰

pyproject.toml 的出现就是为了解决这些问题。它提供了一个集中的、标准化的配置方式，让项目管理变得更加简单和清晰。

pyproject.toml 的标准之路

PEP 518：奠定基础

2016 年，PEP 518 提案定义了 pyproject.toml 文件的基本结构和构建系统规范。这个提案主要解决了 Python 项目构建时的依赖问题，让构建过程变得更加可靠。

Link: https://peps.python.org/pep-0518/

PEP 621：统一项目元数据

2020 年，PEP 621 进一步规范化了项目元数据的格式，使得不同的构建后端都能以统一的方式处理项目信息。

Link: https://peps.python.org/pep-0621/

pyproject.toml 的核心结构

1. 构建系统配置

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

这部分定义了构建项目所需的工具和后端。

2. 项目元数据

[project]
name = "your-awesome-project"
version = "0.1.0"
description = "一个很棒的项目"
authors = [
    {name = "作者名", email = "author@example.com"}
]
dependencies = [
    "requests>=2.24.0",
    "pandas>=1.0.0"
]

这里包含了项目的基本信息和依赖要求。

3. 开发依赖和可选功能

[project.optional-dependencies]
dev = ["pytest", "black", "mypy"]
docs = ["sphinx", "sphinx-rtd-theme"]

你可以定义不同场景下需要的额外依赖。

4. 工具配置

[tool.black]
line-length = 88
target-version = ['py37']

[tool.isort]
profile = "black"

[tool.pytest.ini_options]
minversion = "6.0"
addopts = "-ra -q"

各种开发工具的配置都可以统一在这里管理。

现代化工具支持

现代 Python 项目管理工具都对 pyproject.toml 提供了很好的支持ÿ