本文详解如何在使用 ruamel.yaml 进行 YAML 加载与转储时，真正保留原始文件中的换行与缩进结构（如已手动折行的 flow scalar），而非依赖 width 参数的全局控制——关键在于理解 YAML 规范对流式标量（flow scalars）的折叠行为，并正确选用块标量（block scalars）语法。
本文详解如何在使用 `ruamel.yaml` 进行 yaml 加载与转储时，**真正保留原始文件中的换行与缩进结构**（如已手动折行的 flow scalars），而非依赖 `width` 参数的全局控制——关键在于理解 yaml 规范对流式标量（flow scalars）的折叠行为，并正确选用块标量（block scalars）语法。
在 YAML 处理中，一个常见却易被误解的需求是：对已有 YAML 文件执行“无损 round-trip”更新（例如仅修改某个字段值），同时严格保持原有格式，包括已手动折行的长字符串位置与缩进。然而，直接使用 ruamel.yaml 的 yaml.width = 999 并不能解决所有场景——它虽能防止自动折行，却会抹平原本存在的合法折行（如 description: This is... 被强制展成单行），导致 diff 噪声剧增。
根本原因在于 YAML 1.2 规范明确要求：所有流式标量（flow scalars，即用 : 后直接跟值的普通键值对）中的换行符在解析时会被自动“折叠”（folded）为单个空格（参见 YAML Spec §2.17–2.18）。这意味着，一旦你以 description: This is a long line that has been\n wrapped. 形式书写，ruamel.yaml.load() 在解析阶段就已将 \n 替换为 ' '，原始换行信息永久丢失。后续 dump() 只能基于已扁平化的字符串重新排版，自然无法还原。
✅ 正确解法：显式声明块标量（block scalars）
块标量（|、> 等）是 YAML 中唯一能保留原始换行语义的标量类型。它们在加载时不会折叠行，而是将换行作为内容的一部分保留下来，因此 dump 时可原样输出。
以下对比演示核心实践：
import ruamel.yaml import sys yaml = ruamel.yaml.YAML() yaml.preserve_quotes = True # 可选：保留引号风格 yaml.indent(mapping=2, sequence=4, offset=2) # 可选：统一缩进风格 # ✅ 正确输入：使用块字面量（|）或块折叠（>-）显式保留换行 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 # 仅修改目标字段 yaml.dump(data, sys.stdout)
输出将严格保持原始 description 的折行结构：
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
? 关键语法说明：
- |-（块字面量，strip trailing newlines）：最推荐。保留所有内部换行与空格，末尾换行被移除，语义最贴近原始意图。
- >-（块折叠，strip trailing newlines）：将连续空行折叠为单个 \n，段落内多空格/制表符被压缩为空格，适合纯文本描述（如 README 片段）。
- | / >（不带 -）：末尾会额外保留一个空行，通常非必需。
⚠️ 注意事项：
- 无法挽救已用 flow scalar 编写的旧文件：若原始 YAML 未使用 | 或 >，则换行信息在首次 load() 时已不可逆丢失。此时需人工或脚本预处理，将关键长字段转换为块标量。
- yaml.width 仅控制自动折行阈值，不恢复丢失的换行元数据，切勿将其视为“保留格式”的万能开关。
- 若必须兼容旧格式且无法修改源 YAML，可考虑 ruamel.yaml.comments.CommentedMap 配合自定义 CommentedSeq 手动注入 CommentedBase 的 ca（comment attribute）来模拟换行，但复杂度高、维护成本大，不推荐。
总结：保留 YAML 行包裹的本质，是让解析器“知道你想保留它”。通过在源头使用 |- 块标量语法，你赋予了 YAML 解析器明确的语义指令——这比任何 dump 时的宽度调优都更底层、更可靠。在设计配置文件规范或编写生成工具时，应主动采用块标量处理可能超长的字符串字段，为未来的可维护性与 diff 友好性奠定基础。
