ruamel.yaml 默认按 80 字符宽度折行，导致 name: 等长值被拆分为两行（如 name:\n xxx）；只需设置 yaml.width = 较大值（如 1024） 即可强制单行输出，保持 YAML 可读性与结构一致性。
ruamel.yaml 默认按 80 字符宽度折行，导致 `name:` 等长值被拆分为两行（如 `name:\n xxx`）；只需设置 `yaml.width = 较大值（如 1024）` 即可强制单行输出，保持 yaml 可读性与结构一致性。
在使用 ruamel.yaml 序列化 YAML 数据时，你可能会遇到一个常见但易被忽视的问题：原本紧凑的键值对（如 name: <long-digest-image>）被意外拆分成两行，形如：
- name:
quay.io/modh/cuda-notebooks@sha256:00c53599f5085beedd0debb062652a1856b19921ccf59bd76134471d24c3fa7d这并非语法错误，而是 ruamel.yaml 的默认排版策略所致：它内置了 width 参数（默认为 80），用于控制每行最大字符数。当某个标量值（如镜像 digest）长度超过该阈值（或结合缩进后超出），解析器会将其“悬挂”到下一行，并以缩进形式对齐，以维持视觉整洁——但在配置文件（尤其是 OpenShift ImageSetConfiguration 这类声明式清单）中，这种格式不仅冗余，还显著降低可读性与 diff 友好性。
✅ 解决方案非常简洁：显式增大 yaml.width
from ruamel.yaml import YAML yaml = YAML() yaml.width = 1024 # 关键：禁用因宽度限制导致的自动换行 # yaml.preserve_quotes = True # 可选：保留原始引号（若需） # yaml.default_flow_style = False # 默认即为 block style，通常无需修改 # 加载并重新 dump doc = """...""" # 你的原始 YAML 字符串 data = yaml.load(doc) yaml.dump(data, stdout) # 输出将全部保持单行 key-value
⚠️ 注意事项：
- yaml.width 影响所有行宽控制逻辑（包括列表项、映射键值、注释位置等），设为 1024 或 float('inf')（不推荐）可彻底规避折行，但请确保终端/编辑器能正常渲染超长行；
- 此设置不会改变语义，仅影响输出格式，生成的 YAML 仍完全合法且兼容所有 YAML 1.2 解析器；
- 若你还希望进一步精简（如压缩空行、禁用锚点/别名），可补充：
yaml.indent(mapping=2, sequence=4, offset=2) yaml.compact(seq_seq=False, seq_map=False) # 控制序列内嵌套的紧凑程度
- 切勿混淆 yaml.width 与 yaml.indent() 或 yaml.default_flow_style：后者控制缩进层级和流式/块式风格，不解决本问题。
? 总结：
ruamel.yaml 的智能换行本意是提升人类可读性，但在处理大量长哈希值（如 OCI 镜像 digest）时反而适得其反。通过一行 yaml.width = 1024，即可回归清晰、扁平、易于版本控制的 YAML 格式——这是运维自动化与 GitOps 实践中的关键细节优化。
