Python tomllib 怎样读取二进制 TOML

Python 3.11 起可以直接使用标准库 tomllib 解析 TOML。先记住一个边界：磁盘上的 TOML 文件用 tomllib.load(fp)，这里的 fp 必须是以二进制模式打开的文件对象；已经拿到文本字符串时才用 tomllib.loads(text)。如果手里只有 bytes，不要直接把它传给 loads，可以包装成二进制文件对象，或先按 UTF-8 解码。

Python tomllib 用 load 读取二进制文件

文件在磁盘上时，推荐让 tomllib 自己从二进制文件对象读取。这样不会先把整个文件手工转成字符串，也能把“文件读取”和“TOML 解析”放在同一个资源管理块里。

from pathlib import Path
import tomllib

config_path = Path("settings.toml")

# TOML 文件用二进制模式打开，交给 load 负责读取和解析
with config_path.open("rb") as fp:
    config = tomllib.load(fp)

# 解析结果是普通的嵌套字典，可以按键读取配置
port = config["server"]["port"]
print(port)

with 结束后文件会自动关闭。不要把这里的 "rb" 改成 "r" 后继续调用 load；load 的契约就是二进制文件对象。图1是这条输入链路的静态说明图。

内存中的 bytes 应先解码或包装成文件对象

网络响应、对象存储或缓存经常给出一段 bytes。这时有两种清晰的写法。若想保留“二进制文件对象”语义，可以使用 io.BytesIO：

from io import BytesIO
import tomllib

raw_toml = b"[server]\nport = 8080\n"

# BytesIO 提供 read 方法，符合 tomllib.load 的文件对象要求
with BytesIO(raw_toml) as fp:
    config = tomllib.load(fp)

print(config["server"]["port"])

如果业务已经明确要处理文本，也可以先解码，再调用 loads：

import tomllib

raw_toml = b"title = 'demo'\n"

# TOML 文本按 UTF-8 解码后，loads 接收 str 而不是 bytes
toml_text = raw_toml.decode("utf-8")
config = tomllib.loads(toml_text)
print(config["title"])

不要写成 tomllib.loads(raw_toml)。loads 的输入边界是字符串；bytes 还没有完成字符编码解释。图2把两条合法路径和这个错误边界放在一起比较。

load、loads 与解析参数怎么选

两个函数都支持关键字参数 parse_float，默认使用 float。如果金额或高精度小数不能接受二进制浮点误差，可以传入 decimal.Decimal，但要先确认配置中的特殊浮点写法是否符合你的业务规则。解析 TOML 语法失败时捕获 tomllib.TOMLDecodeError；文件不存在、权限不足和编码解码失败则属于更早的 I/O 或文本处理错误，不要混成同一种异常。

常见问题

tomllib.load 为什么要求 rb？

因为它接收的是二进制文件对象，并由 TOML 解析器处理文件内容。使用 rb 能避免文本层提前改变输入。

bytes 能不能直接交给 tomllib.loads？

不建议也不符合接口输入边界。要么用 BytesIO(bytes_data) 调用 load，要么先按实际编码解码为 str 再调用 loads。

什么时候选 loads？

当 TOML 文本已经在内存中，并且调用方希望明确控制解码、缓存或字符串来源时选 loads；文件读取场景优先选 load。