V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
推荐学习书目
Learn Python the Hard Way
Python Sites
PyPI - Python Package Index
http://diveintopython.org/toc/index.html
Pocoo
值得关注的项目
PyPy
Celery
Jinja2
Read the Docs
gevent
pyenv
virtualenv
Stackless Python
Beautiful Soup
结巴中文分词
Green Unicorn
Sentry
Shovel
Pyflakes
pytest
Python 编程
pep8 Checker
Styles
PEP 8
Google Python Style Guide
Code Style from The Hitchhiker's Guide
reorx
V2EX  ›  Python

PyYAML 使用技巧分享

  •  1
     
  •   reorx ·
    reorx · 2022-05-15 21:25:09 +08:00 · 2636 次点击
    这是一个创建于 683 天前的主题,其中的信息可能已经有所发展或是发生改变。

    原文: https://reorx.com/blog/python-yaml-tips/

    收集了一些平时在 Python 下使用 PyYAML 的技巧和代码片段,并介绍几个相关的库。

    总是使用 safe_load/safe_dump

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

    为了确保应用程序的安全性,尽量在任何情况下使用 yaml.safe_loadyaml.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
    

    这并不是很好的格式,根据 AnsibleHomeAssistant 等 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.dumpDumper 关键字参数。

    >>> 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 仍然是我心中最好的配置语言。希望这篇文章所介绍的技巧能够帮助你避免问题,获得更好的开发和使用体验。

    12 条回复    2022-05-29 23:21:13 +08:00
    BBCCBB
        1
    BBCCBB  
       2022-05-15 22:30:55 +08:00
    楼主你觉得 toml 咋样?
    reorx
        2
    reorx  
    OP
       2022-05-15 22:51:13 +08:00
    @BBCCBB 我一直都不是很喜欢 TOML ,它看起来像一个高级版 INI ,但又像 YAML 那样提供了过多的功能和用法选择。在让事情变复杂这点,它和 YAML 可以说是兄弟俩了。语法方面,TOML 提倡使用缩进,但这个缩进其实没有实际的语法意义,你会看到几乎每个人的 TOML 写法都不一样。YAML 虽然也有一定的宽容度但还是遵循缩进的。

    TOML 另一个我不喜欢的地方是重复,如果要表达的数据结构层级超过 2 ,你会发现自己在不停地重复 `[[level1.level2.]]`,这就回到了第一个问题,既然你学 INI 提倡平铺,为啥我不直接用 INI 呢?

    最关键的一点是,配置语言起到的是定义和沟通的作用,本就不该过度灵活,有的时候限制越多反而越好。类比序列化协议中的 protobuf ,你会发现严格的写法、通用的数据类型才是它长盛不衰的根本。

    StrictYAML 的作者有偏关于 TOML 的文章,可以看看 https://hitchdev.com/strictyaml/why-not/toml/ , 需要声明的是,我们的看法都非常 opinionated.
    Buges
        3
    Buges  
       2022-05-16 02:29:10 +08:00 via Android
    @reorx toml 很符合你说的严格、规范啊,本来就是规范化的 INI 。至于重复你想想它的设计目标就是配置文件,和 json 不一样。
    BBCCBB
        4
    BBCCBB  
       2022-05-16 12:48:58 +08:00
    BBCCBB
        5
    BBCCBB  
       2022-05-16 12:49:24 +08:00
    感觉都是有利有弊
    reorx
        6
    reorx  
    OP
       2022-05-16 13:29:48 +08:00 via iPhone
    @Buges 主要还是觉得写法很反直觉,不符合我的个人审美,所以才想把 YAML 用的严格、规范一些
    xiaket
        7
    xiaket  
       2022-05-16 13:39:46 +08:00
    看过 PyYAML 的代码, 非常不喜欢, 所以连带着也对 yaml 没啥好感(虽然这么些年一直用过来了). 现在 toml 支持终于进官方库了, 所以后面个人项目肯定会能切就切.
    reorx
        8
    reorx  
    OP
       2022-05-16 17:54:26 +08:00
    @xiaket PyYAML 代码和文档都非常💩,TOML 进官方库应该是 poetry 推动 pyproject.toml 有关,挺好的。层级不多的简单场景下,TOML 用着就很自然。越是复杂的东西越倾向于用 YAML ,最早有 Ansible ,这些年过去不那么流行了,结果 GitLab 和 GitHub 的 CI 配置接下了 YAML 编程的接力棒…
    frostming
        9
    frostming  
       2022-05-17 15:39:32 +08:00
    当我看到 oyaml 只有 53 行代码时候直接 excited 了,点进去一看。。。我就说 yaml 这种怪物,怎么能 53 行代码呢。
    reorx
        10
    reorx  
    OP
       2022-05-17 20:04:00 +08:00 via iPhone
    @frostming 感觉我描述的不太准确,应该说 oyaml 是 PyYAML 的 thin wrapper (中文又犯难了)
    StarryOvO
        11
    StarryOvO  
       2022-05-29 23:12:44 +08:00
    原来 pyyaml 的 dump 连支持缩进都这么麻烦吗....我还刚把项目的配置文件从 json 换成 yaml
    reorx
        12
    reorx  
    OP
       2022-05-29 23:21:13 +08:00
    @StarryOvO 正常的缩进还是有的,就是对 list 的缩进比我习惯的要少一层。其实最可怕的是这个抄来的 IndentDumper 我完全不知道它的工作原理
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   946 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 28ms · UTC 21:23 · PVG 05:23 · LAX 14:23 · JFK 17:23
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.