Python 怎样读取 TOML 配置并处理二进制文件

读取 TOML 配置时，最容易混淆的是 tomllib.load() 和 tomllib.loads() 的输入类型：前者接收可读的二进制文件对象，后者接收已经存在于内存中的字符串。文件场景直接用 open(path, "rb") 交给 load()；如果手里只有字节数据，就先按 TOML 的文本编码解码成 str，再交给 loads()。

官方地址：https://docs.python.org/3.14/library/tomllib.html

一句话记忆：带 s 的 loads() 读字符串，不带 s 的 load() 读二进制文件对象。不要把 bytes 直接传给 loads()，也不要用文本模式打开文件后再传给 load()。

先把两种输入边界对齐

tomllib 是 Python 3.11 加入标准库的 TOML 解析模块，负责读取 TOML 1.0 文档。它没有写回 TOML 的接口，本文只讨论读取。两个函数最终都会返回一个字典，但入口处的输入对象不同，这个差异决定了文件打开方式和内存转换方式。

函数名里的 s 可以理解为 string。它不是“更快的 load”，而是把输入边界从文件对象换成了字符串。两者解析出的表、数组、日期和数字遵循同一套 TOML 到 Python 的转换规则；区别主要发生在解析之前。

从 TOML 文件读取时使用 load

文件读取的最小写法是用二进制模式打开文件，并把文件对象放在 with 语句中。这样文件句柄的生命周期清晰，解析完成后会自动关闭；不需要先手动读成字符串，也不需要自己猜测文件编码。

from pathlib import Path
import tomllib


def read_config(path: str | Path) -> dict:
    # tomllib.load 要求传入可读的二进制文件对象，因此使用 rb。
    with open(path, "rb") as file_obj:
        # with 会在解析完成后关闭文件，避免配置读取留下句柄。
        return tomllib.load(file_obj)


config = read_config("settings.toml")
# 解析结果是普通字典，后续可以按配置表结构取值。
print(config.get("server", {}).get("port"))

这里的 "rb" 不是可有可无的写法。官方接口把 load() 的第一个参数定义为可读的二进制文件对象；如果改成 "r"，传给解析器的就是文本文件对象，容易在输入阶段触发类型错误。文件路径来自 Path 还是普通字符串并不重要，关键是打开模式和文件对象本身。

只有字节数据时，先解码再使用 loads

有时配置内容不是一个文件，而是从对象存储、消息体或其他二进制接口得到的 bytes。这时不能把字节数组直接交给 tomllib.loads()，因为 loads() 的输入契约是字符串。应先确认这段字节确实是 UTF-8 编码的 TOML 文本，再调用 decode("utf-8")。

from pathlib import Path
import tomllib


def read_toml_bytes(raw: bytes) -> dict:
    # raw 只能在确认内容是 UTF-8 编码的 TOML 文本时这样处理。
    text = raw.decode("utf-8")
    try:
        # loads 接收 str，不接收 bytes；解析后仍返回字典。
        return tomllib.loads(text)
    except tomllib.TOMLDecodeError as exc:
        # 配置内容格式错误时保留原始异常，便于记录行列信息。
        raise ValueError("TOML 配置格式不正确") from exc


config = read_toml_bytes(b"[server]\nport = 8080\n")
print(config["server"]["port"])

如果来源是路径，也可以用 Path.read_bytes() 取得同样的 bytes 输入：

from pathlib import Path

# Path.read_bytes 返回文件字节，仍需先解码再交给 loads。
raw = Path("settings.toml").read_bytes()
config = read_toml_bytes(raw)

这段代码处理的是“二进制承载的 TOML 文本”，不是任意二进制文件。图片、压缩包或自定义协议数据没有 TOML 文档结构，不能因为它们也是 bytes 就交给 tomllib。如果字节不是 UTF-8，decode() 会先抛出 UnicodeDecodeError；如果解码成功但 TOML 语法不完整，则由 TOMLDecodeError 报告解析位置。

文本已经在内存中时直接用 loads

从环境变量、数据库字段或 HTTP 正文拿到的内容通常已经是字符串，这种情况下不需要为了调用 load() 再创建临时文件。直接传入 str 即可；如果数据来源可能为空或未设置，先在业务层处理缺省值，避免把空输入和格式错误混在一起。

import os
import tomllib


def read_inline_config() -> dict:
    # 环境变量已经是字符串，适合使用 loads，而不是伪造文件对象。
    text = os.environ.get("APP_TOML", "")
    if not text.strip():
        # 空配置由业务层决定是否允许，这里明确返回空字典。
        return {}
    try:
        return tomllib.loads(text)
    except tomllib.TOMLDecodeError as exc:
        # 只转换业务提示，不吞掉异常的上下文和根因。
        raise ValueError("APP_TOML 不是有效的 TOML") from exc

如果字符串来自不可信来源，仍然要限制输入大小并处理异常。官方文档提醒，恶意 TOML 字符串可能让解码器消耗较多 CPU 和内存；loads() 只是改变了输入形式，并不会自动替你完成来源校验或容量限制。

用一个判断表避免反复试错

可以先问自己“当前手里是什么对象”，再选择函数，而不是先写函数后根据异常反复修改。下面这张表把文件、字节和字符串三种常见入口分开：

如果只是想“从文件读取”，优先保留 with open(..., "rb") 这条路径；如果已经有字符串，就不要为了形式统一而落盘。两种函数都返回字典，但输入边界不同，资源管理和错误处理也应放在相应的边界附近。

几个容易混淆的细节

• load 和 loads 的区别是输入对象，不是返回值类型；两者正常解析后都返回 dict。
• load 用二进制文件对象，常见写法是 open(path, "rb")，不要换成文本模式。
• loads 用 str；如果输入是 bytes，先确认编码并显式解码。
• tomllib 只负责读取，不负责把修改后的字典写回 TOML；需要写入时应选择专门的 TOML 写入库。
• 格式错误使用 TOMLDecodeError 处理，编码错误则应单独处理 UnicodeDecodeError。

结语

选择 tomllib.load() 还是 tomllib.loads()，先看输入边界即可：文件对象走 load，字符串走 loads，字节承载的 TOML 先解码。把打开模式、解码动作和异常出口放在数据进入解析器之前，配置读取代码就不会再靠试错区分二进制和文本。

相关问题

tomllib.load 可以接收文本模式文件吗？

不建议。官方接口要求可读的二进制文件对象，文件读取时使用 open(path, "rb") 更符合契约。

tomllib.loads 可以直接接收 bytes 吗？

不能按字符串接口使用。先用正确编码把 bytes 解码为 str，然后再传给 loads()。

读取普通二进制文件也能用 tomllib 吗？

不能。只有内容本身是合法 TOML 文档时，二进制文件对象才适合交给 load()；图片、压缩包等格式应使用对应解析器。