本文详细介绍了如何使用 `ruamel.yaml` 库在Python中加载、修改并保存YAML文件时，最大限度地保留其原始格式，包括标量值的引号、文档起始标记 `---`、注释、以及布尔值的特定大小写。通过配置 `preserve_quotes`、`explicit_start`、`boolean_representation` 和 `indent` 等属性，`ruamel.yaml` 能够实现近乎完美的往返（round-trip）格式保留，这对于维护配置文件的一致性至关重要。
在处理YAML配置文件时，我们经常需要读取文件内容、进行少量修改，然后将其保存回文件。然而，许多YAML库在加载和保存过程中，可能会“优化”掉一些原始格式细节，例如字符串周围的引号、布尔值的大小写（True 变为 true）、文档起始标记 ---，甚至丢失注释和特定的缩进风格。这对于那些需要严格保持文件原始外观或依赖特定格式进行版本控制的场景来说，是一个不小的挑战。
ruamel.yaml 是一个专为往返（round-trip）编辑设计的Python YAML库，它能够尽可能地保留原始YAML文件的结构、样式和注释。本文将深入探讨如何利用 ruamel.yaml 的高级特性来精确控制YAML的输出格式。
1. YAML格式丢失问题分析
标准的YAML解析器通常会将YAML内容解析成Python数据结构（如字典、列表、字符串、布尔值等）。在这个过程中，许多格式信息，例如：
立即学习“Python免费学习笔记（深入）”；
- 字符串引号：'John Doe' 和 John Doe 在解析后都变为Python字符串 'John Doe'。在序列化时，解析器通常不会自动添加引号，除非字符串内容需要（例如包含特殊字符或数字）。
- 布尔值大小写：True、true、TRUE 在Python中都表示布尔值 True。序列化时，通常默认输出为小写的 true。
- 文档起始标记 ---：如果YAML文件中没有指令，这个标记在逻辑上是可选的，许多解析器在序列化时会省略它。
- 注释：注释在数据结构中没有对应，因此通常在加载时被丢弃。
- 缩进风格：不同的缩进（如映射项和序列项的缩进）在序列化时可能会被统一。
这些“优化”虽然在数据层面无害，但在文件内容层面却可能导致不必要的差异，尤其是在使用版本控制系统时。
2. 使用 ruamel.yaml 实现往返保留
ruamel.yaml 的核心优势在于其能够解析YAML的结构和内容，同时保留其原始的格式信息。要实现精确的格式控制，我们需要在 YAML() 实例上配置一些关键属性。
以下是实现高度格式保留的 ruamel.yaml 配置方法：
2.1 引入库与基本设置
首先，我们需要导入 ruamel.yaml 库。
import sys import ruamel.yaml
创建一个 YAML 实例是操作YAML文件的起点。
yaml = ruamel.yaml.YAML()
2.2 控制缩进风格
YAML的缩进是其结构的关键。ruamel.yaml 允许你精确控制映射（字典）和序列（列表）的缩进。
- mapping: 映射键值对的缩进。
- sequence: 序列项的缩进。
- offset: 序列项 - 符号后的额外偏移量。
例如，设置映射缩进为2，序列缩进为4，序列偏移量为2：
yaml.indent(mapping=2, sequence=4, offset=2)
这将使得序列项看起来像这样：
- item1
item2而不是：
- item1 - item2
（这里 offset=2 意味着 item1 会在 - 后额外缩进2个空格）。
2.3 保留文档起始标记 ---
如果你的原始YAML文件包含 --- 标记，并且你希望在保存时也保留它，可以设置 explicit_start 属性。
yaml.explicit_start = True
2.4 自定义布尔值表示
默认情况下，ruamel.yaml 会将Python的 True 和 False 序列化为小写的 true 和 false。如果你需要保留原始文件中的 True 或 False（例如，首字母大写），可以通过 boolean_representation 属性进行自定义。
这个属性接受一个包含两个字符串的列表，分别代表 False 和 True 的输出形式。
yaml.boolean_representation = ['False', 'True']
这将确保Python的 True 值被序列化为 True，False 值为 False。
2.5 保留字符串引号
这是最常遇到的格式丢失问题之一。ruamel.yaml 提供了 preserve_quotes 属性来解决这个问题。当设置为 True 时，它会尝试保留原始文件中字符串标量的引号样式（单引号、双引号或无引号）。
yaml.preserve_quotes = True
重要提示：ruamel.yaml 在内部会跟踪每个标量值的原始引号样式。当你加载YAML后，即使Python数据结构中没有引号的概念，ruamel.yaml 也能在保存时智能地还原它们。尝试通过在Python字符串值中手动添加引号（如 value = f"'{value}'"）来强制输出引号是无效的，因为这会将引号视为字符串内容的一部分，而非YAML的语法结构。
3. 完整示例代码
下面是一个完整的示例，演示了如何将上述配置应用到实际的YAML处理流程中。
假设我们有以下YAML字符串作为输入：
import sys
import ruamel.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()
yaml.indent(mapping=2, sequence=4, offset=2) # 设置缩进
yaml.explicit_start = True # 保留文档起始标记
yaml.boolean_representation = ['False', 'True'] # 自定义布尔值输出
yaml.preserve_quotes = True # 保留字符串引号
# 加载YAML数据
data = yaml.load(yaml_str)
# (此处可以对data进行修改，例如添加新的键值对)
# data['preferences']['new_setting'] = 'some_value'
# 将修改后的数据倾倒回标准输出（或文件）
yaml.dump(data, sys.stdout)运行上述代码，你将得到与原始输入几乎完全一致的输出，包括所有注释、字符串引号、布尔值大小写和文档起始标记：
---
# *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
#################################################################4. 注意事项与最佳实践
- 理解YAML数据模型：YAML的引号、布尔值大小写等是其序列化格式的一部分，而不是Python数据类型的一部分。ruamel.yaml 的强大之处在于它在解析时能够捕获这些格式信息，并在序列化时重新应用。
- 适用场景：当处理配置文件、基础设施即代码（IaC）定义等对格式一致性有高要求的场景时，ruamel.yaml 的往返保留功能尤为重要。它有助于减少不必要的版本控制系统差异，并保持文件的可读性和可维护性。
- 注释保留：ruamel.yaml 默认会保留注释。当你加载数据后，对数据结构的修改通常不会影响到未修改部分的注释。
- 清理不一致的输入：虽然 ruamel.yaml 提供了强大的保留功能，但如果你的原始YAML文件本身存在大量格式不一致或不规范之处，有时进行一次性的“清理”并接受新的统一格式可能更为实际和高效。
- 性能考量：由于 ruamel.yaml 需要跟踪更多的格式信息，其性能可能略低于纯粹的数据解析库（如PyYAML的 safe_load），但在大多数配置文件处理场景下，这种差异可以忽略不计。
总结
ruamel.yaml 提供了一套全面的机制来确保在Python中处理YAML文件时，能够最大限度地保留其原始格式。通过合理配置 explicit_start、preserve_quotes、boolean_representation 和 indent 等属性，开发者可以实现对YAML输出的精细控制，从而满足对格式一致性有严格要求的应用场景。掌握这些技巧，将使你在处理复杂YAML文件时更加得心应手。
