如何在 PyYAML 中正确序列化 pathlib.Path 对象

本文介绍如何为 PyYAML 注册自定义 YAML 表示器，使 pathlib.Path（如 PosixPath 或 WindowsPath）对象能被安全地序列化为 YAML 字符串，避免 RepresenterError。

本文介绍如何为 pyyaml 注册自定义 yaml 表示器，使 `pathlib.path`（如 `posixpath` 或 `windowspath`）对象能被安全地序列化为 yaml 字符串，避免 `representererror`。

在使用 PyYAML 的 safe_dump 或 safe_dump_all 序列化嵌套数据结构时，若对象中包含 pathlib.Path 实例（例如 Path(“/etc/config”)），默认会触发 RepresenterError：cannot represent an Object。这是因为 PyYAML 的 SafeDumper 仅支持基础类型（str, int, list, dict, bool, None 等），不识别 Path 类型——与 json 不同，YAML 没有内置的“通用编码器钩子”（如 JSONEncoder.default），而是依赖显式的 representer 注册机制。

✅ 正确解决方案是：为 pathlib.Path 类注册一个自定义多类型表示器（multi-representer），将其统一转换为标准字符串：

import yaml from pathlib import Path  def represent_path(dumper, path):     return dumper.represent_str(str(path))  # 全局注册：所有 Path 子类（PosixPath、WindowsPath 等）均适用 yaml.add_multi_representer(Path, represent_path)

注册后，即可照常使用 safe_dump 或 safe_dump_all：

data = {     "config_dir": Path("/etc/myapp"),     "log_paths": [Path("/var/log/app.log"), Path("/tmp/debug.json")],     "enabled": True, }  with open("config.yaml", "w") as f:     yaml.safe_dump(data, f, indent=2, default_flow_style=False)

生成的 YAML 将正确显示为：

config_dir: /etc/myapp enabled: true log_paths: - /var/log/app.log - /tmp/debug.json

⚠️ 注意事项：

• ✅ 使用 add_multi_representer（而非 add_representer）可确保 Path 的所有子类（如 PosixPath, WindowsPath, PurePath）均被覆盖；
• ✅ dumper.represent_str(str(path)) 是推荐做法：str(path) 安全、跨平台，且语义清晰（等价于 os.fspath(path)）；
• ❌ 避免直接返回 dumper.represent_scalar(…) —— 它绕过类型安全检查，可能引发意外行为；
• ⚠️ 注册需在调用 dump/dump_all 之前完成，且只需执行一次（通常放在模块顶层或初始化逻辑中）；
• ? 若项目需严格隔离（如多线程/多配置场景），可创建自定义 Dumper 子类并局部注册，但绝大多数场景全局注册已足够安全。

总结：PyYAML 的可扩展性依赖于显式 representer 注册。通过三行核心代码（导入 + 函数定义 + 注册），即可无缝支持 pathlib.Path 序列化，兼顾简洁性、健壮性与可维护性。