本文深入探讨了如何利用 `ruamel.yaml` 库在 Python 中加载、修改并重新保存 YAML 文件时，精确地保留原始文件的格式细节，包括字符串的引用样式、布尔值的表示方式、文档起始标记以及缩进结构。通过配置 `YAML` 实例的特定属性，开发者可以实现对 YAML 文件的无损往返编辑，确保输出文件与输入文件的视觉和结构一致性。
理解 YAML 格式化与 Python 处理
在使用 Python 处理 YAML 文件时，特别是需要进行少量修改后重新保存的场景，一个常见的挑战是如何在输出时保持原始文件的格式一致性。标准的 YAML 解析器（如 PyYAML）在加载 YAML 文件时，通常会将数据转换为 Python 对象（如字典、列表、字符串、布尔值等），在这个过程中，原始的格式信息（如字符串的单引号/双引号、布尔值的大小写、注释、空白行等）会被丢弃。当这些数据被重新序列化回 YAML 格式时，解析器会根据其默认的序列化规则生成新的格式，这往往与原始文件的格式有所不同。
例如，一个被单引号包裹的字符串 'John Doe' 在加载后会变成普通的 Python 字符串 John Doe。当重新写入时，如果字符串内容不包含需要强制引用的特殊字符，它可能就不会被再次引用。同样，布尔值 True 可能会被序列化为小写的 true。文档起始标记 --- 如果不包含指令，也可能被省略。这些行为虽然符合 YAML 规范，但对于需要严格保持文件格式（例如，为了版本控制系统中的最小化差异）的场景来说，却是一个问题。
ruamel.yaml 库专为此类“往返”（round-trip）编辑场景设计，它能够解析并存储原始文件的格式信息，允许用户在修改数据结构的同时，保留大部分原始的格式细节。
使用 ruamel.yaml 精确控制 YAML 输出格式
ruamel.yaml 提供了一系列强大的配置选项，通过设置 YAML 实例的属性，可以精确控制 YAML 文件的加载和保存行为。以下是几个关键的配置选项及其用法：
1. 保留字符串引用 (preserve_quotes)
默认情况下，ruamel.yaml 在输出字符串时，如果字符串内容不需要强制引用，它可能会移除原始的引号。通过设置 preserve_quotes = True，可以指示 ruamel.yaml 尽可能保留原始字符串的引用样式（单引号或双引号）。
yaml = ruamel.yaml.YAML() yaml.preserve_quotes = True
2. 显式文档起始标记 (explicit_start)
YAML 文件通常以 --- 作为文档的起始标记。如果文件中没有定义任何 YAML 指令，这个标记在默认序列化时可能会被省略。设置 explicit_start = True 可以确保在输出时始终包含 --- 标记。
yaml = ruamel.yaml.YAML() yaml.explicit_start = True
3. 控制布尔值表示 (boolean_representation)
YAML 规范允许布尔值有多种表示形式，如 true/false、True/False、TRUE/FALSE 等。ruamel.yaml 默认会将布尔值序列化为小写形式。如果你需要特定的布尔值表示（例如，始终使用 True/False），可以通过 boolean_representation 属性进行设置。这个属性接受一个包含两个字符串的列表，分别代表 False 和 True 的输出形式。
yaml = ruamel.yaml.YAML() yaml.boolean_representation = ['False', 'True']
4. 自定义缩进 (indent)
YAML 的可读性很大程度上依赖于其缩进结构。ruamel.yaml 允许你精确控制映射（字典）、序列（列表）以及序列项的偏移量。indent() 方法接受三个参数：
- mapping: 映射键值对的缩进量。
- sequence: 序列项的缩进量。
- offset: 序列项前 - 符号的偏移量（相对于其父级的缩进）。
yaml = ruamel.yaml.YAML() yaml.indent(mapping=2, sequence=4, offset=2)
上述配置表示：映射键值对缩进 2 个空格；序列项缩进 4 个空格；序列项前的 - 符号相对于其父级缩进 2 个空格。
综合示例
以下是一个完整的示例，演示如何结合上述所有配置，实现对 YAML 文件的无损往返编辑。我们将使用一个包含多种格式特性的 YAML 字符串作为输入，并观察 ruamel.yaml 如何保留这些特性。
import sys
import ruamel.yaml
# 示例输入 YAML 字符串，包含注释、引用字符串、布尔值大小写和特定缩进
yaml_str = """---
# *REQUIRED*
person:
name: 'John Doe'
age: '30'
city: 'Sample City'
apis:
- 'bigquery'
- 'bigquerydatatransfer'
- 'bigquerystorage'
- 'bigtableadmin'
- 'cloudbuild'
- 'cloudkms'
preferences:
theme: 'dark'
language: en_US
test: '77'
shared_vpc_service: 'shared-vpc-admin'
#################################################################
#################################################################
# *OPTIONAL* - Add Project to VPC Service Controls Security Perimeter
# Default: True
# If Set to False - Project will not be added to VPC Service Controls
enable_vpc_svc_ctrls: True
#################################################################
"""
# 创建 YAML 实例并配置格式保留选项
yaml = ruamel.yaml.YAML()
# 配置缩进：映射缩进2，序列缩进4，序列项符号偏移2
yaml.indent(mapping=2, sequence=4, offset=2)
# 确保输出包含文档起始标记 ---
yaml.explicit_start = True
# 配置布尔值输出为 'False'/'True'
yaml.boolean_representation = ['False', 'True']
# 保留原始字符串的引用样式
yaml.preserve_quotes = True
# 加载 YAML 数据
data = yaml.load(yaml_str)
# 假设在这里对 data 进行一些修改，例如添加一个键值对
# data['preferences']['new_setting'] = 'value'
# 将修改后的数据倾倒回标准输出
print("--- 输出结果 ---")
yaml.dump(data, sys.stdout)
运行上述代码，你将看到输出的 YAML 字符串与输入的 yaml_str 几乎完全一致，包括字符串的单引号、布尔值的 True、文档起始的 --- 以及注释和缩进结构。
注意事项与最佳实践
- 一致性与标准化： 虽然 ruamel.yaml 提供了强大的格式保留能力，但在某些情况下，标准化 YAML 文件的格式可能更为有利，尤其是在大型项目或团队协作中。一致的格式可以减少版本控制系统中的不必要差异，并提高可读性。
- 注释的保留： ruamel.yaml 在默认情况下也能很好地保留注释。当你在加载数据后修改数据结构时，关联到特定行或块的注释通常会被保留下来。
- 复杂场景： 对于非常复杂的 YAML 结构或高度定制化的格式要求，可能需要更深入地了解 ruamel.yaml 的内部机制，甚至自定义表示器。但对于大多数常见的格式保留需求，上述配置已经足够。
- 性能考虑： ruamel.yaml 为了实现往返功能，会存储更多的原始信息，这可能会比纯粹的数据解析器消耗更多的内存和处理时间。在处理超大型 YAML 文件时，需要权衡性能与格式保留的需求。
总结
ruamel.yaml 是一个功能强大的 Python 库，特别适用于需要对 YAML 文件进行“往返”编辑并精确保留原始格式的场景。通过灵活配置 YAML 实例的 preserve_quotes、explicit_start、boolean_representation 和 indent 等属性，开发者可以有效地控制输出 YAML 文件的格式，确保其与输入文件的高度一致性。掌握这些技巧，将极大地提高在自动化脚本和配置管理中处理 YAML 文件的效率和准确性。
