pyproject.toml

💡 提示 自 2022 年起，Python 打包生态系统已广泛采用 pyproject.toml 作为标准配置文件，大多数现代打包工具都已支持。

问题背景

当尝试安装从 GitHub 下载的 Python 包时，您可能会发现项目中没有传统的 setup.py 文件，而是包含一个 pyproject.toml 文件。这引发了疑问：这个新文件的作用是什么？它是否取代了 setup.py？如何安装这样的项目？

什么是 pyproject.toml？

pyproject.toml 是由 PEP 518 和 PEP 517 引入的新配置文件，旨在解决 Python 打包生态系统中的几个核心问题：

解决的问题

1. 构建系统依赖问题：传统 setuptools 项目需要预先安装 setuptools 才能构建
2. 工具互操作性：不同打包工具（如 Poetry、Flit）需要生成兼容的 setup.py 文件
3. 工具迁移成本：更换打包工具需要改变整个工作流程

核心作用

pyproject.toml 定义了构建过程的三个关键步骤：

1. 项目源代码检出
2. 构建系统安装
3. 构建系统执行

PEP 518 负责第 2 步（构建系统依赖），PEP 517 负责第 3 步（构建执行）。

核心功能与元数据规范

构建系统配置

pyproject.toml 最基本的用途是指定构建后端和依赖：

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

包元数据 (PEP 621)

PEP 621 定义了在 pyproject.toml 中声明包元数据的标准方式：

[project]
name = "my-package"
version = "0.1.0"
description = "我的Python包"
authors = [
    {name = "张三", email = "zhangsan@example.com"}
]
dependencies = [
    "requests>=2.25.0",
    "numpy>=1.20.0"
]

[project.optional-dependencies]
dev = ["pytest>=6.0", "black"]
gui = ["pyqt5"]

工具支持情况

PEP 621 元数据支持

打包工具	支持版本	备注
setuptools	61.0.0+	传统主流工具
poetry-core	2.0.0+	Poetry 的后端
flit_core	3.2+	Flit 的后端
hatchling	0.3+	Hatch 的后端
pdm-backend	0.3.0+	PDM 的后端

现代工具推荐

对于新项目，推荐使用 Poetry、PDM 或 Hatch 等现代工具，它们提供更完整的依赖管理和打包体验。

可编辑安装

现代方式 (PEP 660)

对于支持 PEP 660 的打包工具，可以直接使用：

pip install -e .

要求：

• pip 版本 ≥ 21.3
• 构建后端支持 PEP 660

各工具的可编辑安装支持

打包工具	支持版本
setuptools	64.0.0+
poetry-core	1.0.8+
flit_core	3.4+
hatchling	0.3+
pdm-backend	0.8.0+

传统方式

对于不支持 PEP 660 的情况，可以创建简化的 setup.py 文件：

#!/usr/bin/env python
import setuptools

if __name__ == "__main__":
    setuptools.setup()

其他工具的配置

pyproject.toml 也被其他工具用于存储配置：

测试配置 (pytest)

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "--verbose"
pythonpath = ["src"]

代码格式配置 (black)

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

类型检查配置 (mypy)

[tool.mypy]
python_version = "3.10"
warn_return_any = true
warn_unused_configs = true

最佳实践

项目结构建议

my-project/
├── src/
│   └── my_package/
│       ├── __init__.py
│       └── module.py
├── tests/
├── pyproject.toml
└── README.md

迁移指南

1. 评估现有项目：检查依赖和构建流程
2. 选择合适工具：根据项目需求选择打包工具
3. 逐步迁移：可以先保留 setup.py 作为过渡
4. 更新CI/CD：确保构建管道支持新的配置格式

兼容性考虑

某些旧工具可能还不完全支持 pyproject.toml，在迁移前请确认所有开发工具链的兼容性。

总结

pyproject.toml 已成为 Python 打包生态系统的现代标准，它提供了：

• 统一的配置文件格式：取代分散的 setup.py、setup.cfg、requirements.txt 等
• 更好的工具互操作性：不同的打包工具可以使用相同的配置文件
• 更可靠的构建过程：明确定义构建依赖和过程
• 扩展性：支持各种工具的配置存储

对于新项目，强烈建议直接使用 pyproject.toml 作为主要的配置文件。对于现有项目，可以根据实际情况逐步迁移到这个新标准。