本文旨在指导读者如何利用 `ruamel.yaml` 库在 python 中处理 yaml 文件时，精确保留原始的格式细节，包括字符串的引号、布尔值的特定大小写以及文档起始符等。通过配置 `ruamel.yaml.yaml` 实例的 `preserve_quotes`、`explicit_start`、`indent` 和 `boolean_representation` 等属性，可以实现对 yaml 文件内容进行修改后，依然保持其原始视觉风格的往返保留，这对于维护配置文件的一致性至关重要。
在 Python 中处理 YAML 文件时，我们常常需要加载、修改并重新保存文件。然而，标准的 YAML 库在倾倒（dump）数据时，往往会“规范化”其输出，导致原始文件中的一些格式细节丢失，例如字符串周围的引号、布尔值的特定大小写（如 True 变为 true），甚至是文档起始符 —。这对于需要严格保持文件格式一致性的场景（例如版本控制下的配置文件）来说，是一个不小的挑战。ruamel.yaml 库正是为了解决这一问题而生，它提供了强大的往返保留（round-trip preservation）能力。
理解 YAML 格式保留的挑战
YAML 是一种人类可读的数据序列化标准。当 YAML 内容被解析成 Python 对象（如字典和列表）时，诸如字符串是否带引号、布尔值使用 True 还是 true 这样的细节，通常被视为数据的表示形式，而非数据本身。因此，在将 Python 对象重新倾倒回 YAML 格式时，默认行为是采用库认为最简洁或标准的表示方式。例如：
字符串 ‘John Doe’ 和 John Doe 在解析后都成为 Python 字符串 “John Doe”。倾倒时，如果字符串内容不包含特殊字符，库通常会省略引号。布尔值 True 和 true 都解析为 Python 布尔值 True。倾倒时，通常统一输出为小写的 true。文档起始符 — 在没有其他指令时，常常被认为是可选的，倾倒时可能被省略。
这些“优化”虽然在数据层面无害，但在视觉和格式层面却可能导致与原始文件不一致，从而引发不必要的版本控制差异或不符合项目规范的问题。
ruamel.yaml 的往返保留机制
ruamel.yaml 的设计目标之一就是实现尽可能完整的往返保留。它在加载 YAML 文件时，会尽可能多地捕获原始格式信息，包括注释、空白行、缩进风格、字符串引号类型等，并在倾倒时尝试重现这些细节。要实现精确的格式保留，我们需要在 ruamel.yaml.YAML() 实例上进行一些特定的配置。
核心配置项详解
以下是 ruamel.yaml 中用于控制格式保留的关键配置项：
1. 保留字符串引号 (preserve_quotes)
此属性用于指示 ruamel.yaml 在倾倒字符串时，是否应保留加载时检测到的原始引号风格（单引号或双引号）。
用法: yaml.preserve_quotes = True效果: 如果原始 YAML 中 ‘John Doe’ 带有单引号，倾倒时仍会是 ‘John Doe’；如果 name: “Alice” 带有双引号，倾倒时仍会是 “Alice”。
2. 明确文档起始符 (explicit_start)
YAML 文件可以包含一个可选的 — 作为文档的起始标记。默认情况下，如果 YAML 文件不包含任何指令，ruamel.yaml 在倾倒时可能会省略它。设置此属性可以强制包含 —。
用法: yaml.explicit_start = True效果: 无论原始文件是否有 —，倾倒的 YAML 文件都会以 — 开头。
3. 自定义缩进 (indent)
ruamel.yaml 允许我们精确控制映射（mapping）和序列（sequence）的缩进级别，以及序列项的额外偏移量。
用法: yaml.indent(mapping=N, sequence=M, offset=O)mapping: 映射键值对的缩进级别（默认为 2）。sequence: 序列项的缩进级别（默认为 4）。offset: 序列项前面 – 符号的额外偏移量（默认为 2）。效果: 确保输出的 YAML 具有与原始文件或项目规范一致的缩进风格。例如，yaml.indent(mapping=2, sequence=4, offset=2) 将使得映射键值对缩进 2 个空格，序列项缩进 4 个空格，且 – 符号相对于其父级缩进 2 个空格。
4. 布尔值表示 (boolean_representation)
ruamel.yaml 默认会将布尔值倾倒为小写的 true 或 false。通过 boolean_representation 属性，我们可以自定义布尔值的字符串表示形式。
用法: yaml.boolean_representation = [‘False’, ‘True’]这是一个包含两个字符串的列表，分别对应 Python 的 False 和 True 在 YAML 中的输出形式。效果: 如果原始 YAML 中 enable_vpc_svc_ctrls: True 使用大写 True，通过此配置，倾倒时也能保持为 True。
实战示例
下面是一个完整的 Python 代码示例，展示如何结合上述配置项，加载一个 YAML 字符串，进行简单的处理（例如，即使不修改数据，也会触发倾倒），并将其以保留原始格式的方式倾倒到标准输出。
import sysimport 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 #################################################################"""# 实例化 ruamel.yaml.YAML 对象yaml = ruamel.yaml.YAML()# 配置缩进风格# mapping=2: 映射键值对缩进2个空格# sequence=4: 序列项缩进4个空格# offset=2: 序列项的 '-' 符号相对于其父级缩进2个空格yaml.indent(mapping=2, sequence=4, offset=2)# 强制保留文档起始符 '---'yaml.explicit_start = True# 自定义布尔值的字符串表示，使其与原始文件保持一致yaml.boolean_representation = ['False', 'True']# 启用字符串引号的保留yaml.preserve_quotes = True# 加载 YAML 字符串到 Python 对象data = yaml.load(yaml_str)# (此处可以进行数据修改，例如 data['preferences']['new_key'] = 'new_value')# 为了演示格式保留，我们在此不进行修改，直接倾倒# 将 Python 对象倾倒回 YAML 格式并输出到标准输出yaml.dump(data, sys.stdout)
运行上述代码，将得到与原始 yaml_str 几乎完全一致的输出，包括字符串的单引号、enable_vpc_svc_ctrls: True 的大写 True 以及文档起始符 —。
注意事项与最佳实践
一致性优先: ruamel.yaml 旨在提供极高的格式保留能力，但这并不意味着它能“修复”不一致的输入。如果原始 YAML 文件本身存在缩进混乱、引号使用不规范等问题，ruamel.yaml 会尽力保留这些“不规范”。因此，最佳实践是在可能的情况下，首先确保输入的 YAML 文件是规范和一致的。boolean_representation 的作用: boolean_representation 属性只影响布尔值在倾倒时的字符串表示。它不会改变 Python 对象中布尔值的实际类型（它们仍然是 True 或 False）。注释和空白行: ruamel.yaml 还能保留注释和空白行，这在处理配置文件时尤为重要，因为它能确保修改后的文件不会丢失重要的上下文信息。性能考量: ruamel.yaml 为了实现往返保留，会比其他一些更简单的 YAML 库（如 PyYAML）消耗更多的内存和处理时间。对于非常大的文件或对性能有极致要求的场景，需要权衡其格式保留的优势与潜在的性能开销。官方文档: ruamel.yaml 拥有非常详尽的官方文档。当遇到更复杂的格式保留需求时，建议查阅官方文档以获取更高级的配置和功能。
总结
ruamel.yaml 是 Python 中处理 YAML 文件并需要精确保留其原始格式的强大工具。通过灵活配置 preserve_quotes、explicit_start、indent 和 boolean_representation 等属性，开发者可以确保在加载、修改和倾倒 YAML 文件后，其视觉风格和结构细节依然保持不变。这对于维护配置文件、自动化部署脚本以及任何对文件格式有严格要求的场景都至关重要，极大地简化了版本控制和协作过程中的潜在冲突。
以上就是如何使用 ruamel.yaml 精确保留 YAML 格式和风格的详细内容，更多请关注创想鸟其它相关文章！
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 chuangxiangniao@163.com 举报，一经查实，本站将立刻删除。
发布者：程序猿，转转请注明出处：https://www.chuangxiangniao.com/p/1378711.html
微信扫一扫 
支付宝扫一扫 
