一文读懂 Python 的 tomllib 模块：TOML 文件解析全攻略

tekin

于 2025-03-05 12:30:00 发布

阅读量2.3k

点赞数 47

分类专栏： Python网络编程 Python 编程秘籍库文章标签： python TOML 文件解析

本文链接：https://blog.csdn.net/tekin_cn/article/details/145965872

版权

Python 编程秘籍库同时被 2 个专栏收录

317 篇文章

订阅专栏

Python网络编程

60 篇文章

订阅专栏

一文读懂 Python 的 tomllib 模块：TOML 文件解析全攻略

文章简介

在 Python 的世界里，处理配置文件和数据序列化是开发过程中常见的任务。tomllib模块自 Python 3.11 版本引入，为解析 TOML 文件提供了便捷的途径。TOML（Tom’s Obvious Minimal Language）作为一种旨在提供一种易于阅读和编写的配置文件格式，正受到越来越多开发者的青睐。本文将深入探讨tomllib模块的使用方法、相关异常处理、数据类型转换以及与其他类似模块的对比，帮助读者全面掌握 TOML 文件在 Python 中的解析技巧。

文章目录

一文读懂 Python 的 tomllib 模块：TOML 文件解析全攻略

一、`tomllib`模块基础认知

tomllib模块主要用于解析符合 TOML 1.0.0 规范的文件和字符串。TOML 格式具有清晰易读的结构，它的设计目标是成为一种既容易被人类阅读和编写，又方便机器解析的配置文件格式。tomllib模块仅专注于解析功能，若需要写入 TOML 文件，可以搭配 Tomli-W 包或使用 TOML Kit 包（该包兼具读取和写入功能，且保留样式，是编辑现有 TOML 文件的推荐替代品）。

二、核心函数解析

（一）`tomllib.load(fp, /, *, parse_float=float)`

该函数用于读取 TOML 文件。其中，fp必须是一个可读的二进制文件对象，这意味着在打开文件时需要使用"rb"模式。函数执行后会返回一个dict，TOML 文件中的数据会按照特定的转换规则被转换为 Python 中的对应数据类型。

例如，有一个名为config.toml的文件，内容如下：

title = "示例配置"
version = 1.0
[author]
name = "张三"
email = "zhangsan@example.com"

在 Python 中解析该文件的代码如下：

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

运行上述代码，输出结果为：

{
    "title": "示例配置",
    "version": 1.0,
    "author": {
        "name": "张三",
        "email": "zhangsan@example.com"
    }
}

parse_float参数是一个可选参数，默认值为float。它用于指定如何解析 TOML 中的浮点数字符串。如果有特殊需求，比如想要将 TOML 中的浮点数解析为decimal.Decimal类型，可以这样修改代码：

import tomllib
from decimal import Decimal

with open("config.toml", "rb") as f:
    data = tomllib.load(f, parse_float=Decimal)
print(data)

此时，TOML 文件中的浮点数在解析后将变为decimal.Decimal类型。需要注意的是，parse_float所指定的可调用对象不能返回dict或list，否则会引发ValueError异常。

（二）`tomllib.loads(s, /, *, parse_float=float)`

这个函数的功能是从字符串对象中加载 TOML 数据，同样返回一个dict。s是包含 TOML 格式数据的字符串。parse_float参数的作用与load函数中的相同。

例如：

import tomllib
toml_str = """
title = "从字符串加载"
count = 5
is_active = true
"""
data = tomllib.loads(toml_str)
print(data)

输出结果为：

{
    "title": "从字符串加载",
    "count": 5,
    "is_active": True
}

三、异常处理

在解析 TOML 文件或字符串时，如果遇到无效的 TOML 文档，tomllib会抛出tomllib.TOMLDecodeError异常，它是ValueError的子类。例如，当 TOML 字符串格式错误时：

import tomllib
toml_str = """
title = "错误示例
count = 5
"""
try:
    data = tomllib.loads(toml_str)
except tomllib.TOMLDecodeError as e:
    print(f"解析错误: {e}")

上述代码中，TOML 字符串缺少一个引号，导致格式错误。运行代码后会捕获到TOMLDecodeError异常，并输出错误信息。

四、数据类型转换

TOML 数据在解析过程中会按照特定的规则转换为 Python 数据类型，具体转换关系如下表所示：

TOML 类型	Python 类型	示例（TOML -> Python）
TOML 文档	`dict`	`[section]\nkey = "value"` -> `{"section": {"key": "value"}}`
string	`str`	`"Hello"` -> `"Hello"`
integer	`int`	`42` -> `42`
float	`float`（可用`parse_float`配置）	`3.14` -> `3.14`（默认）；若`parse_float=Decimal`，则`3.14` -> `Decimal('3.14')`
boolean	`bool`	`true` -> `True`；`false` -> `False`
offset date-time	`datetime.datetime`（`tzinfo`属性设置为`datetime.timezone`的实例）	`2024-01-01T12:00:00+08:00` -> `datetime.datetime(2024, 1, 1, 12, 0, tzinfo=datetime.timezone(datetime.timedelta(hours=8)))`
local date-time	`datetime.datetime`（`tzinfo`属性设置为`None`）	`2024-01-01T12:00:00` -> `datetime.datetime(2024, 1, 1, 12, 0)`
local date	`datetime.date`	`2024-01-01` -> `datetime.date(2024, 1, 1)`
local time	`datetime.time`	`12:00:00` -> `datetime.time(12, 0)`
array	`list`	`[1, 2, 3]` -> `[1, 2, 3]`
table	`dict`	`[section]\nkey = "value"` -> `{"section": {"key": "value"}}`
内联表	`dict`	`{key = "value"}` -> `{"key": "value"}`
表数组	字典列表	`[[section]]\nkey = "value"` -> `[{"section": {"key": "value"}}]`

总结

tomllib模块为 Python 开发者提供了简洁高效的 TOML 文件解析能力。通过load和loads函数，能够轻松地将 TOML 格式的数据转换为 Python 中的字典等数据结构，并且可以灵活地处理不同数据类型的转换。在实际开发中，尤其是在处理配置文件时，TOML 格式凭借其易读性和tomllib模块的便捷解析功能，能够大大提高开发效率。同时，合理地处理TOMLDecodeError异常，可以增强程序的稳定性和健壮性。