现代 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 项目元数据格式࿰进一步标准化c;使项目信息以统一的方式处理不同的构建后端。

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 = "[email protected]"}]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 = 88target-version = ['py37'][tool.isort]profile = "black"[tool.pytest.ini_options]minversion = "6.0"addopts = "-ra -q"

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

支持现代工具。

现代 Python 所有项目管理工具都是正确的。 pyproject.toml。提供了很好的支持：

1. Poetry：完全基于。 pyproject.toml。依赖管理工具。
2. PDM：新一代 Python 包管理器。
3. Hatch：现代化的项目管理工具。
4. Rye：新兴的 Python 项目管理工具。

自定义配置信息。

假如您有自己的配置信息，自己读取 pyproject.toml 也很简单󿼀也很简单�就像读取 json，yaml 相同，以下是示例代码：

import。tomli。  # For Python < 3.11。# For Python 3.11+, you can use: import tomllib。def。read_pyproject_toml。(。file_path。="pyproject.toml")。:。"""    读取并解析 pyproject.toml 文件        Args:        file_path (str): pyproject.toml 文件的路径            Returns:        dict: 解析后的 TOML 内容    """try。:。with。open。(。file_path。,mode。="rb")。as。fp。:。# 使用 rb (二进制读取模式) 避免编码问题。toml_dict。 =tomli。.。load。(。fp。)。return。toml_dict。    except。FileNotFoundError。:。print。(。f"错误: 找不到文件 '{ 。build_system。.。get。(。'requires',[。]。)。}。")。def。main。(。)。:。# 读取并解析 TOML 文件。toml_dict。 =read_pyproject_toml。(。)。if。toml_dict。:。# 打印完整的分析结果。print。(。"完整的 TOML 内容:")。print。(。toml_dict。)。print。(。"\n"+"="*。50。+"\n")。# 打印格式化的项目信息。print_project_info。(。toml_dict。)。if。__name__。 =="__main__":。main。(。)。

需要注意的是，：

• Python < 3.11 需要安装。 tomli。:。 pip install tomli。
• Python 3.11+ 可直接使用内置。 tomllib。

到目前为止，大致可以理解各种工具链是如何配置自己的参数的，当然，如何更好地配置，还是要看官方文档（虽然有些文档真的很烂，如 darglint）。

下一步，我会试着设计一套 all in one 的 lint 方案。