Ruamel.yaml: How to access merge keys and comments in loaded OrderedDict

Question

I have a Python program that is parsing a number of YAML files, some containing comments, anchors, references, and merge keys that I'd like preserved when I load the YAML file into my parser. ruamel.yaml seems to have round-trip preservation of these when I run the following:

with open(yaml_file, "r") as f:
    yaml = f.read()
parsed_yaml = ruamel.yaml.load(yaml, ruamel.yaml.RoundTripLoader)
print ruamel.yaml.dump(parsed_yaml,Dumper=ruamel.yaml.RoundTripDumper)

Which prints out the original file yaml_file as it was presented including comments and merge keys. I'm wondering if I can access these comments and other keys while the YAML is parsed in OrderedDict form. I need to convert these YAML files to an intermediate type, so being able to both get and set comments, merge keys, anchors, and references is a high priority.

Answer 1

Yes you can access the comments, etc. Your mappings (python dict ) will be loaded in an instance of CommentedMap and your sequences (python list ) in an instance of CommentedSeq . These are subclasses of ordereddict and CommentedBase , resp. of list and CommentedBase .

The CommentedBase has several attributes to which comments, merge, anchor and flow-style information are attached. It has also several methods that set/get these values which rely on some map/sequence specific helper functions.

import sys
from ruamel.yaml import YAML

yaml_str = """\
a: 1   # comment 1
b: 2
c: 3
d: 4
e: 5
"""

yaml = YAML()
data = yaml.load(yaml_str)
data.yaml_add_eol_comment('comment 2', key='c')
data.yaml_add_eol_comment('#  comment 3', key='e', column=8)
yaml.dump(data, sys.stdout)

will give you:

a: 1   # comment 1
b: 2
c: 3   # comment 2
d: 4
e: 5    #  comment 3

Please note that:

• if you don't specify a starting column, the column of the next previous comment is taken.
• a leading # and space will be inserted if a comment string doesn't already start with a that combination of characters.
• there will be at least one space between the scalar and the comment.

The interface is underdocumented, primarily because of laziness of the library author. You best have a look at the tests for comments and for anchors to get some examples. The interface also will also require some changes on the attribute content level eg to allow of attachment of EOL comments to keys as well as to key+value combinations. The following YAML doesn't roundtrip as you would expect/correctly:

abc:      # this is the key
    9989  # this is the value

So be sure to wrap the functionality that you need so there is a single point where you can make changes if the interface in ruamel.yaml changes in a backwards incompatible way.