pyproject.toml

pyproject.toml 是 Python 项目统一的配置文件 ，用来集中管理构建、依赖、工具配置，让项目更标准化、更可移植。

它在 2016 年被 PEP 518 引入，现在已经成为 所有现代 Python 项目的核心文件 （类似 Node.js 的 package.json）。

---

✅ 一句话概括它的作用

pyproject.toml 用来告诉 Python：你的项目要怎么构建、用什么工具、有哪些依赖。

---

🔍 详细作用拆解

1. 声明构建系统（build backend）

Python 构建 wheel 或安装包时，会先读取 pyproject.toml，找到：

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

这意味着：

• 用什么工具构建？
• 构建时需要哪些依赖？

类似 Node 中的 "scripts" + 构建工具"。

常见的 backend：

工具	描述
setuptools	标准构建工具（旧项目）
poetry	现代项目常用
pdm	轻量、快速
hatch	高级构建工具
flit	超轻量的包管理

---

2. 管理项目依赖（dependencies）

现代工具（如 Poetry、PDM）直接把依赖写在这里：

[tool.poetry.dependencies]
requests = "^2.31.0"
pydantic = "^2.0"

比 requirements.txt 更规范，更可管理（不过两者可以共存）。

---

3. 集中管理所有工具配置

这是它最强大的地方。

几乎 Python 生态的所有工具都支持从 pyproject.toml 读取配置，例如：

工具	配置示例
Black	格式化规则
Ruff / flake8	Lint 配置
mypy	静态类型检查
pytest	测试配置
isort	import 排序
coverage	测试覆盖率

例子：

[tool.black]
line-length = 100

[tool.mypy]
strict = true

[tool.pytest.ini_options]
python_files = ["tests/*.py"]

优点：不用再到处放 setup.cfg、tox.ini、.flake8 等杂乱文件。

---

4. 声明项目元数据（metadata）

构建系统如 setuptools 使用它描述你的包：

[project]
name = "my_app"
version = "0.1.0"
description = "A demo app"
dependencies = ["requests"]

这在发布到 PyPI 时必须提供。

---

5. 定义可执行命令（entrypoints / scripts）

[project.scripts]
my-cli = "my_app.main:run"

安装后可以直接运行：

my-cli

---

📌 为什么会出现？

因为传统 Python 项目到处都有配置文件：

setup.py
setup.cfg
requirements.txt
MANIFEST.in
tox.ini
mypy.ini
pyproject.toml（以前没有）

非常混乱。

所以 PEP 518 / PEP 621 推出了 pyproject.toml：

• 统一格式
• 更可移植
• 构建环境自动隔离
• 生态工具都能共享配置

现在几乎所有 Python 新项目都必须有它。

---

✨ 总结：它主要做 3 件事

功能	目的
构建系统声明	Python 如何构建这个项目
依赖管理	安装项目需要哪些包
工具配置中心	Black/Mypy/Pytest 等统一在此配置

---

.toml 是一种 配置文件格式，名字来自：

TOML = Tom's Obvious, Minimal Language

由 GitHub 联合创始人 Tom Preston-Werner 设计。

它的目标是：

• 易读（比 JSON 更直观）
• 易写（不用大括号、引号、逗号）
• 适合做配置（格式稳定、安全）

这就是为什么 Python 把它选为统一的项目配置文件格式。

---

🔍 .toml 是什么类型？

它是一种 结构化、键值对（key-value）的配置语言，类似：

格式	对比
INI	最像它
JSON	更严格，但阅读性差
YAML	更强大，但更容易写错（缩进地狱）
TOML	介于 JSON 和 INI 之间，简单又安全

---

🧩 TOML 的几个特点

1. 人类可读性强

例如：

name = "Lewis"
age = 28
active = true

比 JSON 没有大括号、没有引号地狱：

{"name": "Lewis", "age": 28, "active": true}

---

2. 支持分组（类似 INI）

[database]
host = "localhost"
port = 5432

---

3. 支持丰富的数据类型

类型	示例
字符串	name = "abc"
整数、浮点	count = 12
布尔	enabled = true
数组	items = [1, 2, 3]
时间日期	time = 2025-05-20T12:00:00Z

---

4. 解析快、安全、无歧义

不像 YAML 那样：

• 缩进错了就寄
• tab 和 space 容易被混
• 一些格式有歧义

TOML 的设计目标就是"没有坑"。

---

🤔 为什么 Python 选 TOML？

因为 Python 社区需要一个统一配置格式：

过去工具各自有自己的配置文件：

setup.py
setup.cfg
requirements.txt
tox.ini
pytest.ini
flake8.cfg
mypy.ini

维护非常乱。

要统一，就需要一种：

• 易读
• 易写
• 无歧义
• 稳定
• 可扩展
• 被其他语言也接受的格式

TOML 完全符合，于是被官方 PEP 518/PEP 621 采用，用于 pyproject.toml。

现在 Rust、Go、Python 都大量使用 TOML。

---

📌 小结

.toml 是：

• 一种配置文件语言
• 简单、稳定、无歧义
• 被 Python 官方选择为未来统一格式
• 用来写 pyproject.toml、poetry.lock 等文件

---