rtyaml：可往返的YAML

主要作者：Joshua Tauberer https://razor.occams.info

• GitHub: https://github.com/unitedstates/rtyaml
• PyPi: https://pypi.python.org/pypi/rtyaml

此模块是pyyaml的一个包装器，用于读取和写入YAML文件，并进行了一些改进

• 通过保留键的顺序，可以实现YAML文件的往返操作。在Python 3.7+中，只需使用常规的dict。在Python的较早版本中，请使用collections.OrderedDict。
• 为字符串写入YAML设置了更合理的默认值（见下文）。
• 选择了其他合理的默认值，例如使用“安全”的加载/卸载器。
• 当加载YAML时，在流的开头找到的注释块在写回时会保留。

您所说的往返是什么意思？

往返是指您加载一个文件然后将其保存而不做任何更改，您期望磁盘上的字节不会改变。这是不可能使用PyYAML实现的，这使得使用像git这样的版本控制工具处理YAML文件变得困难，因为每次加载和保存文件时，都可能发生重新排列。键的顺序可能会改变，字符串的引号样式可能会改变，注释可能会被移除，等等。

尽管rtyaml不能为所有文件提供往返功能，但它确实在PyYAML上设置了一些合理的默认值，以便更容易实现。例如，如果您使用PyYAML加载此文件

然后将其保存而不做任何更改

import yaml
print(yaml.dump(yaml.load(open('example.yaml'))))

您将得到以下混乱的结果

请注意，注释已经消失，键zz、yy、xx的顺序已经改变，字符串格式不统一，null使用了一个令人困惑的关键词，映射被压缩成单行。

使用 ryaml，您实际上可以得到原始文件！这正是这个库的核心所在。

安装和使用

安装

pip install rtyaml
(or pip3 --- this module works in both Python 2 and Python 3)

使用

import rtyaml

with open("myfile.yaml") as f:
  stuff = rtyaml.load(f)

# ...do things to stuf...

with open("myfile.yaml", "w") as f:
  rtyaml.dump(stuff, f)

与底层的pyyaml库一样，load 接受包含 YAML 或字节数组的字符串，或者一个打开的文件对象（二进制或文本）。此外，dump 的第二个参数是可选的，如果省略，则函数返回 YAML 字符串。

也支持 load_all 和 dump_all，它们使用 YAML 的 --- 文档分隔符加载和保存文档列表。

依赖项

• pyyaml（在 Ubuntu 中，是 python-yaml 或 python3-yaml 软件包）
• libyaml（在 Ubuntu 中，是 libyaml-0-2 软件包，以及安装时仅需要的 libyaml-dev）

详细信息

此库执行以下操作

• 使用原生 libyaml CSafeLoader 和 CDumper，以提高速度并确保操作可靠。
• 保留 dict 中的键的顺序，而不是按字母顺序排序（Python >=3.7）。
• 允许您使用 collections.OrderedDict 与 dump 一起使用，以保留键顺序（在 Python 3.7 之前很有用）。
• 以块模式写入多行字符串（而不是使用带转义字符的引号），根据字符串中行的长度选择字面值或折叠模式。
• 以展开（每行一个）格式写入映射和列表，当输出到版本控制时很方便。
• 修改流字符串引号规则，以便任何由数字组成的字符串都带引号序列化。（默认设置将字符串 "01" 带引号序列化，但字符串 "09" 则不带引号！（你能想出原因吗？））
• None 以波浪号序列化，而不是以 null 序列化，这减少了混淆。
• 如果文件开头有一个块注释（即以 '#' 开头的一行或多行），则如果使用 rtyaml.dump() 写入相同的对象，则将其写回。

对于 Python 3.6 及更早版本

• 加载映射 collections.OrderedDict，以便在稍后使用时将文件中的键顺序保持不变。（在 Python 3.7 中不再需要此功能，因为常规 dict 中现在已保留键顺序。）

对于 Python 2.x 及更早版本

• 写入无怪异 YAML 标签的 Unicode 字符串。它们仅作为字符串出现。输出编码为 UTF-8，非 ASCII 字符以 Unicode 形式出现，无需转义。

用于就地编辑文件的 With-Block 辅助工具

rtyaml.edit 类是一个实用工具类，可用于 with 块，可以使其更容易就地编辑 YAML 文件。例如

with rtyaml.edit("path/to/data.yaml", default={}) as data:  
   data\["hello"\] = "world"

文件以编辑模式打开（"r+" 模式，如果不存在则使用 "w+" 模式，并提供默认值），其内容被解析并返回为 with 块变量中的数据。文件在 with 块执行期间保持打开状态。当 with 块退出时，with 块变量被写入文件作为 YAML，然后关闭文件。

当然，这只适用于文件包含数组或对象（dict），并且不能将新值分配给 with 块变量（这正是 Python with 块的工作方式）。您只能调用其方法，即，您可以编辑列表（追加、弹出、排序等）和字典（获取/设置键），但不能将完全新的列表或字典替换值。

如果没有提供默认参数，或为 None，则文件必须存在。否则，如果文件不存在，则创建文件，with 块变量将使用默认值开始。

如果您想自己打开文件，也可以将流作为第一个参数传递。该流必须支持 seek、truncate 和 close。如果您打开文件，则应使用 "r+" 或 "w+" 模式。

公共领域奉献

该项目已根据 LICENSE 文件中的说明奉献给公共领域。

该项目在美国属于公共领域，通过CC0 1.0全球公共领域奉献声明，全球范围内的工作版权及相关权利均被放弃。http://creativecommons.org/publicdomain/zero/1.0/

该项目所有贡献必须根据CC0奉献声明发布。通过提交拉取请求，您同意遵守此版权利益放弃。