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

技术文档

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

文章简介

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

文章目录

一文读懂 Python 的 tomllib 模块：TOML 文件解析全攻略
- 文章简介
- 一、`tomllib`模块基础认知
- 二、核心函数解析
- - （一）`tomllib.load(fp, /, *, parse_float=float)`
  - （二）`tomllib.loads(s, /, *, parse_float=float)`
- 三、异常处理
- 四、数据类型转换
- 总结
- TAG：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 tomllibwith 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 tomllibfrom decimal import Decimalwith 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 tomllibtoml_str = \"\"\"title = \"从字符串加载\"count = 5is_active = true\"\"\"data = tomllib.loads(toml_str)print(data)

输出结果为：

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

三、异常处理

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

import tomllibtoml_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异常，可以增强程序的稳定性和健壮性。

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