Python tomllib 只读场景下的 TOML 配置写回方案

如果你用 Python tomllib 读取 pyproject.toml 或业务配置，写回时不要继续寻找不存在的 dump 方法：它是只读解析器。实际方案很明确，只关心数据结果就用 tomli-w 重建 TOML；必须保留注释、缩进和原始排版就用 TOML Kit 编辑文档对象。写入生产配置时，再用临时文件加原子替换，避免进程中断留下半个文件。

官方地址：https://docs.python.org/3/library/tomllib.html

先把 tomllib 的职责边界钉死

Python 官方文档把 tomllib 定义为 TOML 解析接口：load 接受可读的二进制文件对象并返回字典，loads 接受字符串并返回字典。它还会把日期、数组和表映射成对应的 Python 类型，但没有写文件 API。下面的读取方式可以作为后续写回的输入，却不能反向恢复原文的注释和空白。

import tomllib

with open("settings.toml", "rb") as source:
    # 读取阶段只负责把 TOML 转成 Python 数据。
    settings = tomllib.load(source)

# 这里修改的是内存中的字典，不会自动写回 settings.toml。
settings["server"]["port"] = 9000

按保留要求选择写入库

先问一个比“哪个库更好”更重要的问题：写回后是否必须保留原文件的注释、缩进和空白？如果配置只是机器生成的结果，重新序列化通常更简单；如果文件由人维护，注释和排版本身就是信息，应该选能保留文档结构的库。

tomli-w 官方地址：https://pypi.org/project/tomli-w/；TOML Kit 官方地址：https://pypi.org/project/tomlkit/。

只关心数据结果时用 tomli-w 重建

配置由程序统一生成时，tomli_w.dump 或 dumps 足够直接。生产写回不要直接覆盖目标文件：先在同一目录写临时文件，刷新内容后再调用 os.replace。同一文件系统内替换能把“旧文件”或“新文件”作为可见结果，降低中断造成的半写风险。

import os
import tempfile
import tomllib
import tomli_w

with open("settings.toml", "rb") as source:
    # 先读取并修改结构化数据，注释不会进入这个字典。
    settings = tomllib.load(source)
settings["server"]["port"] = 9000

directory = os.path.dirname(os.path.abspath("settings.toml"))
with tempfile.NamedTemporaryFile("wb", dir=directory, delete=False) as temp:
    # tomli-w 从映射重建文档；临时文件与目标文件放在同一目录。
    tomli_w.dump(settings, temp)
    temporary_name = temp.name

# 写入完成后再替换目标，异常时可清理临时文件。
try:
    os.replace(temporary_name, "settings.toml")
except Exception:
    os.unlink(temporary_name)
    raise

这条路径的代价是明确的：注释、原始空行和某些排版选择不会从 tomllib 的字典里回来。若这些内容影响人工维护，就不要把 tomli-w 当成无损编辑器。

必须保留注释和排版时用 TOML Kit

TOML Kit 的定位是可编辑、保留风格的 TOML 库。它可以解析成文档对象，在对象上修改字段，再序列化回文件；官方说明覆盖了注释、缩进、空白和内部元素顺序。适合人工维护的项目配置、带说明注释的部署模板和需要小范围改字段的工具。

from pathlib import Path
from tomlkit import dumps, parse

path = Path("settings.toml")
document = parse(path.read_text(encoding="utf-8"))

# 只改目标字段，让 TOML Kit 负责保留文档结构。
document["server"]["port"] = 9000
path.write_text(dumps(document), encoding="utf-8")

如果并发进程也会修改同一个文件，这段代码还需要加锁、版本号或重试策略；“保留注释”解决的是文档表达问题，不等于解决并发写冲突。

上线前的回归检查

1. 重新用 tomllib.load 解析写出的文件，确认语法和关键类型没有变化。
2. 核对目标字段是否真的被更新，尤其是端口、路径、布尔值和日期类型。
3. 检查临时文件清理、目标文件权限以及同目录替换条件。
4. 人工维护的配置优先用 TOML Kit；机器生成的配置才考虑 tomli-w 的完整重建。

常见问题

tomllib 能不能直接修改并保存原文件？

不能。它返回的是 Python 数据，官方接口不包含写回方法；需要另选写入库。

tomli-w 会不会保留 TOML 注释？

不会。它根据映射重新生成文本，带注释的原文应交给 TOML Kit 或其他保留风格的编辑器。

写完后为什么还要再次解析？

再次解析能确认序列化结果仍是合法 TOML，并尽早发现类型、键名或自定义数据导致的写入问题。