# `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
表数组 | 字典列表