如何使用Ruamel.Yaml将完整YAML键值对批量转为注释内容

ruamel.yaml 没有直接提供将指定键值对整体转为注释的内置API，可通过「序列化目标键值对→逐行加注释符→替换原位置为注释」的逻辑自行实现，适配单行、多行、数组等所有格式，以下是可直接运行的实现：

步骤1：安装依赖 #

pip install ruamel.yaml

步骤2：完整实现代码 #

import io
import sys
from ruamel.yaml import YAML

def comment_out_key(yaml: YAML, parent_node, target_key: str):
    # 提取目标键值对
    target_content = {target_key: parent_node[target_key]}
    # 序列化目标键值对为原始YAML字符串，保留原有格式
    buffer = io.StringIO()
    yaml.dump(target_content, buffer)
    raw_lines = buffer.getvalue().rstrip().splitlines()
    # 逐行添加注释符
    commented_lines = [f"# {line}" for line in raw_lines]
    # 删除原键值对
    del parent_node[target_key]
    # 将注释插入到原键值对的对应位置，保持原有顺序
    if parent_node.ca.comment is None:
        parent_node.ca.comment = [None, []]
    for line in commented_lines:
        parent_node.ca.comment[1].append(yaml.CommentToken(f"{line}\n", error=None, problem=None))

# 测试用例
if __name__ == "__main__":
    yaml = YAML()
    yaml.preserve_quotes = True
    yaml.indent(mapping=2, sequence=4, offset=2)
    
    # 原始YAML内容
    raw_yaml = """
foo: bar
list_key:
  - item1
  - item2
  - nested:
      key1: val1
      key2: val2
other_key: test
"""
    data = yaml.load(raw_yaml)
    
    # 分别注释单行键foo和多行复合键list_key
    comment_out_key(yaml, data, "foo")
    comment_out_key(yaml, data, "list_key")
    
    # 输出结果
    yaml.dump(data, sys.stdout)

输出效果 #

# foo: bar
# list_key:
#   - item1
#   - item2
#   - nested:
#       key1: val1
#       key2: val2
other_key: test

注意事项 #

• 可通过调整yaml.indent参数匹配原YAML的缩进规则，保证注释后的格式和原有格式一致
• 该方案支持所有合法YAML结构，包括嵌套映射、数组、单行/多行字符串等格式
• 如果需要处理嵌套层级的键，先定位到目标键所在的父节点，再调用comment_out_key即可

内容的提问来源于stack exchange，提问作者Mark