本文详解如何使用 ruamel.yaml 精确保留输入 yaml 中的单引号，确保含特殊字符（如冒号、逗号、括号）的注解值在序列化时不被自动去引号，满足 kubernetes 等场景对字符串格式的严格要求。
本文详解如何使用 ruamel.yaml 精确保留输入 yaml 中的单引号，确保含特殊字符（如冒号、逗号、括号）的注解值在序列化时不被自动去引号，满足 kubernetes 等场景对字符串格式的严格要求。
在处理 Kubernetes 注解（annotations）等 YAML 配置时，常需严格保持原始字符串的引号形式——例如 'server1.test.local:80' 必须输出为带单引号的字面量，而非无引号的 server1.test.local:80（后者在某些 YAML 解析器中可能被误判为浮点数或时间戳）。PyYAML 默认不保留引号信息，因其将 YAML 字符串统一解析为 Python str 对象，丢失了原始表示方式。真正可行的解决方案是改用 ruamel.yaml 并显式使用其类型化字符串类。
✅ 正确做法：使用 SingleQuotedScalarString
ruamel.yaml 提供了 scalarstring.SingleQuotedScalarString 类型，可强制指定某字符串必须以单引号包裹输出，且不受内容影响（即使值为纯字母数字，也会加引号；反之，未包装的字符串则按需省略引号）：
from ruamel.yaml import YAML
from ruamel.yaml.scalarstring import SingleQuotedScalarString
# 构建带引号控制的 annotations 字典
annotations = {
"example.com/catalog-item-20": SingleQuotedScalarString("server1.test.local:80"),
"bnhp.co.il/network-policy-version": "v14.yaml", # 无引号 → 自动省略
"openshift.io/sa.scc.mcs": SingleQuotedScalarString("s0,c107,c49"),
"collectord.io/logs-index": "channel_1",
"collectord.io/logs-override.11-match": "^.*(%SENSITIVE%).*$", # 含特殊符号但未强制引号 → 仍可能被引（取决于风格）
}
# 组装完整 Namespace 结构
data = {
"apiVersion": "v1",
"kind": "Namespace",
"metadata": {
"annotations": annotations
}
}
# 配置输出样式
yaml = YAML()
yaml.indent(mapping=4, sequence=4, offset=2)
yaml.default_flow_style = False
# 写入文件（引号将严格按 SingleQuotedScalarString 指定方式保留）
with open("namespace.yaml", "w") as f:
yaml.dump(data, f)
⚠️ 注意事项：
preserve_quotes=True仅对 已加载的 YAML 数据 生效（即从文件读取后保留原始引号），不适用于新创建的 Python 字符串。因此必须主动包装为SingleQuotedScalarString。- 若需双引号，可用
DoubleQuotedScalarString；若需保留原始换行/缩进，可用LiteralScalarString。- 输出中的
^.*(%SENSITIVE%).*$未加引号仍合法——YAML 规范允许不含空格/冒号/逗号等危险字符的字符串省略引号。如需强制所有值都加引号，可统一包装，但通常不推荐（增加冗余且降低可读性）。
? 补充：解析原始 YAML 并智能还原引号
若需从原始 YAML 文件中提取键值并自动识别哪些值原本带引号，可结合 ruamel.yaml 的事件解析器或自定义构造器实现。但本例中输入格式为非标准多行字符串（含 1. 编号），建议先预处理清洗（如正则提取 key=value 并判断 value 是否被单引号包围），再逐项构建 SingleQuotedScalarString 实例。
最终生成的 namespace.yaml 将严格匹配目标格式，确保 Kubernetes API Server 或其他工具能正确解析所有注解值，避免因引号缺失导致的解析歧义或策略失效。
