Python tomllib.loads 怎样解析字符串配置

如果 TOML 配置已经在环境变量、数据库字段或接口请求体里，而不是一个本地文件，直接调用 tomllib.loads(text) 就可以把字符串解析成 Python 字典。它要求输入是 str，返回普通 dict；格式不合法时抛出 tomllib.TOMLDecodeError。

官方文档：https://docs.python.org/3/library/tomllib.html

字符串输入怎样变成配置字典

tomllib 从 Python 3.11 开始进入标准库。最小用法只需要准备一段 TOML 字符串，然后把结果当作嵌套字典读取：

import tomllib

toml_text = """
app_name = "billing"
debug = false

[server]
host = "127.0.0.1"
port = 8080
"""

# loads 接收字符串，并把 TOML 文档转换为 Python 字典。
config = tomllib.loads(toml_text)

# 表会变成嵌套字典，整数仍然保持为 int。
print(config["app_name"])
print(config["server"]["port"])

这里的 server 表对应 config["server"]，port 则是嵌套字典里的整数。和 tomllib.load() 不同，loads() 不需要打开二进制文件，适合处理已经读入内存的配置文本。

返回值会保留哪些 TOML 类型

解析结果不是一段未加工的文本，而是按照 TOML 类型转换成 Python 对象。常用对应关系如下：

因此不要把所有值都当成字符串再自行转换。例如 debug = false 解析后是布尔值，判断时应写成 if config["debug"]:，而不是和 "false" 比较。

需要精确小数时怎样使用 parse_float

loads() 的 parse_float 参数会接收每个 TOML 浮点数的文本。金额、税率或比例这类场景可以交给 decimal.Decimal，避免先转成二进制浮点数：

from decimal import Decimal
import tomllib

toml_text = "price = 19.90\ntax_rate = 0.13"

# parse_float 接收浮点文本，返回 Decimal 后可保留十进制计算语义。
config = tomllib.loads(toml_text, parse_float=Decimal)

# 这里两个字段都是 Decimal，而不是默认的 float。
total = config["price"] * (Decimal("1") + config["tax_rate"])
print(total)

解析器函数只能返回适合作为配置值的对象；官方文档明确说明，parse_float 不能返回 dict 或 list，否则会抛出 ValueError。普通配置保持默认 float 即可，不要为了“精确”而无条件改变全部浮点字段。

格式错误怎样处理才容易定位

字符串来自用户输入、远程配置或环境变量时，最常见的问题不是键不存在，而是 TOML 文档本身不完整，例如字符串少了结束引号、数组逗号不正确或表头写错。可以单独捕获 TOMLDecodeError，把错误交给上层记录或返回：

import tomllib

def parse_config(text: str) -> dict:
    # 先限制输入规模，避免不可信长文本占用过多解析资源。
    if len(text) > 256 * 1024:
        raise ValueError("TOML 配置过大")

    try:
        # loads 只负责解析；默认的浮点策略适合一般配置。
        return tomllib.loads(text)
    except tomllib.TOMLDecodeError as exc:
        # 把 TOML 的语法错误转换成调用方可识别的配置错误。
        line = getattr(exc, "lineno", "?")
        column = getattr(exc, "colno", "?")
        raise ValueError(f"TOML 配置格式错误，位置 {line}:{column}") from exc

如果要展示原始错误位置，可以在支持这些属性的 Python 版本中读取 lineno 和 colno；为了兼容不同运行环境，上例用 getattr 提供了兜底。对不可信来源还应限制文本长度，因为复杂或恶意 TOML 可能消耗较多 CPU 和内存。

几个容易混淆的问题

loads() 能直接接收 bytes 吗？它的接口定义是接收 str。如果拿到的是文件或网络字节，应先按明确的字符编码解码，再把字符串传给 loads()；如果本来就是文件对象，则考虑 tomllib.load()。

解析成功后能用 tomllib 写回 TOML 吗？不能。tomllib 是只读解析模块，不提供 TOML 写入 API；需要生成或修改 TOML 时，应根据项目需求选择专门的写入库。

为什么不要只捕获 ValueError？TOMLDecodeError 确实是 ValueError 的子类，但单独捕获它能把 TOML 语法错误和其他业务层数值错误区分开，日志和提示更清楚。

小结

tomllib.loads 的使用重点可以压缩成三点：字符串配置直接传入，结果按 TOML 类型映射为嵌套 Python 对象；需要精确小数时通过 parse_float 指定解析器；不可信或外部输入要限制规模，并捕获 TOMLDecodeError。这样既能保持代码短小，也能把配置错误留在清晰的边界内。