Python tomllib 读取配置并保留类型信息

配置文件里最容易被低估的不是读取，而是读取之后的类型。用 Python 3.11 及以上版本的 tomllib 解析 TOML 时，字符串仍是 str，整数是 int，布尔值是 bool，数组和表分别落到 list 与 dict；日期字段还会得到 date 或 datetime。需要精确处理金额、比例等小数时，把 parse_float 指向 Decimal 即可。官方资料入口：https://docs.python.org/3/library/tomllib.html。

确认 tomllib 的入口和类型映射

tomllib 是只读解析器，输入可以来自文件或内存字符串。文件入口是 load(fp)，字符串入口是 loads(s)。两者都返回嵌套 dict，但不会把 TOML 中的每个值都粗暴转成文本，这正是它适合配置读取的地方。

用 load 读取文件并保留嵌套结构

我更推荐把读取动作包在一个小函数里：文件打开方式、异常边界和返回对象集中在一起，调用方只拿配置字典。注意官方示例使用 rb，不要把文本模式的文件句柄直接传给 load。

import tomllib

def read_settings(path="settings.toml"):
    # tomllib.load 读取二进制文件，并把 TOML 映射为嵌套 Python 对象
    with open(path, "rb") as fp:
        return tomllib.load(fp)

config = read_settings()
server = config["server"]
retry_delays = config.get("retry", {}).get("delays", [])

# 表、数组和整数保持原类型，调用方不需要再次 split 或 int 转换
assert isinstance(server["port"], int)
assert isinstance(retry_delays, list)

如果配置中有 [[workers]]，得到的是 list[dict]；如果写了 release = 2026-09-29，得到的是 datetime.date。这类类型信息值得保留到业务层，避免后面再猜字符串格式。

用 parse_float 保留小数精度

默认浮点值按 float 解码。对于需要十进制语义的配置，可使用 decimal.Decimal：

from decimal import Decimal
import tomllib

def read_pricing(text):
    # parse_float 接管 TOML 浮点字面量，避免先变成二进制 float
    data = tomllib.loads(text, parse_float=Decimal)
    price = data["pricing"]["unit_price"]
    # 业务层仍要校验范围，解析成功不代表配置一定可用
    if price 

parse_float 的回调必须返回标量，返回 list 或 dict 会触发 ValueError。它只影响 TOML 浮点字面量，不会把整数、字符串或日期统一改成 Decimal。

区分语法错误与业务校验

TOML 写错时，tomllib 会抛出 TOMLDecodeError；字段缺失、端口超范围或价格为负，则属于应用自己的规则。把两者分开记录，排查时会清楚很多。

import tomllib

def load_checked(path):
    # 只把文本格式错误归到 TOMLDecodeError，保留原始错误上下文
    try:
        with open(path, "rb") as fp:
            data = tomllib.load(fp)
    except tomllib.TOMLDecodeError as exc:
        raise ValueError(f"TOML 语法错误：第 {exc.lineno} 行") from exc

    # 这里是应用层约束，不要伪装成解析器错误
    if "server" not in data or not 1 

按场景选择读取方式并收住边界

最后一个边界很重要：读取器不是配置编辑器。对不可信来源的 TOML 也应限制输入大小，避免把解析器当成无限制的数据入口。

常见问题

tomllib.load 为什么要用 rb 模式？

官方接口要求可读取的二进制文件对象。直接用 open(path, "rb") 最稳妥，文本模式留给需要先得到字符串再调用 loads 的场景。

日期字段会一直是字符串吗？

不会。符合 TOML 日期语法的值会映射为 date、time 或 datetime；带偏移的日期时间会携带时区信息。

tomllib 能把配置改完再保存吗？

不能。它负责解析读取；需要保留格式并写回时，应选择明确提供写入能力的 TOML 库。