ruamel.yaml是一个支持注释、序列/映射流样式和映射键顺序的YAML解析器/生成器
项目描述
ruamel.yaml
ruamel.yaml是Python的YAML 1.2加载/保存包。
| 版本 | 0.18.6 |
| 更新 | 2024-02-07 |
| 文档 | https://yaml.readthedocs.io |
| 仓库 | https://sourceforge.net/projects/ruamel-yaml |
| pypi | https://pypi.ac.cn/project/ruamel.yaml |
如公告所述，在0.18.0版本中，旧的PyYAML函数已被弃用。（包括scan、parse、compose、load、emit、serialize、dump及其变体（如_all、safe_、round_trip_等））。如果您在程序停止工作后才阅读到这一信息：很抱歉听到这个消息，但这也意味着您或开发您程序的人没有在警告的情况下进行测试（这是PEP 565中的建议，例如使用pytest时的defaultin）。如果您遇到麻烦，请明确使用
pip install "ruamel.yaml<0.18.0"
或在您的需求中添加相应的内容，以给自己一些时间解决问题。
0.18系列还将至少有一个可能破坏性的更改：现在YAML(typ='unsafe')有一个待弃用的警告，并且可能将在2023年底之前被弃用。如果您只是用它进行序列化，请使用新的YAML(typ='full')，使用默认实例YAML()可以安全地加载该结果，这样您将获得可检查的、带标签的标量，而不是执行的Python函数/类。（您可能需要添加您实际需要的构造函数，但我正在考虑添加一个ruamel.yaml.unsafe包，该包将重新添加typ='unsafe'选项。如有必要，请相应地调整/固定您的依赖项。
似乎存在关于ruamel.yaml的一个CVE，指出由于未经检查的输入，load()函数可能被滥用。load()从来就不是默认函数（在新API出现之前是round_trip_load()）。因此，该CVE的创建者信息不足，可能只是懒惰地假设由于ruamel.yaml是PyYAML（为其存在类似CVE）的衍生品，同样的问题仍然存在，而没有进行检查。因此，CVE一直是不合适的，现在更是如此，因为对函数load()的任何输入调用都将导致程序出错并终止。如果您（必须）关心此类CVE，我的建议是完全停止使用Python，因为pickle.load()可以以相同的方式被滥用，并且与load()一样，仅在文档中注明不安全，而没有开发时的警告。
版本0.17.21是最后一个在Python 3.5和3.6上经过测试以确保正常工作的版本。
版本0.16.13是最后一个在Python 2.7上经过测试以确保正常工作的版本。
对于不想自己将流发送到io.BytesIO/StringIO缓冲区的用户，有两个额外的插件包（ruamel.yaml.bytes和ruamel.yaml.string）。
如果您的包使用ruamel.yaml并且不在PyPI上列出，请给我发一封电子邮件，最好提供一些关于您如何使用该包的信息（或链接到仓库），我将通知您当API的状态足够稳定以进行迁移时。
Overview Installing Optional requirements Basic Usage Load and dump More examples Working with Python classes Dumping Python classes Dataclass Details Indentation of block sequences Inconsistently indented YAML Indenting using `typ="safe"` Positioning ':' in top level mappings, prefixing ':' Document version support Round trip including comments Config file formats Extending Smartening Examples Output of `dump()` as a string Departure from previous API Loading Duplicate keys Dumping a multi-document YAML stream Dumping Controls Transparent usage of new and old API Reason for API change Differences with PyYAML Defaulting to YAML 1.2 support PY2/PY3 reintegration Fixes Testing API Contributing Documentation Code Flake Tox/pytest Typing/mypy Generated files Vulnerabilities
变更日志
0.18.6 (2024-02-07):
- 修复了当字段是集合时数据类加载的问题（由FibroMyAlgebra在StackOverflow上的一个问题发现）
- 修复了使用
from __future__ import annotations延迟类型评估时，加载带有InitVar字段的dataclasses的问题。
0.18.5 (2023-11-03):
- 有迹象表明，依赖项已经固定以使用特定的（测试过的）版本，即使在已到生命周期的Python版本中也仅安装最新版本。
0.18.4 (2023-11-01):
- YAML()实例有一个
doc_infos属性，它是一个累积的DocInfo实例列表（load()一个，对于load_all()每份文档一个）。DocInfo实例包含版本信息（请求的、指令）和标签指令信息。 - 修复了YAML实例的tags属性在加载文档之间没有重置的问题，导致多个文档的标签指令混合。现在只提供在加载后的最新文档上的标签指令信息。这意味着在加载同一实例的文档后必须再次设置dump的标签。（因此，将来将删除tags，以有利于不同的机制）
- 修复了多个文档混合YAML 1.2和YAML 1.1的问题，现在VersionedResolver将重置
- 修复了当下一个标记为Tag时评论消失的问题（仍然不能在标签和节点之前同时有注释和标签之后的注释）
0.18.3 (2023-10-29):
- 修复了在注释之后的第一个项目上出现的多余换行符以及嵌套块序列问题
- 在PyPI的元数据中添加了额外的链接（由Sorin报告，并提供了修复方法）。
0.18.2 (2023-10-24):
- 现在调用已弃用的函数会引发一个带有更详细原始警告信息的
AttributeError。而不是调用sys.exit(1)
0.18.1 (2023-10-24):
- 现在总是显示警告信息。（由Trend Lloyd报告）
0.18.0 (2023-10-23):
- 已弃用以下函数：
scan、parse、compose、load、emit、serialize、dump及其变体（如_all、safe_、round_trip_等）。当然，YAML()实例上的同名methods仍然存在。 YAML(typ='unsafe')现在会发出一个PendingDeprecationWarning。这将变为弃用在0.18系列（可能在大约2023年底之前）中。您可以使用YAML(typ='full')来序列化未注册的Python类/函数。对于加载，如果想要旧的不安全功能，则必须注册您的类/函数。您仍然可以使用（默认的）回环解析器安全地加载任何标记，例如`!!python/name:posix.system`。- 修复了在序列化二进制流时需要'bytes-like object'而不是'str'的问题。这由Vit Zikmund报告、分析和提供修复。
0.17.40 (2023-10-20):
- 现在保留flow风格集合（例如
!!set {a, b, c}）。在加载时指定的任何值都将被删除，包括!!null ""。 - 针对问题484的可能解决方案：包含变体规范
CommonMark的long_description_content_type可能导致在Azure上出现问题。如果可以使用RUAMEL_NO_LONG_DESCRIPTION=1 pip install ruamel.yaml --no-binary :all:从.tar.gz安装，则长描述及其引起问题的类型将不会包含在METADATA中。（由Coury Ditch报告） - 更新了文档中的链接（由David Hoese报告）
- 为内部使用的类添加了一些
__repr__。
0.17.39 (2023-10-19):
- 更新README生成，没有代码更改。
0.17.36 (2023-10-19):
- 修复了问题480，加载的空流式映射的导出失败（由Stéphane Brunner报告）
- 修复了问题482，这是由于DEFAULT_MAPPING_TAG从字符串更改为
Tag()实例而引起的（由yan12125报告） - 更新了文档，以使用mkdocs。
0.17.35 (2023-10-04):
- 支持使用具有
InitVar变量的数据类（需要一些特殊编码才能在相应的实例属性中获取意外的默认值（例如，在这个问题中的使用示例）
0.17.34 (2023-10-03):
- 当使用
typ='safe'时，Python 3.12也加载C版本。 - 对在加载注册数据类之后调用具有该方法的dataclasses的
__post_init__()的初始支持。（最初由nyanpasu64在Stackoverflow上提出，并由Patrick Lehmann作为ticket提出）
@yaml.register_class
@dataclass
class ...
0.17.33 (2023-09-28):
- 向
Emitter类添加了flow_seq_start、flow_seq_end、flow_seq_separator、flow_map_start、flow_map_end、flow_map_separatorclass属性，以便更轻松地影响flow风格输出（基于这个答案，该答案是Huw Walters在StackOverflow上的一个问题）。
0.17.32 (2023-06-17):
- 修复扫描仪陷入无限循环的问题
0.17.31 (2023-05-31):
- 在
ScalarEvent和Node上添加了tag.setter标签，它接受一个Tag实例或一个字符串（由Sorin Sbarnea报告）
0.17.30 (2023-05-30):
- 修复问题467，由于Tag实例不可哈希（由Douglas Raillard报告）
0.17.29 (2023-05-30):
- 将标签属性的内部实现从字符串更改为类，这允许保留原始句柄和后缀。这应该会导致使用带有%TAG指令的文档时结果更好，同时保留标签后缀中的URI转义。
0.17.28 (2023-05-26):
- 修复问题464：以文档结束标记结尾且没有换行的文档无法加载（由Mariusz Rusiniak报告）
0.17.27 (2023-05-25):
- 修复将内联映射作为合并键值的问题（由Sirish在StackOverflow上报告）
- 修复问题468，在
CommentedMap上访问合并属性后插入错误（由Bastien gerard报告） - 修复问题461，在同一个
CommentedMap键上pop + insert引发错误（由John Thorvald Wodder II报告）
0.17.26 (2023-05-09):
- 修复问题459的边缘笼中的错误
0.17.25 (2023-05-09):
- 修复在转储带有太多反斜杠的包装字符串时的回归（问题459，由Lele Gaifax报告）
0.17.24 (2023-05-06):
- 重写
CommentedMap.insert()。如果您在要插入的映射的YAML文档中有一个合并键，则位置值应该是您查看YAML输入时的值。这修复了问题453，其中合并映射的其他键会在插入后显示（由Alex Miller报告）。它还修复了调用.insert()导致合并键移动到第一个键（如果不是第一个键）的情况，并且现在还可以在合并键之前插入一个键（即使它是映射中的第一个键）。 - 修复（包括纯Python实现和默认值）问题447。（由Jack Cherng报告，并由brent在StackOverflow上提出）
0.17.23 (2023-05-05):
- 修复问题458，以超过宽度的单词开头的纯标量错误。（由Kyle Larose报告）
- 修复
.update()不再正确处理关键字参数（由John Lin在StackOverflow上报告） - 修复问题454：引号中的高Unicode（表情符号）始终转义（由Michal Čihař基于StackOverflow上的一个问题报告）
- 修复发射器保守地在内联引号字符串中插入额外反斜杠的问题（由thebenman在StackOverflow上报告）
0.17.22 (2023-05-02):
- 修复问题449，第二个感叹号被URL编码（由John Stark报告并修复了提供的PR）
- 修复问题，当缩进不等于2且字面量标量有空的第一行时（由wrdis在StackOverflow上报告）
- 更新了CommentedMap的
__repr__，因为Python的dict是排序的，所以不再需要ordereddict(list-of-tuples) - 合并MR 4，处理YAML 1.1中的八进制整数（由Jacob Floyd提供）
- 修复加载
!!float 42（由Eric在Stack overflow上报告） - 现在在
CommentedKeySeq和CommentedKeyMap上设置行号（如果映射中的键是序列或映射，则创建它们） - 普通标量：将宽度超过的单词放在单独的一行，而不是放在上一行的后面（问题427，由Antoine Cotten报告）。注意：这目前会导致上一行以空格结尾。
- 421折标量部分的修复：折叠标量第一行中的 ">" 后的注释现在被保留（就像在相同位置的文本标量一样）。由Jacob Floyd报告的问题。
- 将stacklevel添加到警告中
- 从Py2兼容的注释更改为Py3，删除了各种Py2特性
0.17.21 (2022-02-12):
- 修复了使用
pathlib.Path实例调用.compose()方法时的错误。
0.17.20 (2022-01-03):
- 修复了在四舍五入日期时间分数 >= 9999995 时的微秒错误（由Luis Ferreira报告）
0.17.19 (2021-12-26):
- 修复了mypy问题（由Arun报告）
0.17.18 (2021-12-24):
- 折叠标量注释附件中的复制粘贴错误（由Stephan Geulette报告）
- 修复了411号问题，在空序列值之间的缩进错误注释（由Guillermo Julián报告）
0.17.17 (2021-10-31):
- 将时间戳匹配/创建提取到util
0.17.16 (2021-08-28):
- 398还处理了当注释是换行符时的问题397
0.17.15 (2021-08-28):
- 修复了问题397，在键和值之间存在注释时在键之前插入注释（由Bastien gerard报告）
0.17.14 (2021-08-25):
- 修复了问题396，在合并的字典中插入键/值（由Bastien gerard报告）
0.17.13 (2021-08-21):
- 属性处理中的小修复
0.17.12 (2021-08-21):
- 修复了在已注册类上的锚点未保留以及使用带有
@attr.s()的包属性的那些类的问题（两者均由ssph报告）
0.17.11 (2021-08-19):
- 修复了
DuplicateKeyError的基类错误（由Łukasz Rogalski报告） - 修复了读者错误消息中的拼写错误，导致在读者错误期间出现
KeyError（由MTU报告）
0.17.10 (2021-06-24):
- 修复了问题388，旧注释结构的标记不符合两个元素（由Dimitrios Bariamis报告）
0.17.9 (2021-06-10):
- 修复了更新CommentedMap时的错误（由sri在StackOverflow上报告）
0.17.8 (2021-06-09):
- 修复了问题387，模板锚点在标记对象上未设置，导致潜在id重用。（由Artem Ploujnikov报告）
0.17.7 (2021-05-31):
- 问题385也影响了其他已弃用的加载器（通过电子邮件由Oren Watson报告）
0.17.6 (2021-05-31):
- 合并了由Jochen Sprickerhof提供的类型注释更新
- 修复了问题385：弃用的round_trip_loader函数不起作用（由Mike Gouline报告）
- 花了几个小时消除mypy警告/错误
0.17.5 (2021-05-30):
- 修复了问题384
!!set与别名条目导致的在rt上损坏的YAML（由William Kimball报告）
0.17.4 (2021-04-07):
- 防止（空）注释抛出断言错误（问题351由William Kimball报告）注释（或空行）将被丢弃
0.17.3 (2021-04-07):
- 修复由格式字符串中的错误引起的问题382（由William Kimball报告）
- 通过设置
yaml.composer.return_alias = lambda s: copy.deepcopy(s)允许别名扩展（如Stackoverflow答案中所述）
0.17.2 (2021-03-29):
- 将-py2.py3-none-any.whl更改为-py3-none-any.whl，并删除0.17.1
0.17.1 (2021-03-29):
- 添加了'Programming Language :: Python :: 3 :: Only'，并从PyPI中删除了0.17.0（由Alasdair Nicol报告）
0.17.0 (2021-03-26):
- 由于分类信息不完整而删除
- 本版本不再支持Python 2.7，大多数如果不是全部的Python 2特定代码已被移除。0.17.x系列是最后一个支持Python 3.5的系列（这也允许移除对
ruamel.std.pathlib的依赖） - 移除Python 2特定代码分支和适配（u-strings）
- 使用
_F准备%代码用于f-strings - 允许PyOxidisation（问题324相应于171）
- 将Python 2兼容的关键字参数的强制执行替换为'*'
- 旧顶级函数load、safe_load、round_trip_load、dump、safe_dump、round_trip_dump、scan、parse、compose、emit、serialize以及它们的多文档流的_all变体现在发出PendingDeprecationning（例如，当从pytest运行时，但也可以通过
-Wd启动Python）。使用已扩展的YAML()方法。 - 问题376的修复：缩进更改可能会将字面量/折叠标量置于后续注释的
#列之前。实际上使注释部分成为输出中的标量。（由Bence Nagy报告）
有关更早的更改，请参阅文件CHANGES
下载文件
下载适合您平台的文件。如果您不确定选择哪个，请了解更多关于 安装包的信息。
