tomllib — 解析TOML文件

在 3.11 版本中新增。

源代码: Lib/tomllib

---

本模块提供了用于解析TOML 1.0.0（Tom's Obvious Minimal Language，https://toml.io）的接口。本模块不支持写入TOML。

参见

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

文档中解析失败的索引。

lineno

与pos对应的行号。

colno

与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
整数	int
浮点数	浮点数（可通过parse_float配置）
boolean	bool
带偏移量的日期时间	datetime.datetime（tzinfo属性设置为datetime.timezone的实例）
本地日期时间	datetime.datetime（tzinfo属性设置为None）
本地日期	datetime.date
本地时间	datetime.time
array	list
表	dict
内联表	dict
表数组	字典列表