pyproject.toml 现在该怎么理解

pyproject.toml 是 Python 项目的现代配置文件，本文帮你理解它的作用和使用方法。

1. 什么是 pyproject.toml

pyproject.toml 是 PEP 621 规定的项目配置文件，用于定义项目的元数据、构建系统和依赖。简单来说，它就是现代 Python 项目的「身份证」和「 строительства蓝图」。

2. 基本结构

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

[project]
name = "mypackage"
version = "1.0.0"
description = "这是一个示例包"
authors = [
    {name = "张三", email = "zhangsan@example.com"}
]
readme = "README.md"
license = {text = "MIT"}
requires-python = ">=3.8"
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
]
dependencies = [
    "requests>=2.28.0",
    "flask>=2.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=22.0.0",
]
test = [
    "pytest>=7.0.0",
    "pytest-cov>=4.0.0",
]

[project.scripts]
myapp = "mypackage.cli:main"

[tool.setuptools]
packages = ["mypackage"]

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

3. 各部分详解

[build-system] 构建系统

这一部分定义了项目如何构建。requires 指定构建所需的工具版本，build-backend 指定使用哪个构建后端。

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

常用的构建后端有：

  • setuptools：最常用的构建后端
  • poetry：Poetry 专用
  • hatchling：Hatch 专用
  • meson-python：用于 C 扩展模块
  • flit：轻量级构建后端

[project] 项目元数据

这部分定义项目的基本信息。name 是包名，version 是版本号，description 是描述，authors 是作者信息。

[project]
name = "mypackage"
version = "1.0.0"
description = "这是一个示例包"
authors = [
    {name = "张三", email = "zhangsan@example.com"}
]
readme = "README.md"
license = {text = "MIT"}
requires-python = ">=3.8"

常见的可选字段：

  • homepage：项目主页
  • repository：代码仓库
  • documentation：文档链接
  • keywords：关键词
  • classifers：分类标签

dependencies 依赖管理

dependencies 定义运行时依赖，optional-dependencies 定义可选依赖。

dependencies = [
    "requests>=2.28.0",
    "flask>=2.0.0",
    "numpy>=1.23.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=22.0.0",
]
test = [
    "pytest>=7.0.0",
    "pytest-cov>=4.0.0",
]

安装可选依赖：

pip install mypackage[dev]
pip install mypackage[test]

4. 工具配置

pyproject.toml 还可以配置各种工具的行为。

Black 代码格式化

[tool.black]
line-length = 88
target-version = ['py38', 'py39', 'py310']
include = '\.pyi?$'
exclude = '''
/(
    \.git
  | \.venv
  | build
  | dist
)/
'''

pytest 测试

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_classes = ["Test*"]
python_functions = ["test_*"]
addopts = "-v --cov=mypackage --cov-report=html"

isort 导入排序

[tool.isort]
profile = "black"
line_length = 88
multi_line_output = 3

mypy 类型检查

[tool.mypy]
python_version = "3.8"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = false

5. 实际示例

简单库

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "mylib"
version = "0.1.0"
description = "我的 Python 库"
readme = "README.md"
requires-python = ">=3.8"
dependencies = []

[tool.setuptools]
py-modules = ["mylib"]

带子包的库

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "mypackage"
version = "1.0.0"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.28.0",
]

[tool.setuptools.packages]
find = {"where": ["src"]}

目录结构：

mypackage/
├── pyproject.toml
├── src/
│   └── mypackage/
│       ├── __init__.py
│       └── module.py

命令行应用

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "mycli"
version = "1.0.0"
description = "命令行工具"
requires-python = ">=3.8"
dependencies = [
    "click>=8.0.0",
]

[project.scripts]
mycli = "mycli.cli:main"

6. 对比旧方式

setup.py（旧方式）

from setuptools import setup, find_packages

setup(
    name="mypackage",
    version="1.0.0",
    packages=find_packages(),
    install_requires=[
        "requests>=2.28.0",
    ],
)

pyproject.toml（新方式）

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "mypackage"
version = "1.0.0"
dependencies = [
    "requests>=2.28.0",
]

新方式的优势：更声明式、更易读、可被各种工具解析。

7. 常见问题

为什么要有 pyproject.toml

在 PEP 621 之前，构建系统配置分散在 setup.py、setup.cfg 等多个文件中。pyproject.toml 统一了这些配置，让项目管理更规范。

必须使用 pyproject.toml 吗

对于需要分发的包，推荐使用。如果是内部脚本或简单项目，setup.py 仍然可用，但新项目强烈建议使用 pyproject.toml。

如何生成

可以使用工具自动生成：

# 使用 hatch
hatch new myproject

# 使用 poetry
poetry new myproject

# 手动创建

快速对照表

字段 作用
name 包名
version 版本号
description 描述
dependencies 运行依赖
optional-dependencies 可选依赖
requires-python Python 版本要求
[project.scripts] 入口点

理解 pyproject.toml 是现代 Python 开发的必备技能，它让项目配置更加规范和统一。