如何使用ruamel.yaml在Python中生成带锚点与合并语法的YAML文档

嘿，我完全懂你的需求——想要用Python生成带锚点（&ANCHOR）和合并（<<: *ANCHOR）语法的YAML文件，而且ruamel.yaml确实是最佳选择，毕竟它在锚点处理上比PyYAML靠谱太多：

• 它能透明加载带锚点和合并的YAML文件：不管数据是通过锚点复用还是直接定义的，你在Python里访问这些数据的方式完全一样
• 它支持往返（round-trip）编辑：读入一个带锚点的YAML文件，修改后再写回磁盘，锚点和合并语法都会原封不动保留

这说明ruamel.yaml内部肯定有一套能识别锚点的元数据结构，只是官方没把“从Python代码手动创建锚点”这件事写进文档里。不过咱们可以通过它的内部API实现这个需求。

你想要生成的最简YAML文档是这样的：

base: &ANCHOR
  x: 1

object:
  <<: *ANCHOR
  y: 2

具体实现代码 #

下面是用ruamel.yaml生成这个文件的完整代码，每一步我都给你标注清楚：

from ruamel.yaml import YAML
from ruamel.yaml.comments import CommentedMap
from ruamel.yaml.scalarstring import PlainScalarString

# 1. 初始化YAML实例，用round-trip模式（必须用这个模式才能处理锚点元数据）
yaml = YAML()
# 调整缩进格式，让输出更符合常规YAML风格
yaml.indent(mapping=2, sequence=4, offset=2)

# 2. 创建带锚点的base对象
base = CommentedMap()
base['x'] = 1
# 给base设置锚点，always_dump=True确保锚点一定会被输出
base.yaml_set_anchor('ANCHOR', always_dump=True)

# 3. 创建包含合并语法的object对象
obj = CommentedMap()
# 添加合并项：<< 是YAML的特殊合并键，需要用PlainScalarString标记确保被正确识别
obj[PlainScalarString('<<')] = PlainScalarString('*ANCHOR')
obj['y'] = 2

# 4. 组装顶层数据结构
yaml_data = CommentedMap()
yaml_data['base'] = base
yaml_data['object'] = obj

# 5. 写入文件
with open('output.yaml', 'w') as f:
    yaml.dump(yaml_data, f)

关键要点解释 #

1. 为什么用CommentedMap而不是普通dict？
   普通Python字典没有存储锚点元数据的能力，CommentedMap是ruamel.yaml专门用来保存YAML映射（mapping）及其元数据（比如锚点、注释）的类，它自带yaml_set_anchor方法来设置锚点。

2. PlainScalarString的作用是什么？
   如果直接用普通字符串'<<'作为键，ruamel.yaml可能会把它当成普通的映射键而不是YAML的特殊合并键。用PlainScalarString标记后，它会被识别为原始的YAML标量，确保合并语法生效。

3. yaml_set_anchor的always_dump参数
   这个参数确保即使锚点被引用，也会在定义的地方输出锚点标记（&ANCHOR）。如果不设置，当锚点被引用时ruamel.yaml也会自动输出，但显式设置更稳妥，避免特殊场景下锚点不显示的问题。

备注：内容来源于stack exchange，提问作者julaine