Python tomllib 怎么解析日期时间而不丢失类型

tomllib 不会把合法的 TOML 日期时间字面量统一读成字符串。只要值没有被引号包围，它会自动返回 datetime.datetime、datetime.date 或 datetime.time；带偏移量的日期时间还会保留 tzinfo。真正容易“丢类型”的地方，通常是 TOML 本身把日期写成了字符串，或者应用在读取后过早调用了 str()。

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

先看配置负载：四种写法对应四种 Python 类型

tomllib 从 Python 3.11 起进入标准库，读取 TOML 1.0.0。日期时间不是额外插件能力，而是 TOML 类型系统的一部分。下面这个配置同时包含偏移日期时间、本地日期时间、本地日期和本地时间：

[job]
# 带 Z 的值表示一个明确的 UTC 时刻。
started_at = 2026-10-06T09:30:00Z
# 不带偏移量，只表达本地墙上时间。
local_start = 2026-10-06T17:30:00
# 只有日期，不包含时区和时间。
run_date = 2026-10-07
# 只有一天中的时间，不绑定具体日期。
cutoff = 23:15:00

这四个值进入 Python 后不会共用一个类型。官方转换表给出的对应关系如下：

约束条件：文件必须用二进制模式交给 load

读取文件时使用 rb。tomllib.load() 的第一个参数要求是可读的二进制文件对象，并返回普通 dict。如果配置已经在内存中是 str，则使用 tomllib.loads()。

from __future__ import annotations

import tomllib
from pathlib import Path
from typing import Any


def load_settings(path: Path) -> dict[str, Any]:
    # load() 要求二进制文件对象，tomllib 负责 UTF-8 解码和类型转换。
    with path.open("rb") as file:
        return tomllib.load(file)


settings = load_settings(Path("settings.toml"))
job = settings["job"]

# 这里拿到的是日期时间对象，不需要再手动 fromisoformat。
started_at = job["started_at"]
local_start = job["local_start"]
run_date = job["run_date"]
cutoff = job["cutoff"]

对于短字符串或测试数据，可以这样读取：

import tomllib

document = """
[job]
# 无引号日期会进入 datetime.date。
run_date = 2026-10-07
"""

# loads() 接收 str，而不是二进制文件对象。
settings = tomllib.loads(document)
run_date = settings["job"]["run_date"]

方案对比：检查类型，而不是再次解析字符串

推荐做法是把 tomllib 返回的对象直接带入业务层。这样日期比较、时间加减和时区判断都保留明确语义。为了尽早发现配置被错误加引号，可以在配置装载边界做类型检查。

from datetime import date, datetime, time
from typing import Any


def validate_job(job: dict[str, Any]) -> None:
    # 精确检查关键字段，避免被引号包围的日期悄悄变成 str。
    if not isinstance(job.get("started_at"), datetime):
        raise TypeError("job.started_at 必须是 TOML 日期时间字面量")
    if not isinstance(job.get("run_date"), date):
        raise TypeError("job.run_date 必须是 TOML 日期字面量")
    if not isinstance(job.get("cutoff"), time):
        raise TypeError("job.cutoff 必须是 TOML 时间字面量")

注意 datetime 是 date 的子类。如果某个字段必须是“纯日期”，而不能接受日期时间，可以使用 type(value) is date 做更严格的判断。配置模型较大时，也可以在这一层把原始字典转换成 dataclass，但没有必要先转成字符串再转回来。

推荐处理：明确区分 aware 与 naive datetime

带 Z 或 +08:00 的 offset date-time 表示明确时刻，tomllib 会设置 tzinfo。不带偏移量的 local date-time 只表达本地日期和时间，tzinfo 为 None。二者语义不同，不能靠“长得一样”混用。

from datetime import datetime
from typing import Any


def require_aware(value: Any, field: str) -> datetime:
    # 跨系统时间戳必须同时是 datetime 且包含时区信息。
    if not isinstance(value, datetime) or value.tzinfo is None:
        raise ValueError(f"{field} 必须包含 Z 或 UTC 偏移量")
    return value


started_at = require_aware(job["started_at"], "job.started_at")

不要在不知道业务时区的情况下直接给 naive datetime 填一个 tzinfo。本地日期时间可能表示门店营业时间、批处理窗口或用户所在地时间，真正的时区应由配置中的独立字段或业务上下文决定。

风险点：最常见的丢类型原因是把值写进引号

TOML 值一旦被引号包围，就明确变成字符串。下面两个值看起来只差一对引号，解析结果却完全不同：

[job]
# 无引号：TOML offset date-time，解析为 aware datetime。
started_at = 2026-10-06T09:30:00Z
# 有引号：普通字符串，tomllib 不会猜测它应该是日期时间。
label = "2026-10-06T09:30:00Z"

如果配置规范允许字符串形式，那就应由应用显式定义字符串格式并解析；如果目标是保留 TOML 原生类型，修复配置文件比在代码里猜测字符串更可靠。

风险点：parse_float 不能接管日期时间

tomllib.load() 和 loads() 的 parse_float 只会接收 TOML 浮点数字符串，例如用 decimal.Decimal 替换默认 float。它不是通用类型钩子，也不会改变日期时间映射。日期时间字段应依赖 TOML 原生语法和官方转换表，不要寻找不存在的 parse_datetime 参数。

只在导出边界调用 isoformat

Python 的标准 JSON 编码器不能直接序列化 datetime、date 和 time。这并不意味着读取时应该把它们全部变成字符串。更稳妥的架构是：配置层保留强类型，业务层完成比较和校验，只有在 JSON、日志或文本边界才转换。

from datetime import date, datetime, time
from typing import Any


def to_json_value(value: Any) -> Any:
    # 仅在序列化边界转成 ISO 8601 文本，业务层仍保留原类型。
    if isinstance(value, (datetime, date, time)):
        return value.isoformat()
    if isinstance(value, dict):
        return {key: to_json_value(item) for key, item in value.items()}
    if isinstance(value, list):
        return [to_json_value(item) for item in value]
    return value

isoformat() 是显式的边界转换。之后若还要恢复对象，接收方必须按协议解析；它不等同于 tomllib 的原生类型保持。

错误处理：无效 TOML 会抛出 TOMLDecodeError

日期写法不合法、键重复或文档结构错误时，tomllib 会抛出 TOMLDecodeError。应用应在配置入口把它转换成可定位的启动错误，而不是捕获后继续使用空配置。

from pathlib import Path
import tomllib


def read_required_config(path: Path) -> dict:
    try:
        # 二进制模式读取，并保留 TOML 原生类型。
        with path.open("rb") as file:
            return tomllib.load(file)
    except FileNotFoundError as exc:
        raise RuntimeError(f"配置文件不存在：{path}") from exc
    except tomllib.TOMLDecodeError as exc:
        # 保留原异常链，便于定位行列和语法原因。
        raise RuntimeError(f"配置格式错误：{path}") from exc

对于外部上传或其他不可信来源，还应限制配置体积。Python 官方文档明确提醒，恶意 TOML 字符串可能消耗大量 CPU 和内存。

落地清单

常见问题

tomllib 能直接写回 TOML 吗？

不能。标准库 tomllib 只负责读取。如果要写新 TOML，可以选择专门的写入库；如果要保留原文件注释和排版，需要使用支持样式保留的编辑库。

为什么比较两个 datetime 会报时区错误？

通常是一个值带 tzinfo，另一个不带。先确认 TOML 中是否一个值有 Z 或偏移量、另一个没有，再按业务规则统一时区语义，不要直接删除 tzinfo 掩盖差异。

能让 tomllib 把日期解析成自定义类吗？

没有内置日期时间转换钩子。先让 tomllib 得到标准库对象，再在配置模型层转换成自定义类型；parse_float 只针对浮点数。

所以，保持日期时间类型的关键并不是多写一层解析，而是让 TOML 使用原生日期时间字面量，让 tomllib 完成标准映射，并把字符串化推迟到真正需要输出的边界。