实用的 PyYAML 使用技巧

Posted 2023-03-21

AML 是一个被广泛使用的数据序列化和配置语言，作为一个开发者，总是不免和它打交道。但处理 YAML 文档，尤其是使用 PyYAML 的过程总是非常痛苦。

这篇文章分享我在 Python 下使用 PyYAML 的技巧和代码片段，并介绍几个相关的库。

注意：本文中的代码仅保证在 Python 3 下正常工作

总是使用 safe_load/safe_dump

PyYAML 的 load 函数可以构造任意 Python 对象（Pickle 协议），这意味着一次 load 可能导致任意 Python 函数被执行。

为了确保应用程序的安全性，尽量在任何情况下使用 yaml.safe_load 和 yaml.safe_dump。

保留字段顺序

Python 3.7+ 中，dict keys 具备保留插入顺序的特性，所以通过 yaml.safe_load 得到的 dict，其 keys 顺序会与原始文件保持一致。

>>> import yaml
>>> text = """---
... c: 1
... b: 1
... d: 1
... a: 1
... """
>>> d = yaml.safe_load(text)
>>> d
c: 1, b: 1, d: 1, a: 1
>>> list(d)
[c, b, d, a]

当把 dict 导出为 YAML 字符串时，为 yaml.safe_dump 传递 sort_keys=False 来保留 keys 的顺序。

>>> print(yaml.safe_dump(d))
a: 1
b: 1
c: 1
d: 1
>>> d[e] = 1
>>> print(yaml.safe_dump(d, sort_keys=False))
c: 1
b: 1
d: 1
a: 1
e: 1

如果 Python 版本较低，或者你想确保代码能在更广泛的环境下工作，你可以使用 oyaml 库来代替 PyYAML 的 yaml 包。

>>> import oyaml as yaml
>>> d = yaml.safe_load(text)
>>> d
OrderedDict([(c, 1), (b, 1), (d, 1), (a, 1)])
>>> d[e] = 1
>>> print(yaml.safe_dump(d, sort_keys=False))
c: 1
b: 1
d: 1
a: 1
e: 1

优化列表项的缩进

默认情况下，PyYAML 输出的列表缩进与其父元素一致。

>>> d = a: [1, 2, 3]
>>> print(yaml.safe_dump(d))
a:
- 1
- 2
- 3

这并不是很好的格式，根据 Ansible 和 HomeAssistant 等 YAML 书写规范，列表项应该缩进 2 空格。

这种格式也会对导致列表项不会被如 VSCode 等编辑器识别，进而无法使用编辑器的折叠功能。

要解决这个问题，使用如下代码片段，在代码中定义 IndentDumper class:

class IndentDumper(yaml.Dumper):
    def increase_indent(self, flow=False, indentless=False):
        return super(IndentDumper, self).increase_indent(flow, False)

然后将它传递给 yaml.dump 的 Dumper 关键字参数。

>>> print(yaml.dump(d, Dumper=IndentDumper))
a:
  - 1
  - 2
  - 3

注意，yaml.safe_dump 由于有自己的 Dumper class，传递此参数会造成冲突。

输出可读的 UTF-8 字符

默认情况下，PyYAML 假设你希望输出的结果里只有 ASCII 字符。

>>> d = a: 你好
>>> print(yaml.safe_dump(d))
a: "\\u4F60\\u597D"

这会让输出结果非常难以阅读。

在 UTF-8 足够普及的今天，直接输出 UTF-8 字符是非常安全的。因此我们可以将 allow_unicode=True 传入 yaml.safe_dump 使 PyYAML 将 Unicode 转换成 UTF-8 字符串。

>>> print(yaml.safe_dump(d, allow_unicode=True))
a: 你好

一些 YAML 相关的库

oyaml

Link: https://github.com/wimglenn/oyaml

正如上文中提到的，oyaml 是 yaml 包的替换品，使 dict keys 的顺序在 dump/load 的时候得以保留。

oyaml 是一个单文件库，只有 53 行代码，因此使用起来非常灵活，你可以直接把它的代码复制到自己的项目中，然后根据自己的需求进行修改。

strictyaml

Link: https://github.com/crdoconnor/strictyaml

有的人说 YAML 过于复杂和灵活，不是一个好的配置语言。但我认为这不是 YAML 的问题，而是使用方式的问题。如果我们限制程序只使用 YAML 的部分功能，YAML 其实可以变得像它设计的那般好用。

这就是 StrictYAML 的设计意图，它是一个类型安全的 YAML 解析器，实现了 YAML 规范说明中的一个子集 。

如果你对 YAML 的输入输出有较强的安全考虑，建议使用 StrictYAML 代替 PyYAML。

顺带一提的是，StrictYAML 的文档站有很多关于设计细节和配置语言思考的文章，非常值得一看。

ruamel.yaml

Link: https://yaml.readthedocs.io/en/latest/overview.html

ruamel.yaml 是 PyYAML 的一个分叉，于 2009 年发布并持续维护至今。

ruamel.yaml 的文档里详细说明了它和 PyYAML 的差异。总体来说，ruamel.yaml 专注在 YAML 1.2 上，对一些语法进行了优化。

ruamel.yaml 最令我感兴趣的特性是输入输出的 “round-trip”，可以最大程度地保留输入源的原始格式。官方文档中的定义是这样的：

A round-trip is a YAML load-modify-save sequence and ruamel.yaml tries to preserve, among others:

• comments
• block style and key ordering are kept, so you can diff the round-tripped source
• flow style sequences ( ‘a: b, c, d’) (based on request and test by Anthony Sottile)
• anchor names that are hand-crafted (i.e. not of the formidNNN)
• merges in dictionaries are preserved

如果你有尽可能保留原始格式的需求，建议使用 ruamel.yaml 代替 PyYAML。

在使用中我注意到 ruamel.yaml 的 safe load 方法 (YAML(typ=safe).load) 与 PyYAML 有些不同，它无法解析 flow style 的集合定义 (如 a: "foo": "bar")，这点没有在文档中提及，使用时须多加注意。

总结

YAML 有它好的地方和坏的地方。它易于阅读，初期的学习曲线非常平缓。但 YAML 的规范说明非常复杂，不仅造成了使用中的混乱，也使不同语言的实现在很多细微的地方难以保持一致。

尽管有这些小毛病，YAML 仍然是我心中最好的配置语言。希望这篇文章所介绍的技巧能够帮助你避免问题，获得更好的开发和使用体验。

链接：https://reorx.com/blog/python-yaml-tips-zh/

使用 PyYAML 库解析 AWS CloudFormation 模板

【中文标题】使用 PyYAML 库解析 AWS CloudFormation 模板

【英文标题】：Parse an AWS CloudFormation template with the PyYAML library

【发布时间】：2018-11-27 14:12:40

【问题描述】：

我正在使用需要读取 AWS CloudFormation YAML 模板的 PyYAML 库编写自定义 Python 应用程序。

我知道这些模板是有效的 CloudFormation 模板，因为我使用 validate-template 对其进行了测试：

▶ aws cloudformation validate-template --template-body file://cloudformation.yml

但是，当我尝试使用 PyYAML 库读取它们时，我收到如下错误：

yaml.scanner.ScannerError: 此处不允许映射值

和

无法确定标签“!Sub”的构造函数

和其他人。

举个例子，我试试这个 AWS 示例模板：

▶ curl -s \
    https://raw.githubusercontent.com/awslabs/aws-cloudformation-templates/master/aws/services/CloudFormation/FindInMap_Inside_Sub.yaml \
    -o FindInMap_Inside_Sub.yaml

然后：

▶ python
Python 2.7.15 (default, Nov 27 2018, 21:40:55) 
[GCC 4.2.1 Compatible Apple LLVM 10.0.0 (clang-1000.11.45.5)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import yaml
>>> yaml.load(open('FindInMap_Inside_Sub.yaml'))

这会导致：

yaml.constructor.ConstructorError: could not determine a constructor for the tag '!FindInMap'
  in "FindInMap_Inside_Sub.yaml", line 89, column 45

如何使用 PyYAML 等库或其他库解析 CloudFormation YAML 文件？

【参考方案1】：

可以使用aws-cfn-template-flip 项目附带的cfn_tools 库。

安装库：

▶ pip install cfn_flip

那么在模板中读取的最简单的 Python 可能是：

#!/usr/bin/env python
  
import yaml
from cfn_tools import load_yaml, dump_yaml

text = open('./FindInMap_Inside_Sub.yaml').read()
data = load_yaml(text)

print(dump_yaml(data))

这个库并没有真正记录在案，但其中也有各种方法可以自定义输出的格式，值得探索。

【参考方案2】：

Alex's answer 遇到了一些问题，因为它会自动将我的 CF 模板转换为长格式。因此，任何!Ref Thing 调用都被转换为字典映射。

如果您想匹配 input.template 文件的原始输入，请使用：

from cfn_tools import load_yaml
import cfn_flip.yaml_dumper
import yaml


with open('input.template') as f:
    raw = f.read()
    data_dict = load_yaml(raw)

with open('output.template', 'w') as f:
    dumper = cfn_flip.yaml_dumper.get_dumper(clean_up=False, long_form=False)
    raw = yaml.dump(
        data_dict,
        Dumper=dumper,
        default_flow_style=False,
        allow_unicode=True
    )
    f.write(raw)

您还可以将clean_up=False 更改为True 以执行一些智能格式化，这在我的情况下效果很好。

我在运行 cfn cli 工具并在我的模板上看到正确的短格式输出后发现了这一点。然后我用that main file作为参考，按照代码路径走。

【讨论】：

谢谢！你会碰巧知道如何将构造函数的变量保持在同一行吗？例如，即使使用了它，我仍然没有得到我想要的结果：- !FindInMap [PrivateLink, EndPoint, SubnetId1]。相反，我得到- !FindInMap，然后它删除一行并传递其余变量- PrivateLink - EndPoint - SubnetId1

这两件事在功能上应该是等效的@Daniel，在 cloudformation yaml 中，这两种方式都被视为列表。但不，我不知道有什么办法。但我不会费心去调查，因为它只是风格

【参考方案3】：

他们的 aws-cfn-template-flip 项目将 cfn 模板转换为/从 json 和 yaml 是一个很好的起点。 示例查看yaml_loader.py 脚本。 它显示了它是如何添加 yaml 构造函数的。 在底部，您会看到：

CfnYamlLoader.add_constructor(TAG_MAP, construct_mapping)
CfnYamlLoader.add_multi_constructor("!", multi_constructor)

您可能会对那里的construct_mapping 方法感兴趣。从那里，您可以查看代码是如何工作的。

【讨论】：

非常感谢您提供这些信息。我为我的具体问题找到了另一种解决方法，但它们可能会帮助我解决其他自动化问题。

事实上，我真正要做的是找到一个解决方案，让 AWS cfn 模板参数覆盖 AWS Service Catalog 中的无服务器应用程序部署（工件和程序包），通过我使用 aws Management 和 CI 设置的基础设施系统/CD 工具。我最终决定使用 AWS Systems Manager Parameter Store 将基础设施与配置和参数分开。但是我会使用你在另一个阶段指出的这些工具，我打算写一篇关于我所做的事情以及确切遇到的问题的完整文章......

那篇文章在哪里；）？