本文详解如何利用 ruamel.yaml 的块标量（block scalars）机制，在 round-trip 加载-修改-转储过程中严格保留原始 YAML 文件中已有的手动换行，避免 description 等字段被意外展平或 url 被强制折行。
本文详解如何利用 ruamel.yaml 的块标量（block scalars）机制，在 round-trip 加载-修改-转储过程中严格保留原始 yaml 文件中已有的手动换行，避免 `description` 等字段被意外展平或 `url` 被强制折行。
在使用 ruamel.yaml 进行 YAML 文件的读取、修改与写回（round-trip）时，一个常见且棘手的问题是：原始文件中人为换行的字符串（如 description: This is a long line that has been\n wrapped.）在加载后丢失换行信息，导致 dump 时格式发生不可控变化。例如，原本折叠的多行描述被展平为单行，而本应保持单行的长 URL 却被自动折行——这不仅影响可读性，更会污染 Git diff，违背“最小变更”原则。
根本原因在于 YAML 规范对流式标量（flow scalars） 的定义：根据 YAML 1.2.2 规范 §2.17–2.18 ，所有流式标量（即用双引号、单引号或无引号直接书写的字符串）中的换行符在解析阶段即被“折叠”（folded），视为空格处理。这意味着 ruamel.yaml 在 load() 时已将 \n 和缩进全部丢弃，后续 dump() 仅能依据当前数据结构和全局配置（如 width）重新排版——原始换行信息不可恢复。
因此，真正的解决方案不是调整 yaml.width 或 yaml.preserve_quotes，而是主动采用 YAML 块标量（block scalars）语法，让换行成为语义的一部分，而非被忽略的格式噪声。
✅ 正确做法：使用 |（literal）或 >-（folded, strip）块标量
块标量通过 |（字面量）或 >（折叠）引导符显式声明，其内容中的换行和缩进被完整保留（受修饰符控制）。针对你的用例：
-
若需完全保留原始换行与空格（包括末尾空行），使用 |：
description: | This is a long line that has been wrapped.
-
若希望保留换行但自动去除末尾空白与空行（更贴近自然语言书写习惯），推荐 >-（> 后加 - 表示“strip”）：
description: >- This is a long line that has been wrapped.
✅ >- 是最佳实践：它将多行内容折叠为单个空格连接（规范行为），但关键的是——ruamel.yaml 在加载时会记录该字段的原始块标量形态，并在 dump 时原样复现其换行结构，从而实现 round-trip 保真。
? 实际代码示例
import ruamel.yaml import sys yaml = ruamel.yaml.YAML() yaml.preserve_quotes = True # 可选：保留原始引号风格 # 原始 YAML 使用 >- 块标量（注意：这是关键！） instr = """\ description: >- This is a long line that has been wrapped. url: https://long-url.com/add-more-characters-so-that-it-goes-out-farther-than-the-default-80-cols value: 7 """ data = yaml.load(instr) data['value'] += 1 # 仅修改 value yaml.dump(data, sys.stdout)
输出结果（完全符合预期）：
description: >- This is a long line that has been wrapped. url: https://long-url.com/add-more-characters-so-that-it-goes-out-farther-than-the-default-80-cols value: 8
✅ description 的换行被完美保留；
✅ url 作为普通流式标量，按 width（默认 80）自动控制是否折行，不受 description 影响；
✅ Git diff 仅显示 value: 7 → 8，无格式噪音。
⚠️ 注意事项与最佳实践
- 不要依赖 yaml.width = 999：它虽能防止长 URL 折行，但会强制所有流式标量展平，破坏你刻意设计的 description 换行。
- 块标量必须显式声明：原始 YAML 文件中需人工或工具将需保留换行的字段改为 >- 或 | 格式；ruamel.yaml 无法从普通流式标量中“猜出”你想要换行。
- 兼容性提示：>- 是 YAML 1.2 标准特性，所有现代解析器（包括 Python 的 PyYAML、ruamel.yaml、Kubernetes、Ansible）均支持，无需担心跨平台问题。
- 批量迁移建议：若需改造现有文件，可借助 ruamel.yaml 的 CommentedMap + 自定义 RoundTripConstructor 预处理，或使用正则+AST 工具批量转换关键字段。
总结而言，保留换行的本质是语义升级：从“被忽略的格式”变为“受保护的内容”。通过主动采用 >- 块标量，你赋予了 YAML 解析器明确的保真指令，使 round-trip 操作真正可控、可预测、可审计。
