# `tomllib` --- 解析 TOML 文件

Added in version 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)

  Subclass of `ValueError` with the following additional attributes:

  msg

    The unformatted error message.

  doc

    The TOML document being parsed.

  pos

    The index of doc where parsing failed.

  lineno

    The line corresponding to pos.

  colno

    The column corresponding to pos.

  在 3.14 版本发生变更: Added the msg, doc and pos parameters. Added the `msg`, `doc`, `pos`, `lineno` and `colno` attributes.

  自 3.14 版本弃用: Passing free-form positional arguments is deprecated.

## 例子

解析 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
表数组 | 字典列表