Home

Awesome

ruamel.yaml

ruamel.yaml is a YAML 1.2 loader/dumper package for Python.

<table class="docutils"> <tr> <td>version</td> <td>0.18.6</td> </tr> <tr> <td>updated</td> <td>2024-02-07</td> </tr> <tr> <td>documentation</td> <td><a href="https://yaml.readthedocs.io">https://yaml.readthedocs.io</a></td> </tr> <tr> <td>repository</td> <td><a href="https://sourceforge.net/projects/ruamel-yaml">https://sourceforge.net/projects/ruamel-yaml</a></td> </tr> <tr> <td>pypi</td> <td><a href="https://pypi.org/project/ruamel.yaml">https://pypi.org/project/ruamel.yaml</a></td> </tr> </table>

As announced, in 0.18.0, the old PyYAML functions have been deprecated. (scan, parse, compose, load, emit, serialize, dump and their variants (_all, safe_, round_trip_, etc)). If you only read this after your program has stopped working: I am sorry to hear that, but that also means you, or the person developing your program, has not tested with warnings on (which is the recommendation in PEP 565, and e.g. defaultin when using pytest). If you have troubles, explicitly use

pip install "ruamel.yaml<0.18.0"

or put something to that effects in your requirments, to give yourself some time to solve the issue.

There will be at least one more potentially breaking change in the 0.18 series: YAML(typ='unsafe') now has a pending deprecation warning and is going to be deprecated, probably before the end of 2023. If you only use it to dump, please use the new YAML(typ='full'), the result of that can be safely loaded with a default instance YAML(), as that will get you inspectable, tagged, scalars, instead of executed Python functions/classes. (You should probably add constructors for what you actually need, but I do consider adding a ruamel.yaml.unsafe package that will re-add the typ='unsafe' option. Please adjust/pin your dependencies accordingly if necessary.

There seems to be a CVE on ruamel.yaml, stating that the load() function could be abused because of unchecked input. load() was never the default function (that was round_trip_load() before the new API came into existence. So the creator of that CVE was ill informed and probably lazily assumed that since ruamel.yamlis a derivative of PyYAML (for which a similar CVE exists), the same problem would still exist, without checking. So the CVE was always inappriate, now just more so, as the call to the functionload()with any input will terminate your program with an error message. If you (have to) care about such things as this CVE, my recommendation is to stop using Python completely, aspickle.load()can be abused in the same way asload()(and like unlikeload()` is only documented to be unsafe, without development-time warning.

Version 0.17.21 was the last one tested to be working on Python 3.5 and 3.6<BR> The 0.16.13 release was the last that was tested to be working on Python 2.7.

There are two extra plug-in packages (ruamel.yaml.bytes and ruamel.yaml.string) for those not wanting to do the streaming to a io.BytesIO/StringIO buffer themselves.

If your package uses ruamel.yaml and is not listed on PyPI, drop me an email, preferably with some information on how you use the package (or a link to the repository) and I'll keep you informed when the status of the API is stable enough to make the transition.

<pre> <a href="overview/#overview">Overview</a> <a href="install/#installing">Installing</a> <a href="install/#optional-requirements">Optional requirements</a> <a href="basicuse/#basic-usage">Basic Usage</a> <a href="basicuse/#load-and-dump">Load and dump </a> <a href="basicuse/#more-examples">More examples</a> <a href="dumpcls/#working-with-python-classes">Working with Python classes</a> <a href="dumpcls/#dumping-python-classes">Dumping Python classes</a> <a href="dumpcls/#dataclass">Dataclass</a> <a href="detail/#details">Details</a> <a href="detail/#indentation-of-block-sequences">Indentation of block sequences</a> <a href="detail/#inconsistently-indented-yaml">Inconsistently indented YAML</a> <a href="detail/#indenting-using-typsafe">Indenting using `typ="safe"`</a> <a href="detail/#positioning-in-top-level-mappings-prefixing">Positioning ':' in top level mappings, prefixing ':'</a> <a href="detail/#document-version-support">Document version support</a> <a href="detail/#round-trip-including-comments">Round trip including comments</a> <a href="detail/#config-file-formats">Config file formats</a> <a href="detail/#extending">Extending</a> <a href="detail/#smartening">Smartening</a> <a href="example/#examples">Examples</a> <a href="example/#output-of-dump-as-a-string">Output of `dump()` as a string</a> <a href="api/#departure-from-previous-api">Departure from previous API</a> <a href="api/#loading">Loading</a> <a href="api/#duplicate-keys">Duplicate keys</a> <a href="api/#dumping-a-multi-document-yaml-stream">Dumping a multi-document YAML stream</a> <a href="api/#dumping">Dumping</a> <a href="api/#controls">Controls</a> <a href="api/#transparent-usage-of-new-and-old-api">Transparent usage of new and old API</a> <a href="api/#reason-for-api-change">Reason for API change</a> <a href="pyyaml/#differences-with-pyyaml">Differences with PyYAML</a> <a href="pyyaml/#defaulting-to-yaml-12-support">Defaulting to YAML 1.2 support</a> <a href="pyyaml/#py2py3-reintegration">PY2/PY3 reintegration</a> <a href="pyyaml/#fixes">Fixes</a> <a href="pyyaml/#testing">Testing</a> <a href="pyyaml/#api">API</a> <a href="contributing/#contributing">Contributing</a> <a href="contributing/#documentation">Documentation</a> <a href="contributing/#code">Code</a> <a href="contributing/#flake">Flake</a> <a href="contributing/#toxpytest">Tox/pytest</a> <a href="contributing/#typingmypy">Typing/mypy</a> <a href="contributing/#generated-files">Generated files</a> <a href="contributing/#vulnerabilities">Vulnerabilities</a> </pre>

imageimage image image image image

ChangeLog

0.18.6 (2024-02-07):

0.18.5 (2023-11-03):

0.18.4 (2023-11-01):

0.18.3 (2023-10-29):

0.18.2 (2023-10-24):

0.18.1 (2023-10-24):

0.18.0 (2023-10-23):

0.17.40 (2023-10-20):

0.17.39 (2023-10-19):

0.17.36 (2023-10-19):

0.17.35 (2023-10-04):

0.17.34 (2023-10-03):

@yaml.register_class
@dataclass
class ...

0.17.33 (2023-09-28):

0.17.32 (2023-06-17):

0.17.31 (2023-05-31):

0.17.30 (2023-05-30):

0.17.29 (2023-05-30):

0.17.28 (2023-05-26):

0.17.27 (2023-05-25):

0.17.26 (2023-05-09):

0.17.25 (2023-05-09):

0.17.24 (2023-05-06):

0.17.23 (2023-05-05):

0.17.22 (2023-05-02):

0.17.21 (2022-02-12):

0.17.20 (2022-01-03):

0.17.19 (2021-12-26):

0.17.18 (2021-12-24):

0.17.17 (2021-10-31):

0.17.16 (2021-08-28):

0.17.15 (2021-08-28):

0.17.14 (2021-08-25):

0.17.13 (2021-08-21):

0.17.12 (2021-08-21):

0.17.11 (2021-08-19):

0.17.10 (2021-06-24):

0.17.9 (2021-06-10):

0.17.8 (2021-06-09):

0.17.7 (2021-05-31):

0.17.6 (2021-05-31):

0.17.5 (2021-05-30):

0.17.4 (2021-04-07):

0.17.3 (2021-04-07):

0.17.2 (2021-03-29):

0.17.1 (2021-03-29):

0.17.0 (2021-03-26):


For older changes see the file CHANGES