本文详解如何使用 ruamel.yaml 精确保留输入 yaml 中字符串的单引号/双引号状态，解决 pyyaml 默认序列化时丢弃引号导致特殊值（如含冒号、逗号、括号的 annotation 值）被错误解析的问题。
本文详解如何使用 ruamel.yaml 精确保留输入 yaml 中字符串的单引号/双引号状态，解决 pyyaml 默认序列化时丢弃引号导致特殊值（如含冒号、逗号、括号的 annotation 值）被错误解析的问题。
在 Kubernetes 等场景中处理 YAML annotations 时，常需严格保持原始引号格式——例如 'server1.test.local:80' 中的单引号不可省略，否则某些工具（如旧版 kubectl、自定义校验器或非标准 YAML 解析器）可能将 : 误判为映射分隔符，导致解析失败。PyYAML 的 safe_dump 默认不保留引号语义，而 ruamel.yaml 提供了细粒度控制能力，但关键在于：仅设置 preserve_quotes=True 不足以保留新构造字符串的引号；必须显式使用其专用字符串子类。
✅ 正确做法：用 SingleQuotedScalarString 显式标记需加引号的值
ruamel.yaml 提供了 scalarstring 模块中的类型，用于在 Python 对象层面“携带”引号意图：
-
SingleQuotedScalarString(s)→ 强制输出为's' -
DoubleQuotedScalarString(s)→ 强制输出为"s" -
LiteralScalarString(s)→ 强制输出为|或>块样式（适合多行）
以下是一个完整、健壮的处理流程示例，兼容您原始输入格式（带编号和等号的多行字符串）：
import re
from pathlib import Path
import ruamel.yaml
from ruamel.yaml.scalarstring import SingleQuotedScalarString, DoubleQuotedScalarString
# 1. 解析原始 YAML（保留原始引号信息）
yaml = ruamel.yaml.YAML()
yaml.preserve_quotes = True # 仅对已加载的字符串生效
with open('annotations.yaml', 'r') as f:
raw_data = yaml.load(f)
# 2. 提取并结构化 annotations（去除编号、拆分 key=value、识别原始引号）
annotations = {}
for prefix, block in raw_data.items():
# 清理前缀（确保以 / 结尾）
clean_prefix = prefix.rstrip('/') + '/'
# 按行分割（block 是多行字符串）
for line in block.strip().splitlines():
# 匹配 "1. key='value'" 或 "2. key=value"
match = re.match(r'^\s*\d+\.\s+([^=]+)=((?:\'[^\']*\')|(?:"[^"]*")|[^\'"].*)$', line.strip())
if not match:
continue
key, raw_value = match.groups()[0].strip(), match.groups()[1]
# 判断原始是否带引号，并提取无引号内容
if raw_value.startswith(("'", '"')) and raw_value.endswith(("'", '"')):
unquoted = raw_value[1:-1]
# 根据原始引号类型选择子类（此处统一用单引号，也可按需区分）
quoted_value = SingleQuotedScalarString(unquoted)
else:
quoted_value = raw_value # 保持原样（无引号）
full_key = clean_prefix + key
annotations[full_key] = quoted_value
# 3. 构建目标结构并输出（带格式控制）
output_data = {
'apiVersion': 'v1',
'kind': 'Namespace',
'metadata': {
'annotations': annotations
}
}
# 配置输出：缩进、不使用流式风格、强制换行友好
yaml.indent(mapping=4, sequence=4, offset=2)
yaml.default_flow_style = False
yaml.width = 1000 # 防止长值被折行
with open('namespace.yaml', 'w') as f:
yaml.dump(output_data, f)
⚠️ 注意事项与最佳实践
-
preserve_quotes=True仅作用于load()加载的字符串：它不会影响你用str()创建的新字符串。必须用SingleQuotedScalarString等显式包装。 - 避免混合引号逻辑：若原始输入同时含单引号和双引号，可通过正则捕获引号类型，再分别调用对应子类，实现完全保真。
-
Kubernetes 兼容性提醒：YAML 规范中，
server1.test.local:80本身是合法标量（因上下文明确为键值对），加引号纯属防御性需求。若目标平台支持标准 YAML 解析器（如现代 kubectl），可省略引号以提升可读性；仅当对接遗留系统时才强制保留。 -
性能考虑：
ruamel.yaml比 PyYAML 稍重，但其 AST 级别控制能力无可替代。生产环境推荐固定版本（如ruamel.yaml>=0.17.0）。
通过上述方法，您即可精准控制每个 annotation 值的引号行为，确保生成的 YAML 既符合规范，又满足特定工具链的严苛要求。
