摘要

本 PEP 提议将 tomllib 模块添加到标准库，用于解析 TOML (Tom 的明显极简语言，https://toml.io)。

动机

TOML 是 Python 打包的首选格式，如 PEP 517、PEP 518 和 PEP 621 所示。这为 Python 构建工具带来了引导问题，迫使它们捆绑 TOML 解析包或采用其他不必要的变通方法，并给重新打包者和其他下游消费者带来了严重问题。在标准库中包含 TOML 支持将完美解决所有这些问题。

此外，许多 Python 工具现在可以通过 TOML 进行配置，例如 black、mypy、pytest、tox、pylint 和 isort。许多不支持的工具，例如 flake8，将缺乏标准库支持作为 主要原因。鉴于 TOML 在 Python 生态系统中已经占据特殊地位，将其作为内置电池是合理的。

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

基本原理

本 PEP 提议将标准库中对 TOML 读取的支持基于第三方库 tomli (github.com/hukkin/tomli)。

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

tomli 得到积极维护并经过充分测试。它大约有 800 行代码，100% 测试覆盖率，并通过了 提议的官方 TOML 合规性测试套件 中的所有测试，以及 更完善的 BurntSushi/toml-test 套件。

规范

一个新的模块 tomllib 将被添加到 Python 标准库，暴露以下公共函数

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 参数必须具有与 io.RawIOBase.read() 具有相同 API 的 read() 方法。

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 模块
• [打包] 采用/推荐 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 许可证下，以更宽松者为准。