用途:处理 Python 中的 TOML 配置文件(如 config.toml、pyproject.toml),解析、创建、修改并写回,重点是在 read-modify-write 过程中保留注释与格式。
主要能力:库选择上,需修改已有配置并保留注释与格式时用 tomlkit;仅需只读且为 Python 3.11+ 时可用标准库 tomllib。安装方式:uv add tomlkit 或 pip install tomlkit,要求 Python >=3.8、tomlkit >=0.12.0。
读取:tomlkit.parse()/loads() 解析字符串,tomlkit.load(f) 读取文件对象,TOMLFile("config.toml").read() 便捷读取,返回类字典的 TOMLDocument。
写入:tomlkit.dumps(data)、tomlkit.dump(data, f)、TOMLFile.write(doc)。创建可用 document()、table()、comment()、nl()、array()、inline_table();文档支持字典式访问、get、in、items、pop/remove,unwrap() 转纯 dict,as_string() 转 TOML 字符串。值助手包括 item、string、integer、float_、boolean、datetime、date、time。
错误处理:异常有 TOMLKitError、带 .line/.col 的 ParseError、NonExistentKey、KeyAlreadyPresent、ConvertError,可捕获 ParseError、FileNotFoundError 等。
常见模式:加载或创建配置、更新单值并保留注释、写到临时文件后原子替换、校验必填段落与键;也可与 dataclass 配合加载与保存。
限制与注意:直接改 unwrap() 返回的纯 dict 会丢失注释;读取值需校验类型;缺失键应使用 .get() 带默认值。TOML 遵循 v1.0.0 规范。配置路径可参考 XDG 基础目录(如 ~/.config/myapp/config.toml),相关技能包括 xdg-base-directory、standards-for-python-development、uv。资料未提供性能、平台兼容性等额外信息。