文件格式

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

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

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

build-system 表格

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

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

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

由于 setuptools 和 wheel 在社区中使用非常广泛，因此当不存在 pyproject.toml 文件时，构建工具应使用上述示例配置文件作为其默认语义。

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

tool 表格

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

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

JSON 模式

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

{
    "$schema": "https://json-schema.fullstack.org.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讨论中提到的那样存在问题。另一个是该文件架构从未被严格定义，因此不知道在不混淆setuptools安装的情况下将来可以使用哪种格式。

其他文件名

考虑并拒绝了几个其他文件名（尽管这在很大程度上是一个无关紧要的话题，因此决定主要取决于品味）。

pysettings.toml

最合理的替代方案。

pypa.toml

虽然引用PyPA [11]很有意义，但它是一个有点利基的术语。最好使文件名在没有特定领域知识的情况下有意义。

pybuild.toml

从这个PEP的限制性角度来看，这个文件名是有意义的，但如果将来有任何非构建元数据添加到文件中，那么这个名称就变得没有意义了。

pip.toml

过于特定于工具。

meta.toml

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

setup.toml

虽然由于setup.py而保持传统，但它不一定与文件将来可能包含的内容相匹配（例如，了解项目的名称是否本质上是其设置的一部分？）。

pymeta.toml

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

pypackage.toml & pypackaging.toml

“包”是什么（项目与命名空间）的名称混淆。

pydevelop.toml

该文件可能包含并非特定于开发的详细信息。

pysource.toml

与源代码没有直接关系。

pytools.toml

具有误导性，因为该文件（目前）针对项目管理。

dstufft.toml

过于特定于个人。;)