摘要

本 PEP 提出将 tomllib 模块添加到标准库中，用于解析 TOML（Tom’s Obvious Minimal Language，https://toml.cn）。

动机

TOML 是 Python 打包的首选格式，正如 PEP 517、PEP 518 和 PEP 621 所证明的那样。这为 Python 构建工具带来了一个引导问题，迫使它们将 TOML 解析包进行捆绑或采用其他不可取的解决方法，并给重新打包者和其他下游消费者带来严重问题。在标准库中包含 TOML 支持将很好地解决所有这些问题。

此外，许多 Python 工具现在可以通过 TOML 进行配置，例如 black、mypy、pytest、tox、pylint 和 isort。许多没有使用 TOML 配置的工具，例如 flake8，将缺少标准库支持作为 主要原因。鉴于 TOML 在 Python 生态系统中的特殊地位，将其包含为内置库是有意义的。

最后，TOML 作为一种格式越来越受欢迎（原因在 PEP 518 中概述），各种 Python TOML 库在 PyPI 上拥有大约 2000 个反向依赖项（相比之下，requests 拥有大约 28000 个反向依赖项）。因此，即使考虑了 Python 打包和相关工具的需求之外，这也有可能成为一个普遍有用的补充。

理由

本 PEP 建议基于第三方库 tomli（github.com/hukkin/tomli）来构建标准库对读取 TOML 的支持。

许多项目最近已切换到使用 tomli，例如 pip、build、pytest、mypy、black、flit、coverage、setuptools-scm 和 cibuildwheel。

tomli 积极维护且经过良好测试。它大约有 800 行代码，拥有 100% 的测试覆盖率，并且通过了 提议的官方 TOML 兼容性测试套件 中的所有测试，以及 更成熟的 BurntSushi/toml-test 测试套件。

规范

将向 Python 标准库添加一个新模块 tomllib，公开以下公共函数

def load(
    fp: SupportsRead[bytes],
    /,
    *,
    parse_float: Callable[[str], Any] = ...,
 ) -> dict[str, Any]: ...

def loads(
    s: str,
    /,
    *,
    parse_float: Callable[[str], Any] = ...,
) -> dict[str, Any]: ...

tomllib.load 将包含 TOML 文档的二进制类文件对象反序列化为 Python dict。fp 参数必须具有一个 read() 方法，该方法与 io.RawIOBase.read() 的 API 相同。

tomllib.loads 将包含 TOML 文档的 str 实例反序列化为 Python dict。

parse_float 参数是一个可调用对象，它以 TOML 浮点数的原始字符串表示形式作为输入，并返回相应的 Python 对象（类似于 json.load 中的 parse_float）。例如，用户可以传递一个返回 decimal.Decimal 的函数，用于需要精确度的用例。默认情况下，TOML 浮点数将解析为 Python float 类型的实例。

返回的对象仅包含基本 Python 对象（str、int、bool、float、datetime.{datetime,date,time}、list、dict，其键为字符串）以及 parse_float 的结果。

如果 TOML 无效，则会引发 tomllib.TOMLDecodeError。

请注意，本 PEP 并没有提出 tomllib.dump 或 tomllib.dumps 函数；有关详细信息，请参阅 包含用于写入 TOML 的 API。

维护影响

向后兼容性

本提案在标准库中没有任何向后兼容性问题，因为它描述了一个新模块。任何现有的名为 tomllib 的第三方模块都将被破坏，因为 import tomllib 将导入标准库模块。但是，tomllib 未在 PyPI 上注册，因此不太可能存在广泛使用的同名模块。

请注意，我们避免使用更直观的名称 toml，以避免对已固定当前 toml PyPI 包版本的用户的向后兼容性影响。有关详细信息，请参阅 模块的备选名称 部分。

安全影响

实现中的错误可能导致潜在的安全问题。但是，解析器的输出仅限于简单数据类型；无法加载任意类可以避免更“强大”的格式（如 pickle 和 YAML）中常见的安全问题。此外，实现将使用纯 Python，这减少了 C 中常见的安全问题，例如缓冲区溢出。

如何教授

tomllib 的 API 模仿了其他成熟的文件格式库，如 json 和 pickle。文档中将解释缺乏 dump 函数的原因，并提供指向相关第三方库（例如 tomlkit、tomli-w、pytomlpp）的链接。

参考实现

提议的实现可以在 https://github.com/hukkin/tomli 中找到。

被拒绝的建议

之前讨论

• bpo-40059：在标准库中提供 toml 模块
• [Python-Dev] 将 toml 模块添加到标准库中？
• [Python-Ideas] Python 标准库 TOML 模块
• [Packaging] 采用/推荐 toml 解析器？
• hukkin/tomli#141: 请考虑将 tomli 推入标准库

附录 A：建议的 API 与 toml 之间的差异

本附录涵盖了本 PEP 中提出的 API 与第三方包 toml 的 API 之间的差异。这些差异与理解如果我们使用 toml 作为标准库模块的名称，我们可能遇到的代码中断程度，以及更好地理解设计空间相关。请注意，此列表可能并不详尽。

1. 不建议包含写入 API（无 toml.dump[s]）

   本 PEP 目前建议不包含写入 API；也就是说，不会有类似于 toml.dump 或 toml.dumps 的功能，如 包含写入 TOML 的 API 中所述。

   如果我们包含了写入 API，将可以相当容易地将大多数使用 toml 的代码转换为新的标准库模块（承认这与兼容的 API 非常不同，因为它仍然需要代码更改）。

   根据比较 “toml.load” 的出现次数 与 “toml.dump” 的出现次数，相当一部分 toml 用户依赖于此功能。

2. toml.load 的第一个参数不同

   toml.load 具有以下签名

   def load(
       f: Union[SupportsRead[str], str, bytes, list[PathLike | str | bytes]],
       _dict: Type[MutableMapping[str, Any]] = ...,
       decoder: TomlDecoder = ...,
   ) -> MutableMapping[str, Any]: ...
   

   这与本 PEP 中提出的第一个参数 SupportsRead[bytes] 相当不同。

   回顾一下之前在 tomllib.load 的第一个参数所接受的类型 中提到的原因

   • 允许路径（甚至路径列表）作为参数与标准库中其他类似函数不一致。
   • 使用 SupportsRead[bytes] 使我们能够确保 UTF-8 是使用的编码，并避免错误地将单个回车符解析为有效的 TOML。

   根据手动检查 “toml.load” 的出现次数，相当一部分 toml 用户依赖于此功能。

3. 错误

   toml 抛出 TomlDecodeError，而建议使用符合 PEP 8 的 TOMLDecodeError。

   根据 “TomlDecodeError” 的出现次数，相当一部分 toml 用户依赖于此功能。

4. toml.load[s] 接受 _dict 参数

   如 控制 tomllib.load[s] 返回的映射类型 中所述。

   正如那里提到的，几乎所有使用都包含 _dict=OrderedDict，这在 Python 3.7 及更高版本中不再必要。

5. toml.load[s] 支持一个未记录的 decoder 参数

   似乎预期用例是为了实现注释保留。记录的信息不足以保留样式来对 TOML 文档进行循环处理，实现存在已知错误，该功能未记录，我们只在 https://grep.app 上找到一个使用实例。

   公开的 toml.TomlDecoder 接口 远非简单，包含九种方法。

   用户可能最好使用更完整的样式保留解析和写入实现。

6. toml.dump[s] 支持 encoder 参数

   请注意，我们目前建议不包含写入 API；但是，如果要更改，这些差异可能会变得相关。

   encoder 参数支持两种用例

   • 控制自定义类型如何序列化，以及
   • 控制输出的格式。

   第一个是合理的；但是，我们只在 https://grep.app 上找到这两个实例中的一个。这两个实例中有一个使用了这种能力来添加对转储 decimal.Decimal 的支持，而潜在的标准库实现将开箱即用地支持该能力。如果需要其他类型，可以通过类似于 json.dump 中的 default 参数的方式来很好地解决此用例。

   第二个用例是通过允许用户指定 toml.TomlEncoder 的子类并覆盖方法来指定 TOML 写入过程的各个部分来实现的。该 API 包含五种方法，并公开了大量的实现细节。

   在 https://grep.app 上有一些使用 encoder API 的例子；但是，似乎它只占 toml 总使用量的很小一部分。

7. 时区

   toml 使用并公开自定义的 toml.tz.TomlTz 时区对象。建议的实现使用标准库中的 datetime.timezone 对象。

版权

本文档放置在公共领域或根据 CC0-1.0-Universal 许可证发布，以更宽松的许可证为准。