ruamel.yaml is a YAML 1.2 loader/dumper package for Python. It is a
derivative of Kirill Simonov’s PyYAML 3.11.
ruamel.yaml supports YAML 1.2 and has round-trip loaders and dumpers.
A round-trip is a YAML load-modify-save sequence and ruamel.yaml tries to
preserve, among others:
- 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 form``idNNN``)
- merges in dictionaries are preserved
This preservation is normally not broken unless you severely alter the structure of a component (delete a key in a dict, remove list entries). Reassigning values or replacing list items, etc., is fine.
For the specific 1.2 differences see Defaulting to YAML 1.2 support
Although individual indentation of lines is not preserved, you can specify separate indentation levels for mappings and sequences (counting for sequences does not include the dash for a sequence element) and specific offset of block sequence dashes within that indentation.
ruamel.yaml still allows most of the PyYAML way of doing
things, adding features required a different API then the transient
nature of PyYAML’s
Dumper. Starting with
ruamel.yaml version 0.15.0 this new API gets introduced. Old ways
that get in the way will be removed, after first generating warnings
on use, then generating an error. In general a warning in version 0.N.x will become an
error in 0.N+1.0
Many of the bugs filed against PyYAML, but that were never
acted upon, have been fixed in