TOML Kit 默认不支持 pathlib.Path 等自定义类型直接序列化，但可通过 tomlkit.register_encoder 注册自定义编码器，实现任意 Python 对象到 TOML 值的无侵入式转换。
toml kit 默认不支持 pathlib.path 等自定义类型直接序列化，但可通过 tomlkit.register_encoder 注册自定义编码器，实现任意 python 对象到 toml 值的无侵入式转换。
TOML Kit 提供了灵活且可扩展的序列化机制，核心在于 tomlkit.register_encoder() 函数。它允许你注册一个回调函数（encoder），该函数接收任意 Python 对象，若能处理则返回一个符合 TOML 规范的 tomlkit.items.Item 子类实例（如 String、Integer、Boolean 等）；否则应抛出 ConvertError，以便链式调用其他已注册的 encoder 或触发默认错误。
以下是一个将 pathlib.Path 无缝转为 TOML 字符串的完整示例：
from pathlib import Path
from typing import Any
import tomlkit
from tomlkit.items import Item, String, ConvertError
class PathItem(String):
"""可选：封装 Path 的专用 String 类，便于后续反序列化时识别"""
def unwrap(self) -> Path:
return Path(super().unwrap())
def path_encoder(obj: Any) -> Item:
if isinstance(obj, Path):
return PathItem.from_raw(str(obj)) # 转为字符串并保留语义
raise ConvertError # 不匹配时必须显式抛出 ConvertError
# 注册编码器（全局生效，只需一次）
tomlkit.register_encoder(path_encoder)
# 使用示例
data = {
"config_dir": Path("/etc/myapp"),
"log_file": Path("logs/app.log"),
"version": 1.2,
"enabled": True
}
toml_str = tomlkit.dumps(data)
print(toml_str)
输出结果：
config_dir = "/etc/myapp" log_file = "logs/app.log" version = 1.2 enabled = true
✅ 关键要点与注意事项：
- 编码器函数必须严格遵循签名 def encoder(obj: Any) -> Item，返回 tomlkit.items.Item 实例；
- 若无法处理当前对象，必须抛出 ConvertError（而非 TypeError 或 ValueError），否则会中断整个编码流程；
- 同一类型可注册多个 encoder，它们按注册顺序尝试，首个成功返回者生效；
- PathItem 继承自 String 是推荐做法——既复用 TOML 字符串语义，又可通过 unwrap() 方法反向还原为 Path（适用于需双向映射的场景）；
- 注册是全局操作，建议在应用初始化阶段集中完成，避免重复注册或竞态问题；
- 不支持嵌套结构中自动递归调用 encoder（如 {"nested": {"path": Path(...)}} 中的 Path 仍会被正确处理，因 tomlkit.dumps() 会对字典值逐个调用 encoder）。
通过这种方式，你不仅可以支持 Path，还能轻松扩展对 datetime、UUID、自定义数据类等类型的 TOML 序列化支持，真正实现“一次注册，处处可用”的优雅集成。
