如何用ruamel.yaml为YAML列表添加带注释元素并指定位置？

问题描述 #

现有如下结构的YAML文件：

# Comment for item one
- key1: item1
  key2: item1
# Comment for item two
- key1: item2
  key2: item2
# Comment for item seven
- key1: item7
  key2: item7

需求：

1. 给列表添加带有对应注释的新条目（比如添加key1: item5, key2: item5，对应注释# Comment for item five）
2. 按字母/数字顺序将新条目插入到列表的合适位置（示例中将item5插入到item2和item7之间）

解决方案 #

用ruamel.yaml可以完美实现需求——它支持保留原有注释结构、添加带注释的新条目，还能按规则排序插入。

1. 安装依赖 #

先安装ruamel.yaml库：

pip install ruamel.yaml

2. 实现代码 #

以下代码会读取原YAML，添加带注释的新条目，按key1的值排序后写入文件，全程保留注释格式：

from ruamel.yaml import YAML
from ruamel.yaml.comments import CommentedSeq, CommentedMap

# 初始化YAML处理器，保留原文件格式
yaml = YAML()
yaml.preserve_quotes = True
yaml.indent(mapping=2, sequence=4, offset=2)

# 读取原YAML文件
with open('input.yaml', 'r', encoding='utf-8') as f:
    data = yaml.load(f)

# 准备新条目和对应的注释
new_entry = CommentedMap([('key1', 'item5'), ('key2', 'item5')])
entry_comment = '# Comment for item five'

# 添加新条目到列表
data.append(new_entry)
# 给新条目添加前置注释
data.yaml_set_start_comment(entry_comment, before=True)

# 定义排序规则：提取item后的数字转整数排序，确保顺序正确
def sort_by_item_num(entry):
    return int(entry['key1'].split('item')[1])

# 排序并重新构建带注释的序列
sorted_entries = CommentedSeq(sorted(data, key=sort_by_item_num))

# 复制原有注释到排序后的序列，保持注释与条目的关联
for idx, entry in enumerate(sorted_entries):
    original_pos = data.index(entry)
    if original_pos in data.ca.items:
        sorted_entries.ca.items[idx] = data.ca.items[original_pos]

# 复制文件顶部的注释（如果有）
if data.ca.comment:
    sorted_entries.ca.comment = data.ca.comment

# 写入结果文件
with open('output.yaml', 'w', encoding='utf-8') as f:
    yaml.dump(sorted_entries, f)

3. 输出结果 #

运行代码后，输出的YAML内容如下：

# Comment for item one
- key1: item1
  key2: item1
# Comment for item two
- key1: item2
  key2: item2
# Comment for item five
- key1: item5
  key2: item5
# Comment for item seven
- key1: item7
  key2: item7

关键细节 #

• ruamel.yaml的CommentedSeq和CommentedMap是核心，它们能完整存储YAML的注释元数据
• yaml_set_start_comment方法可以精准给新条目添加前置注释
• 排序时必须手动复制注释信息，确保每个条目和它的注释对应关系不被打乱
• 如果只需要字符串排序，直接用entry['key1']作为排序键即可

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