ruamel.yaml is a YAML parser/emitter that supports roundtrip preservation of comments, seq/map flow style, and map key order


Keywords
yaml, 1, 2, parser, round-trip, preserve, quotes, order, config
License
MIT
Install
pip install ruamel.yaml==0.17.3

Documentation

ruamel.yaml

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

version: 0.15.81
updated: 2018-12-06
documentation: http://yaml.readthedocs.io
repository: https://bitbucket.org/ruamel/
pypi: https://pypi.org/project/ruamel.yaml/

Starting with version 0.15.0 the way YAML files are loaded and dumped is changing. See the API doc for details. Currently existing functionality will throw a warning before being changed/removed. For production systems you should pin the version being used with ``ruamel.yaml<=0.15``. There might be bug fixes in the 0.14 series, but new functionality is likely only to be available via the new API.

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 bitbucket/github) and I'll keep you informed when the status of the API is stable enough to make the transition.

https://readthedocs.org/projects/yaml/badge/?version=stable https://bestpractices.coreinfrastructure.org/projects/1128/badge

ChangeLog

0.15.81 (2018-12-06):
  • fix issue dumping methods of metaclass derived classes (reported and fix provided by Douglas Raillard)
0.15.80 (2018-11-26):
  • fix issue emitting BEL character when round-tripping invalid folded input (reported by Isaac on StackOverflow)
0.15.79 (2018-11-21):
  • fix issue with anchors nested deeper than alias (reported by gaFF on StackOverflow)
0.15.78 (2018-11-15):
0.15.77 (2018-11-09):
  • setting yaml.sort_base_mapping_type_on_output = False, will prevent explicit sorting by keys in the base representer of mappings. Roundtrip already did not do this. Usage only makes real sense for Python 3.6+ (feature request by Sebastian Gerber).
  • implement Python version check in YAML metadata in _test/test_z_data.py
0.15.76 (2018-11-01):
  • fix issue with empty mapping and sequence loaded as flow-style (mapping reported by Min RK, sequence by Maged Ahmed)
0.15.75 (2018-10-27):
0.15.74 (2018-10-17):
  • fix dropping of comment on rt before sequence item that is sequence item (reported by Thorsten Kampe)
0.15.73 (2018-10-16):
  • fix irregular output on pre-comment in sequence within sequence (reported by Thorsten Kampe)
  • allow non-compact (i.e. next line) dumping sequence/mapping within sequence.
0.15.72 (2018-10-06):
  • fix regression on explicit 1.1 loading with the C based scanner/parser (reported by Tomas Vavra)
0.15.71 (2018-09-26):
0.15.70 (2018-09-21):
  • reverted CommentedMap and CommentedSeq to subclass ordereddict resp. list, reimplemented merge maps so that both dict(**commented_map_instance) and JSON dumping works. This also allows checking with isinstance() on dict resp. list. (Proposed by Stuart Berg, with feedback from blhsing on StackOverflow)
0.15.69 (2018-09-20):
  • fix issue with dump_all gobbling end-of-document comments on parsing (reported by Pierre B.)
0.15.68 (2018-09-20):
  • fix issue with parsabel, but incorrect output with nested flow-style sequences (reported by Dougal Seeley)
  • fix issue with loading Python objects that have __setstate__ and recursion in parameters (reported by Douglas RAILLARD)
0.15.67 (2018-09-19):
  • fix issue with extra space inserted with non-root literal strings (Issue reported and PR with fix provided by Naomi Seyfer.)
0.15.66 (2018-09-07):
  • fix issue with fold indicating characters inserted in safe_load-ed folded strings (reported by Maximilian Hils).
0.15.65 (2018-09-07):
  • fix issue #232 revert to throw ParserError for unexcpected ] and } instead of IndexError. (Issue reported and PR with fix provided by Naomi Seyfer.)
  • added key and reverse parameter (suggested by Jannik Klemm via email)
  • indent root level literal scalars that have directive or document end markers at the beginning of a line
0.15.64 (2018-08-30):
  • support round-trip of tagged sequences: !Arg [a, {b: 1}]
  • single entry mappings in flow sequences now written by default without braces, set yaml.brace_single_entry_mapping_in_flow_sequence=True to force getting [a, {b: 1}, {c: {d: 2}}] instead of the default [a, b: 1, c: {d: 2}]
  • fix issue when roundtripping floats starting with a dot such as .5 (reported by Harrison Gregg)
0.15.63 (2018-08-29):
  • small fix only necessary for Windows users that don't use wheels.
0.15.62 (2018-08-29):
  • C based reader/scanner & emitter now allow setting of 1.2 as YAML version. ** The loading/dumping is still YAML 1.1 code**, so use the common subset of YAML 1.2 and 1.1 (reported by Ge Yang)
0.15.61 (2018-08-23):
  • support for round-tripping folded style scalars (initially requested by Johnathan Viduchinsky)
  • update of C code
  • speed up of scanning (~30% depending on the input)
0.15.60 (2018-08-18):
  • again allow single entry map in flow sequence context (reported by Lee Goolsbee)
  • cleanup for mypy
  • spurious print in library (reported by Lele Gaifax), now automatically checked
0.15.59 (2018-08-17):
0.15.58 (2018-08-17):
  • simple mappings can now be used as keys when round-tripping:

    {a: 1, b: 2}: hello world
    

    although using the obvious operations (del, popitem) on the key will fail, you can mutilate it by going through its attributes. If you load the above YAML in d, then changing the value is cumbersome:

    d = {CommentedKeyMap([('a', 1), ('b', 2)]): "goodbye"}

    and changing the key even more so:

    d[CommentedKeyMap([('b', 1), ('a', 2)])] = d.pop(

    CommentedKeyMap([('a', 1), ('b', 2)]))

    (you can use a dict instead of a list of tuples (or ordereddict), but that might result in a different order, of the keys of the key, in the output)

  • check integers to dump with 1.2 patterns instead of 1.1 (reported by Lele Gaifax)

0.15.57 (2018-08-15):
  • Fix that CommentedSeq could no longer be used in adding or do a sort (reported by Christopher Wright)
0.15.56 (2018-08-15):
  • fix issue with python -O optimizing away code (reported, and detailed cause pinpointed, by Alex Grönholm)
0.15.55 (2018-08-14):
  • unmade CommentedSeq a subclass of list. It is now indirectly a subclass of the standard collections.abc.MutableSequence (without .abc if you are still on Python2.7). If you do isinstance(yaml.load('[1, 2]'), list)) anywhere in your code replace list with MutableSequence. Directly, CommentedSeq is a subclass of the abstract baseclass ruamel.yaml.compat.MutableScliceableSequence, with the result that (extended) slicing is supported on ``CommentedSeq``. (reported by Stuart Berg)
  • duplicate keys (or their values) with non-ascii now correctly report in Python2, instead of raising a Unicode error. (Reported by Jonathan Pyle)
0.15.54 (2018-08-13):
  • fix issue where a comment could pop-up twice in the output (reported by Mike Kazantsev and by Nate Peterson)
  • fix issue where JSON object (mapping) without spaces was not parsed properly (reported by Marc Schmidt)
  • fix issue where comments after empty flow-style mappings were not emitted (reported by Qinfench Chen)
0.15.53 (2018-08-12):
  • fix issue with flow style mapping with comments gobbled newline (reported by Christopher Lambert)
  • fix issue where single '+' under YAML 1.2 was interpreted as integer, erroring out (reported by Jethro Yu)
0.15.52 (2018-08-09):
  • added .copy() mapping representation for round-tripping (CommentedMap) to fix incomplete copies of merged mappings (reported by Will Richards)
  • Also unmade that class a subclass of ordereddict to solve incorrect behaviour for {**merged-mapping} and dict(**merged-mapping) (reported independently by Tim Olsson and Filip Matzner)
0.15.51 (2018-08-08):
  • Fix method name dumps (were not dotted) and loads (reported by Douglas Raillard)
  • Fix spurious trailing white-space caused when the comment start column was no longer reached and there was no actual EOL comment (e.g. following empty line) and doing substitutions, or when quotes around scalars got dropped. (reported by Thomas Guillet)
0.15.50 (2018-08-05):
  • Allow YAML() as a context manager for output, thereby making it much easier to generate multi-documents in a stream.
  • Fix issue with incorrect type information for load() and dump() (reported by Jimbo Jim)
0.15.49 (2018-08-05):
  • fix preservation of leading newlines in root level literal style scalar, and preserve comment after literal style indicator (| # some comment) Both needed for round-tripping multi-doc streams in ryd.
0.15.48 (2018-08-03):
  • housekeeping: oitnb for formatting, mypy 0.620 upgrade and conformity
0.15.47 (2018-07-31):
  • fix broken 3.6 manylinux1, the result of an unclean build (reported by Roman Sichnyi)
0.15.46 (2018-07-29):
0.15.45 (2018-07-26):
0.15.44 (2018-07-14):
  • Correct loading plain scalars consisting of numerals only and starting with 0, when not explicitly specifying YAML version 1.1. This also fixes the issue about dumping string '019' as plain scalars as reported by Min RK, that prompted this chance.
0.15.43 (2018-07-12):
  • merge PR33: Python2.7 on Windows is narrow, but has no sysconfig.get_config_var('Py_UNICODE_SIZE'). (merge provided by Marcel Bargull)
  • register_class() now returns class (proposed by Mike Nerone}
0.15.42 (2018-07-01):
  • fix regression showing only on narrow Python 2.7 (py27mu) builds (with help from Marcel Bargull and Colm O'Connor).
  • run pre-commit tox on Python 2.7 wide and narrow, as well as 3.4/3.5/3.6/3.7/pypy
0.15.41 (2018-06-27):
  • add detection of C-compile failure (investigation prompted by StackOverlow by Emmanuel Blot), which was removed while no longer dependent on libyaml, C-extensions compilation still needs a compiler though.
0.15.40 (2018-06-18):
  • added links to landing places as suggested in issue 190 by KostisA
  • fixes issue #201: decoding unicode escaped tags on Python2, reported by Dan Abolafia
0.15.39 (2018-06-17):
  • merge PR27 improving package startup time (and loading when regexp not actually used), provided by Marcel Bargull
0.15.38 (2018-06-13):
0.15.37 (2018-03-21):
  • again trying to create installable files for 187
0.15.36 (2018-02-07):
  • fix issue 187, incompatibility of C extension with 3.7 (reported by Daniel Blanchard)
0.15.35 (2017-12-03):
  • allow None as stream when specifying transform parameters to YAML.dump(). This is useful if the transforming function doesn't return a meaningful value (inspired by StackOverflow by rsaw).
0.15.34 (2017-09-17):
  • fix for issue 157: CDumper not dumping floats (reported by Jan Smitka)
0.15.33 (2017-08-31):
  • support for "undefined" round-tripping tagged scalar objects (in addition to tagged mapping object). Inspired by a use case presented by Matthew Patton on StackOverflow.
  • fix issue 148: replace cryptic error message when using !!timestamp with an incorrectly formatted or non- scalar. Reported by FichteFoll.
0.15.32 (2017-08-21):
  • allow setting yaml.default_flow_style = None (default: False) for for typ='rt'.
  • fix for issue 149: multiplications on ScalarFloat now return float (reported by jan.brezina@tul.cz)
0.15.31 (2017-08-15):
  • fix Comment dumping
0.15.30 (2017-08-14):
  • fix for issue with "compact JSON" not parsing: {"in":{},"out":{}} (reported on StackOverflow by mjalkio
0.15.29 (2017-08-14):
  • fix issue #51: different indents for mappings and sequences (reported by Alex Harvey)
  • fix for flow sequence/mapping as element/value of block sequence with sequence-indent minus dash-offset not equal two.
0.15.28 (2017-08-13):
  • fix issue #61: merge of merge cannot be __repr__-ed (reported by Tal Liron)
0.15.27 (2017-08-13):
  • fix issue 62, YAML 1.2 allows ? and : in plain scalars if non-ambigious (reported by nowox)
  • fix lists within lists which would make comments disappear
0.15.26 (2017-08-10):
  • fix for disappearing comment after empty flow sequence (reported by oit-tzhimmash)
0.15.25 (2017-08-09):
  • fix for problem with dumping (unloaded) floats (reported by eyenseo)
0.15.24 (2017-08-09):
  • added ScalarFloat which supports roundtripping of 23.1, 23.100, 42.00E+56, 0.0, -0.0 etc. while keeping the format. Underscores in mantissas are not preserved/supported (yet, is anybody using that?).
  • (finally) fixed longstanding issue 23 (reported by Antony Sottile), now handling comment between block mapping key and value correctly
  • warn on YAML 1.1 float input that is incorrect (triggered by invalid YAML provided by Cecil Curry)
  • allow setting of boolean representation (false, true) by using: yaml.boolean_representation = [u'False', u'True']
0.15.23 (2017-08-01):
  • fix for round_tripping integers on 2.7.X > sys.maxint (reported by ccatterina)
0.15.22 (2017-07-28):
  • fix for round_tripping singe excl. mark tags doubling (reported and fix by Jan Brezina)
0.15.21 (2017-07-25):
0.15.20 (2017-07-23):
  • wheels for windows including C extensions
0.15.19 (2017-07-13):
  • added object constructor for rt, decorator yaml_object to replace YAMLObject.
  • fix for problem using load_all with Path() instance
  • fix for load_all in combination with zero indent block style literal (pure=True only!)
0.15.18 (2017-07-04):
  • missing pure attribute on YAML useful for implementing !include tag constructor for including YAML files in a YAML file
  • some documentation improvements
  • trigger of doc build on new revision
0.15.17 (2017-07-03):
  • support for Unicode supplementary Plane output (input was already supported, triggered by this Stack Overflow Q&A)
0.15.16 (2017-07-01):
  • minor typing issues (reported and fix provided by Manvendra Singh
  • small doc improvements
0.15.15 (2017-06-27):
0.15.14 (2017-06-25):
  • fix for issue 133, in setup.py: change ModuleNotFoundError to ImportError (reported and fix by Asley Drake)
0.15.13 (2017-06-24):
  • suppress duplicate key warning on mappings with merge keys (reported by Cameron Sweeney)
0.15.12 (2017-06-24):
  • remove fatal dependency of setup.py on wheel package (reported by Cameron Sweeney)
0.15.11 (2017-06-24):
  • fix for issue 130, regression in nested merge keys (reported by David Fee)
0.15.10 (2017-06-23):
  • top level PreservedScalarString not indented if not explicitly asked to
  • remove Makefile (not very useful anyway)
  • some mypy additions
0.15.9 (2017-06-16):
  • fix for issue 127: tagged scalars were always quoted and seperated by a newline when in a block sequence (reported and largely fixed by Tommy Wang)
0.15.8 (2017-06-15):
  • allow plug-in install via install ruamel.yaml[jinja2]
0.15.7 (2017-06-14):
  • add plug-in mechanism for load/dump pre resp. post-processing
0.15.6 (2017-06-10):
  • a set() with duplicate elements now throws error in rt loading
  • support for toplevel column zero literal/folded scalar in explicit documents
0.15.5 (2017-06-08):
  • repeat load() on a single YAML() instance would fail.
0.15.4 (2017-06-08):
  • transform parameter on dump that expects a function taking a string and returning a string. This allows transformation of the output before it is written to stream. This forces creation of the complete output in memory!
  • some updates to the docs
0.15.3 (2017-06-07):
  • No longer try to compile C extensions on Windows. Compilation can be forced by setting the environment variable RUAMEL_FORCE_EXT_BUILD to some value before starting the pip install.
0.15.2 (2017-06-07):
  • update to conform to mypy 0.511: mypy --strict
0.15.1 (2017-06-07):
  • duplicate keys in mappings generate an error (in the old API this change generates a warning until 0.16)
  • dependecy on ruamel.ordereddict for 2.7 now via extras_require
0.15.0 (2017-06-04):
  • it is now allowed to pass in a pathlib.Path as "stream" parameter to all load/dump functions
  • passing in a non-supported object (e.g. a string) as "stream" will result in a much more meaningful YAMLStreamError.
  • assigning a normal string value to an existing CommentedMap key or CommentedSeq element will result in a value cast to the previous value's type if possible.
  • added YAML class for new API
0.14.12 (2017-05-14):
  • fix for issue 119, deepcopy not returning subclasses (reported and PR by Constantine Evans <cevans@evanslabs.org>)
0.14.11 (2017-05-01):
  • fix for issue 103 allowing implicit documents after document end marker line (...) in YAML 1.2
0.14.10 (2017-04-26):
  • fix problem with emitting using cyaml
0.14.9 (2017-04-22):
0.14.8 (2017-04-19):
  • fix Text not available on 3.5.0 and 3.5.1, now proactively setting version guards on all files (reported by João Paulo Magalhães)
0.14.7 (2017-04-18):
  • round trip of integers (decimal, octal, hex, binary) now preserve leading zero(s) padding and underscores. Underscores are presumed to be at regular distances (i.e. 0o12_345_67 dumps back as 0o1_23_45_67 as the space from the last digit to the underscore before that is the determining factor).
0.14.6 (2017-04-14):
  • binary, octal and hex integers are now preserved by default. This was a known deficiency. Working on this was prompted by the issue report (112) from devnoname120, as well as the additional experience with .replace() on scalarstring classes.
  • fix issues 114: cannot install on Buildozer (reported by mixmastamyk). Setting env. var RUAMEL_NO_PIP_INSTALL_CHECK will suppress pip-check.
0.14.5 (2017-04-04):
  • fix issue 109: None not dumping correctly at top level (reported by Andrea Censi)
  • fix issue 110: .replace on Preserved/DoubleQuoted/SingleQuoted ScalarString would give back "normal" string (reported by sandres23)
0.14.4 (2017-03-31):
  • fix readme
0.14.3 (2017-03-31):
0.14.2 (2017-03-23):
  • fix for old default pip on Ubuntu 14.04 (reported by Sébastien Maccagnoni-Munch)
0.14.1 (2017-03-22):
  • fix Text not available on 3.5.0 and 3.5.1 (reported by Charles Bouchard-Légaré)
0.14.0 (2017-03-21):
  • updates for mypy --strict
  • preparation for moving away from inheritance in Loader and Dumper, calls from e.g. the Representer to the Serializer.serialize() are now done via the attribute .serializer.serialize(). Usage of .serialize() outside of Serializer will be deprecated soon
  • some extra tests on main.py functions

For older changes see the file CHANGES