苦练Python第63天：零基础玩转TOML配置读写，tomllib模块实战

前言

大家好，我是倔强青铜三。欢迎关注我，微信公众号：倔强青铜三。点赞、收藏、关注，一键三连！

欢迎来到苦练Python第63天！

今天继续啃下另一只“配置文件界的瑞士军刀”——TOML。

TOML是Tom’s Obvious, Minimal Language的简写。

Python 3.11 起，标准库自带 tomllib，开箱即用，零依赖！

一、TOML 是什么？能做什么？

和 JSON、YAML 并列的三大配置文件格式之一。
像 .ini 的升级豪华版：支持嵌套表、数组、日期时间、注释。
典型场景：
1. pyproject.toml（PEP 518 指定 Python 项目元数据）
2. Rust/Cargo、Node/npm、Go Modules 等语言生态的默认配置
3. 机器学习超参数、CI/CD 流水线、容器编排文件

二、读 TOML —— 把文件读成 dict

2.1 读取文件：tomllib.load

1# demo_read_file.py
2import tomllib
3from pathlib import Path
4
5# 1. 先造一份 TOML 文件
6toml_text = '''
7title = "我的项目"
8
9[owner]
10name = "倔强青铜三"
11dob = 2000-06-01T12:34:56+08:00
12
13[database]
14ports = [ 8001, 8001, 8002 ]
15enabled = true
16'''
17Path("config.toml").write_text(toml_text, encoding="utf-8")
18
19# 2. 读取
20with open("config.toml", "rb") as f:
21    conf = tomllib.load(f)
22
23print("项目名:", conf["title"])
24print("作者生日:", conf["owner"]["dob"])
25print("数据库端口列表:", conf["database"]["ports"])
26

运行结果：

1项目名: 我的项目
2作者生日: 2000-06-01 12:34:56+08:00
3数据库端口列表: [8001, 8001, 8002]
4

注意：必须以 二进制模式 "rb" 打开文件，防止编码踩坑。

2.2 读取字符串：tomllib.loads

1# demo_read_str.py
2import tomllib
3
4toml_str = '''
5[[users]]
6id = 1
7name = "张三"
8
9[[users]]
10id = 2
11name = "李四"
12'''
13
14data = tomllib.loads(toml_str)
15for user in data["users"]:
16    print(f"#{user['id']} 姓名: {user['name']}")
17

输出：

1#1 姓名: 张三
2#2 姓名: 李四
3

三、类型对照表（牢记！）

TOML 类型	Python 读出来
string	str
integer	int
float	float（可自定义）
boolean	bool
offset date-time	datetime.datetime
local date-time	datetime.datetime
local date	datetime.date
local time	datetime.time
array	list
table	dict
表数组	list[dict]

四、自定义浮点解析：Decimal 防精度丢失

默认 tomllib 把 TOML 的 3.14 解析成 Python float。想要 高精度小数？传个 parse_float。

1# demo_decimal.py
2import tomllib
3from decimal import Decimal
4
5toml_str = "price = 19.99"
6data = tomllib.loads(toml_str, parse_float=Decimal)
7print(type(data["price"]), data["price"])
8

输出：

1<class 'decimal.Decimal'> 19.99
2

规则：parse_float 不能返回 dict/list，否则抛 ValueError。

五、异常处理：TOMLDecodeError

TOML 写错怎么办？tomllib.TOMLDecodeError 会告诉你行号。

1# demo_error.py
2import tomllib
3
4bad_toml = "answer = 42\nthis line is broken >>>"
5try:
6    tomllib.loads(bad_toml)
7except tomllib.TOMLDecodeError as e:
8    print("解析失败:", e)
9

六、完整实战：把 TOML 读成 dict，再写回“极简 JSON”

任务：把 pyproject.toml 里的项目名、版本、依赖读出来，生成 summary.json（仅标准库）。

1# demo_summary.py
2import tomllib
3import json
4from pathlib import Path
5
6# 1. 造一份 pyproject.toml
7toml_content = '''
8[project]
9name = "toml_demo"
10version = "0.1.0"
11description = "tomllib 实战示例"
12dependencies = ["requests>=2.31", "rich>=13.0"]
13'''
14Path("pyproject.toml").write_text(toml_content, encoding="utf-8")
15
16# 2. 读 TOML
17with open("pyproject.toml", "rb") as f:
18    data = tomllib.load(f)
19
20proj = data["project"]
21summary = {
22    "name": proj["name"],
23    "version": proj["version"],
24    "deps": proj["dependencies"]
25}
26
27# 3. 写 JSON
28Path("summary.json").write_text(json.dumps(summary, ensure_ascii=False, indent=2), encoding="utf-8")
29print("已生成 summary.json ↓")
30print(json.dumps(summary, indent=2))
31

运行后生成 summary.json：

1{
2  "name": "toml_demo",
3  "version": "0.1.0",
4  "deps": [
5    "requests>=2.31",
6    "rich>=13.0"
7  ]
8}
9

七、小结

tomllib.load 读文件，tomllib.loads 读字符串，返回值都是 dict。
支持全部 TOML 1.0.0 特性：表、表数组、日期时间、注释。
只读不写，写回文件请用 json、configparser 或第三方 TOML Kit。
注意 二进制打开 和 TOMLDecodeError 异常捕获。

最后感谢阅读！欢迎关注我，微信公众号：倔强青铜三。
欢迎点赞、收藏、关注，一键三连！！

《苦练Python第63天：零基础玩转TOML配置读写，tomllib模块实战》是转载文章，点击查看原文。