Tomli

一个小型的TOML解析器

目录 由mdformat-toc生成

• 简介
• 安装
• 使用
  • 解析TOML字符串
  • 解析TOML文件
  • 处理无效的TOML
  • 从TOML浮点数构建decimal.Decimal
  • 构建tomli/tomllib兼容层
• 常见问题解答
  • 为什么是这个解析器？
  • 支持保留注释的往返解析吗？
  • 有dumps、write或encode函数吗？
  • TOML类型如何映射到Python类型？
• 性能

简介

Tomli 是一个用于解析 TOML 的 Python 库。它与 TOML v1.0.0 完全兼容。

Python 3.11 通过 PEP 680 添加了 Tomli 的一个版本，即 tomllib 模块。Tomli 继续在 PyPI 上为那些标准库模块不可用且尚未达到生命周期的 Python 版本提供回端口。

安装

pip install tomli

使用

解析 TOML 字符串

import tomli

toml_str = """
[[players]]
name = "Lehtinen"
number = 26

[[players]]
name = "Numminen"
number = 27
"""

toml_dict = tomli.loads(toml_str)
assert toml_dict == {
    "players": [{"name": "Lehtinen", "number": 26}, {"name": "Numminen", "number": 27}]
}

解析 TOML 文件

import tomli

with open("path_to_file/conf.toml", "rb") as f:
    toml_dict = tomli.load(f)

必须以二进制模式（使用 "rb" 标志）打开文件。二进制模式将强制以 UTF-8 编码并禁用通用换行符进行解码，这两者都是正确解析 TOML 所必需的。

处理无效的 TOML

import tomli

try:
    toml_dict = tomli.loads("]] this is invalid TOML [[")
except tomli.TOMLDecodeError:
    print("Yep, definitely not valid.")

请注意，错误消息仅视为信息。它们不应被视为在 Tomli 版本之间保持恒定。

从 TOML 浮点数构建 decimal.Decimal

from decimal import Decimal
import tomli

toml_dict = tomli.loads("precision-matters = 0.982492", parse_float=Decimal)
assert isinstance(toml_dict["precision-matters"], Decimal)
assert toml_dict["precision-matters"] == Decimal("0.982492")

请注意，可以将 decimal.Decimal 替换为另一个可调用的函数，该函数将 TOML 浮点字符串转换为 Python 类型。然而，对于不能容忍浮点数不精确的用例，decimal.Decimal 是一个实际的选择。

非法类型是 dict 和 list，以及它们的子类型。如果 parse_float 生成非法类型，将引发 ValueError。

构建 tomli/tomllib 兼容层

Python 3.11+ 版本附带 Tomli 版本：标准库模块 tomllib。要构建在可用的标准库中使用的代码，但仍然与 Python 3.6+ 无缝工作，请执行以下操作。

不要使用硬 Tomli 依赖关系，而是使用以下 依赖指定符 仅在标准库模块不可用时要求 Tomli

tomli >= 1.1.0 ; python_version < "3.11"

然后，在您的代码中，使用以下回退机制导入 TOML 解析器

import sys

if sys.version_info >= (3, 11):
    import tomllib
else:
    import tomli as tomllib

tomllib.loads("['This parses fine with Python 3.6+']")

常见问题解答

为什么是这个解析器?

• it's lil'
• 纯 Python，无任何依赖
• 最快的纯 Python 解析器 *：比 tomlkit 快 16 倍，比 toml 快 2.3 倍
• 仅输出 基本数据类型
• 100% 规范兼容：通过 BurntSushi/toml-test 测试套件中的所有测试
• 彻底测试：100% 分支覆盖率

是否支持保留注释的往返解析?

不支持。

tomli.loads 函数返回一个普通的 dict，其中填充了内置类型和标准库中的类型。保留注释需要返回一个自定义类型，因此不会支持，至少不会由 tomli.loads 和 tomli.load 函数支持。

如果需要保留风格，请查看 TOML Kit。

是否有 dumps、write 或 encode 函数?

Tomli-W 是 Tomli 的写入对应版本，提供 dump 和 dumps 函数。

核心库不包括写入功能，因为大多数 TOML 用例是只读的，而 Tomli 旨在最小化。

如何将 TOML 类型映射到 Python 类型?

性能

该存储库中的 benchmark/ 文件夹包含各种 Python TOML 解析器的性能基准。可以使用 tox -e benchmark-pypi 运行基准测试。在我的个人电脑上运行基准测试的输出如下

foo@bar:~/dev/tomli$ tox -e benchmark-pypi
benchmark-pypi installed: attrs==21.4.0,click==8.0.3,pytomlpp==1.0.10,qtoml==0.3.1,rtoml==0.7.1,toml==0.10.2,tomli==2.0.1,tomlkit==0.9.2
benchmark-pypi run-test-pre: PYTHONHASHSEED='3088452573'
benchmark-pypi run-test: commands[0] | python -c 'import datetime; print(datetime.date.today())'
2022-02-09
benchmark-pypi run-test: commands[1] | python --version
Python 3.8.10
benchmark-pypi run-test: commands[2] | python benchmark/run.py
Parsing data.toml 5000 times:
------------------------------------------------------
    parser |  exec time | performance (more is better)
-----------+------------+-----------------------------
     rtoml |    0.891 s | baseline (100%)
  pytomlpp |    0.969 s | 91.90%
     tomli |        4 s | 22.25%
      toml |     9.01 s | 9.88%
     qtoml |     11.1 s | 8.05%
   tomlkit |       63 s | 1.41%

解析器按照从快到慢的顺序排序，使用最快的解析器作为基准。Tomli 在所有纯 Python TOML 解析器中表现最佳，仅输给了 pytomlpp（C++ 包装）和 rtoml（Rust 包装）。