tomllib是Python 3.12+标准库只读TOML解析模块，无需pip安装；仅支持load，不支持dump或写入；与tomli API兼容但不可混用，需用sys.version_info >= (3, 12)判断可用性。
tomllib 是标准库模块，不需要 pip install
Python 3.12 已将 tomllib 正式纳入标准库（PEP 680），它替代了第三方 toml 或 tomli 库用于只读解析。你无需安装任何包，直接 import tomllib 即可使用——但要注意，它**只提供解析（load），不提供序列化（dump）**，也**不支持写入或修改 TOML 文件**。
常见错误是误以为 tomllib 和 tomli 完全兼容：虽然 API 高度一致，但 tomllib 在 Python 3.12+ 中才存在，低版本会抛出 ModuleNotFoundError；而 tomli 在 3.12 中仍可用，但属于冗余依赖。
- 确认运行环境：用
sys.version_info >= (3, 12)判断是否可用tomllib - 不要在项目中同时声明
tomli为依赖（除非需兼容 - 若用 Poetry / pip-tools，避免在
pyproject.toml的依赖中写死tomli（除非明确需要向下兼容）
用 tomllib.load() 解析文件时必须传入二进制模式打开的文件对象
tomllib.load() 只接受 BinaryIO（如 open(..., "rb") 返回的对象），不接受文本模式（"r"）或字符串路径。这是和 json.load() 的关键区别，也是最常踩的坑。
错误示例：tomllib.load(open("config.toml")) 会报 TypeError: expected bytes-like object, not str；正确做法是确保以 "rb" 模式打开，并用 try/except 包裹解析过程。
立即学习“Python免费学习笔记（深入）”；
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
- ✅ 正确写法：
with open("config.toml", "rb") as f: data = tomllib.load(f) - ❌ 错误写法：
tomllib.load(open("config.toml", "r"))或tomllib.load("config.toml") - 解析失败时抛出
tomllib.TOMLDecodeError，包含行号和列号（如TOMLDecodeError: Invalid leading character at line 5, column 1），可直接用于定位配置语法错误
tomllib 不支持自定义解码器、钩子或扩展类型
tomllib 的设计目标是安全、轻量、标准兼容，因此**完全不支持**类似 json.loads(..., object_hook=...) 的钩子机制，也不支持解析日期、自定义类等扩展类型。所有值都按 TOML 规范映射为 Python 原生类型（str, int, float, bool, datetime, list, dict）。
这意味着：如果你的配置里写了 created = 2024-04-01T10:30:00Z，它会被解析为 datetime.datetime 对象（符合规范）；但如果你写了 version = v1.2.3（非标准语法），就会直接报错，不会尝试转成字符串。
- 无法实现“把每个 table 自动转成
dataclass实例”这类逻辑——得在tomllib.load()之后手动处理 - 不支持注释提取、位置信息保留、多文档（
---分隔）等高级功能 - 安全性高：不执行代码、不导入模块、不调用任意用户函数，适合解析不可信来源的配置（如用户上传的 config.toml）
从 Python 3.11 迁移时要注意 import 路径和异常类型
在 Python 3.11 及更早版本中，你可能用的是第三方 tomli，其 import 写法为 import tomli，异常是 tomli.TOMLDecodeError。升级到 3.12 后若直接替换为 import tomllib，需同步调整异常捕获逻辑，因为 tomllib.TOMLDecodeError 是独立类型，与 tomli.TOMLDecodeError 不兼容（即使名字相同）。
- 迁移前：
except tomli.TOMLDecodeError as e: - 迁移后：
except tomllib.TOMLDecodeError as e: - 若需兼容 3.11 和 3.12，可用
try/except ImportError做 fallback，但注意两个模块的异常类不能用isinstance(e, ...)统一判断 -
tomllib不提供tomllib.loads()的字符串解析快捷函数（3.13 才加入），目前只能先用io.BytesIO(b"..." )包装字节再传给load()
真正麻烦的不是语法怎么写，而是当配置来自外部（比如 CI 环境注入、用户提交表单）时，tomllib 的零扩展性意味着所有结构校验、默认值填充、类型转换都得自己补全——它只做一件事：把合法 TOML 字节安全地变成 dict。别指望它替你做数据验证。
