tomllib --- 解析 TOML 文件

源代码： Lib/tomllib

---

This module provides an interface for parsing TOML 1.1.0 (Tom's Obvious Minimal Language, https://toml.io). This module does not support writing TOML.

Added in version 3.11: The module was added with support for TOML 1.0.0.

在 3.15 版本发生变更: Added TOML 1.1.0 support. See the What's New for details.

警告

在解析不受信任来源的数据时要小心谨慎。 恶意的 TOML 字符串可能导致解码器消耗大量 CPU 和内存资源。 建议对要解析的数据大小进行限制。

参见

Tomli-W 包 是一个 TOML 写入器，它可以与此模块一起使用，提供了与标准库用户熟悉的 marshal 和 pickle 模块类似的写入 API。

参见

TOML Kit 包 是一个兼具读取和写入功能的保留样式的 TOML 库。 它是用于编辑现有 TOML 文件的本模块的推荐替代品。

这个模块定义了以下函数：

tomllib.load(fp, /, *, parse_float=float)

读取一个 TOML 文件。第一个参数应该是一个可读的二进制文件对象。返回 dict。使用 转换表 将 TOML 类型转换为 Python。

对每个要解析的 TOML 浮点数字符串调用 parse_float。 默认情况下，这相当于 float(num_str)。这可以用于为 TOML 浮点数使用另一种数据类型或解析器 (例如 decimal.Decimal)。 可调用对象不能返回 dict 或 list，否则将引发 ValueError。

对无效的 TOML 文档将引发 TOMLDecodeError。

tomllib.loads(s, /, *, parse_float=float)

从 str 对象中加载 TOML。返回 dict。使用 转换表 将 TOML 类型转换为 Python类型。参数 parse_float 与 load() 中的意义相同。

对无效的 TOML 文档将引发 TOMLDecodeError。

有以下几种异常：

exception tomllib.TOMLDecodeError(msg, doc, pos)

拥有以下附加属性的 ValueError 的子类：

msg

未格式化的错误消息。

doc

正在解析的 TOML 文档。

pos

doc 解析失败的索引位置。

lineno

The line corresponding to pos.

colno

The column corresponding to pos.

在 3.14 版本发生变更: 增加了 msg, doc 和 pos 形参。 增加了 msg, doc, pos, lineno 和 colno 属性。

自 3.14 版本弃用: 传入自由形式的位置形参的做法已被弃用。

例子

解析 TOML 文件:

import tomllib

with open("pyproject.toml", "rb") as f:
    data = tomllib.load(f)

解析 TOML 字符串:

import tomllib

toml_str = """
python-version = "3.11.0"
python-implementation = "CPython"
"""

data = tomllib.loads(toml_str)

转换表

TOML	Python
TOML 文档	dict
string	str
integer	int
float	float（可用 parse_float 配置）
boolean	bool
offset date-time	datetime.datetime (tzinfo 属性设置为 datetime.timezone 的实例)
local date-time	datetime.datetime (tzinfo 属性设置为 None)
local date	datetime.date
local time	datetime.time
array	list
table	dict
内联表	dict
表数组	字典列表

Limits and interoperability considerations

tomllib places some limits on the documents it can handle, and it preserves details that other TOML parsers are allowed to ignore. When writing portable TOML files, only use features that are guaranteed or recommended by the standard.

The implementation details listed here may change in future versions of Python.

Tables/dicts

The TOML spec does not guarantee key/value pairs in TOML documents and tables to be in any specific order.

CPython 实现细节： tomllib loads dictionary entries in the order they appear in the source.

整数

TOML recommends supporting integers in range(−2**63, 2**63).

CPython 实现细节： tomllib uses Python's limit on integer string conversion (4300 digits by default).

Floats

TOML recommends supporting at least IEEE 754 binary64 values, which means that numbers with more than 15 significant decimal digits are likely to be rounded.

CPython 实现细节： tomllib uses Python float by default; on many common platforms this is the recommended binary64. See sys.float_info for details.

Nesting limit

TOML 1.1.0 does not recommend a limit on how deeply arrays and tables may be nested inside one another. (A limit of 100 has been proposed for a future version of TOML.)

CPython 实现细节： In tomllib, the nesting level is mainly limited by Python's recursion limit. Note that code that calls tomllib may contribute to the limit.