如何用Python最小侵入式编辑YAML文件（保留格式、注释等）

问题背景 #

我有如下YAML源文件：

top_level: &TL
  field0: somestring
  field1: "this one has quotes"
  field2: [1,2,3]
  # This comment describes something very important about field3
  field3:
    deep_list:
      - name: foo
        field1: bar
        field2: baz
        quoxx: { flow_form: 42, bar: [one, two], field}
        # Here is another super important comment about the blockform field
        blockform:
          - one
          - two
          - three
      - name: bar
        message: I was written by a human
                 and deliberately formatted
                 this way for a good reason.

level0:
  level1:
    level2:
      - item
      - item2: 23
        tl: *TL

我需要用Python程序修改这个文件，比如给top_level.field3.deep_list添加新元素，但要求完全保留原文件的格式、字符串引用规则、锚点（anchors）及注释，只修改数据变更直接影响的行，其余内容一丝不动。

之前试过ruamel.yaml，它在往返序列化时能保留大部分格式和注释，但存在明显缺陷——比如无法保留字符串的空格或换行格式（像示例中bar的message字段那种多行缩进的格式会被破坏）。想知道有没有更优的方案实现真正的最小侵入式编辑。

可行方案推荐 #

1. 优化ruamel.yaml配置实现格式保留 #

其实ruamel.yaml并非完全做不到保留多行字符串格式，只是需要针对性配置：

• 启用typ='rt'（往返模式），确保加载时保留原始结构信息；
• 设置preserve_quotes=True保留原字符串的引号规则；
• 避免手动转换字符串类型，让库自动识别并保留原格式。

示例代码：

from ruamel.yaml import YAML

# 初始化YAML对象，启用往返模式
yaml = YAML(typ='rt')
yaml.preserve_quotes = True
yaml.default_style = None

# 加载原文件
with open('source.yaml', 'r') as f:
    doc = yaml.load(f)

# 添加新元素到目标列表，严格匹配原格式风格
new_item = {
    'name': 'new_entry',
    'message': 'New multi-line message\n    following original indent\n    style'
}
doc['top_level']['field3']['deep_list'].append(new_item)

# 配置输出缩进匹配原文件
yaml.indent(mapping=2, sequence=4, offset=2)
# 写入修改后的文件
with open('modified.yaml', 'w') as f:
    yaml.dump(doc, f)

如果原文件中存在无引号的多行缩进字符串（如示例中bar的message），可以手动指定节点的style属性，避免格式被调整：

# 获取原始message节点的style，应用到新节点
original_style = doc['top_level']['field3']['deep_list'][1]['message'].style
new_item['message'] = yaml.scalarstring.PreservedScalarString(new_item['message'], style=original_style)

2. 文本层面的局部匹配修改 #

如果ruamel.yaml的优化仍无法满足极致的格式保留需求，可以直接对YAML文件做文本层面的局部修改：

• 通过正则匹配定位到目标列表的区域；
• 找到列表最后一个元素的结束位置，插入严格匹配原格式的新元素；
• 这种方式完全不解析YAML结构，能100%保留原格式，但缺点是对文件格式变化敏感，缩进、换行风格改变会导致正则失效。

示例代码（针对示例文件的特定格式）：

import re

with open('source.yaml', 'r') as f:
    content = f.read()

# 匹配deep_list的完整列表块
pattern = re.compile(
    r'(deep_list:\n(?:\s+- name: .+\n(?:\s+.*\n)*))',
    re.MULTILINE | re.DOTALL
)
match = pattern.search(content)
if match:
    deep_list_block = match.group(1)
    # 构造新元素，严格对齐原文件的缩进和换行格式
    new_element = '''      - name: new_entry
        message: New human-written
                 multi-line message
                 matching original format'''
    # 替换原块为添加新元素后的内容
    modified_block = deep_list_block.rstrip('\n') + '\n' + new_element + '\n'
    modified_content = content.replace(deep_list_block, modified_block)
    
    with open('modified.yaml', 'w') as f:
        f.write(modified_content)

3. 小众专用库补充 #

Python生态中还有一些专注YAML格式保留的小众库，比如yamlfix（主要用于格式标准化，而非数据修改）、pyyaml-preserve（基于PyYAML的分支，增强格式保留），但这些库的成熟度和社区支持度远不如ruamel.yaml，仅作为备选方案。

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