文件格式

构建系统依赖项将存储在一个名为 pyproject.toml 的文件中，该文件使用 TOML 格式 [6] 编写。

选择此格式是因为它易于人类使用（不同于 JSON [7]），它足够灵活（不同于 configparser [9]），源自标准（也不同于 configparser [9]），并且它不会过于复杂（不同于 YAML [8]）。TOML 格式已在 Rust 社区中作为其 Cargo 包管理器的一部分使用 [14]，并且在私人电子邮件中表示他们对选择 TOML 感到非常满意。关于为什么不选择各种替代方案的更详细讨论可以在 其他文件格式 部分阅读。然而，作者确实意识到，配置文件的格式选择最终是主观的，必须做出选择，作者在此情况下更喜欢 TOML。

下面我们列出了工具预计会识别/尊重的表格。本 PEP 未指定的表格保留供其他 PEP 未来使用。

构建系统表

[build-system] 表用于存储构建相关数据。最初，该表只有一个有效且强制的键：requires。此键的值必须是一个字符串列表，表示执行构建系统所需的 PEP 508 依赖项（目前这意味着执行 setup.py 文件所需的依赖项）。

对于绝大多数依赖 setuptools 的 Python 项目，pyproject.toml 文件将是

[build-system]
# Minimum requirements for the build system to execute.
requires = ["setuptools"]  # PEP 508 specifications.

由于目前 setuptools 在社区中的广泛使用，当 pyproject.toml 文件不存在时，构建工具预计会使用上述示例配置文件作为其默认语义。

工具不应要求 [build-system] 表的存在。pyproject.toml 文件可用于存储与构建无关的配置详细信息，因此可能合法地缺少 [build-system] 表。如果文件存在但缺少 [build-system] 表，则应使用上述指定的默认值。如果指定了该表但缺少必需的字段，则工具应将其视为错误。

工具表

[tool] 表是任何与你的 Python 项目相关的工具（不只是构建工具）可以供用户指定配置数据的地方，只要它们使用 [tool] 中的子表，例如 flit 工具会将其配置存储在 [tool.flit] 中。

我们需要一种机制来在 tool.* 命名空间内分配名称，以确保不同的项目不会尝试使用相同的子表并发生冲突。我们的规则是，一个项目可以使用子表 tool.$NAME，当且仅当它们拥有 Cheeseshop/PyPI 中 $NAME 的条目。

JSON Schema

为了仅出于说明目的提供 TOML 文件中生成数据的特定类型表示，以下 JSON Schema [15] 将匹配数据格式

{
    "$schema": "https://schema.json.js.cn/schema#",

    "type": "object",
    "additionalProperties": false,

    "properties": {
        "build-system": {
            "type": "object",
            "additionalProperties": false,

            "properties": {
                "requires": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            },
            "required": ["requires"]
        },

        "tool": {
            "type": "object"
        }
    }
}

一个语义版本键

为了配置文件的未来兼容性，最初提出了一个 semantics-version 键。默认值为 1，其想法是，如果对先前定义的键或表发生任何不向后兼容的语义更改，则 semantics-version 将递增到一个新数字。

然而，最终决定这是一个过早的优化。预期对配置文件中预定义的语义进行的更改将相当保守。并且在发生向后不兼容更改的情况下，可以使用不同的名称来表示新语义，以避免破坏旧工具。

一个更深层的命名空间

本 PEP 的早期草案有一个顶层 [package] 表。其想法是为语义版本控制方案施加一些范围（参见 语义版本键，了解该想法为何被拒绝）。随着范围需求的消除，拥有顶层表的意义变得多余。

其他表名

为 [build-system] 表提出的另一个名称是 [build]。这个替代名称更短，但不能充分表达表中存储的信息意图。在 distutils-sig 邮件列表上投票后，当前名称胜出。

其他文件格式

其他几种文件格式曾被提出考虑，但都因各种原因被拒绝。关键要求是该格式必须可由人类编辑，并且具有项目可以轻松引入的实现。这完全排除了某些对人类不友好且从未认真讨论过的格式，如 XML。

{
    "build": {
        "requires": [
            "setuptools",
            "wheel>=0.27"
        ]
    }
}

build:
    requires:
        - setuptools
        - wheel>=0.27

[build]
requires =
    setuptools
    wheel>=0.27

# The build configuration
{"build": {"requires": ["setuptools",
                        "wheel>=0.27", # note the trailing comma
                        # "numpy>=1.10" # a commented out data line
                        ]
# and here is an arbitrary comment.
           }
 }

坚持使用 setup.cfg

setuptools 使用的 setup.cfg 作为通用格式存在两个问题。一是它们是 .ini 文件，如上面 configparser 讨论中所述，存在问题。另一个是该文件的 schema 从未严格定义，因此不确定哪种格式在将来使用是安全的，而不会潜在地混淆 setuptools 安装。

其他文件名

其他几个文件名被考虑并拒绝（尽管这是一个非常容易引发争议的话题，所以决定主要取决于品味）。

pysettings.toml

最合理的替代方案。

pypa.toml

虽然引用 PyPA [11] 有意义，但它是一个有些小众的术语。最好文件名在没有领域特定知识的情况下也能理解。

pybuild.toml

从本 PEP 的限制性角度来看，此文件名有意义，但如果任何非构建元数据最终添加到文件中，则该名称将失去意义。

pip.toml

过于工具化。

meta.toml

过于通用；项目可能想要拥有自己的元数据文件。

setup.toml

虽然沿用了 setup.py 的传统，但它不一定与文件未来可能包含的内容匹配（例如，知道项目的名称是否本质上属于其 setup 的一部分？）。

pymeta.toml

对于编程和/或 Python 的新手来说不明显。

pypackage.toml & pypackaging.toml

“package”的名称混淆（项目与命名空间）。

pydevelop.toml

文件可能包含与开发无关的详细信息。

pysource.toml

与源代码不直接相关。

pytools.toml

误导，因为该文件（目前）旨在用于项目管理。

dstufft.toml

过于针对个人。 ;)