pyproject.toml

pyproject.toml 是 Python 项目的统一配置文件，定义构建系统、项目元数据和工具配置。

背景与演进

阶段	说明
PEP 518 (2017)	定义构建系统要求，引入 [build-system]
PEP 621 (2021)	标准化项目元数据，引入 [project]
现状	替代 setup.py/setup.cfg，成为官方推荐

解决的问题：配置碎片化（setup.py、requirements.txt、各工具独立配置文件）。

基本结构

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"
 
[project]
name = "my-package"
version = "0.1.0"
authors = [{ name = "Author", email = "email@example.com" }]
description = "A short description"
dependencies = ["requests>=2.25.0"]
 
[project.optional-dependencies]
dev = ["pytest>=7.0", "black>=22.0"]
 
[project.scripts]
my-cli = "my_package.cli:main"

构建后端选项

后端	工具
setuptools.build_meta	setuptools（最主流）
poetry.core.masonry.api	Poetry
flit_core.buildapi	Flit
hatchling.build	Hatch

工具配置

[tool.black]
line-length = 88
 
[tool.pytest.ini_options]
testpaths = ["tests"]
 
[tool.mypy]
python_version = "3.10"
warn_return_any = true

依赖管理

# 安装项目依赖
pip install .
 
# 安装开发依赖
pip install .[dev]
 
# 可编辑模式
pip install -e .

完整示例

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"
 
[project]
name = "my-lib"
version = "0.1.0"
description = "A Python library"
dependencies = ["requests>=2.25.0"]
 
[project.optional-dependencies]
dev = ["pytest>=7.0", "black>=22.0", "mypy>=1.0"]
 
[tool.black]
line-length = 88
 
[tool.pytest.ini_options]
testpaths = ["tests"]

注意事项

1. 版本要求：setuptools >= 61.0 支持 PEP 621
2. 避免混用：不要同时使用 pyproject.toml 和 setup.py
3. TOML 语法：注意引号、逗号格式
4. 工具支持：确认工具版本（pytest >= 6.0、black >= 20.0）