ruamel.yaml.base 0.3.2

YAMLBase class with saving loading and version support

YAMLBase class with saving, delayed loading and optional version support

The YAMLBase class is initiated with a pathlib.Path or string based filename of a document containing a single YAML file. This file needs to exists unless the create_ok parameter is supplied, in which case an instance of the argument to that parameter is created (typically a list or dict like object) as the root of the data structure. If the argument is True an empty ruamel.yaml.CommentedMap() instance is created as the root.

Access to the root object is made via the .data attribute, if an existing file was specified, it is read in on the first access to .data.

from ruamel.yaml.base import YAMLBase

file_name = '/data0/talks/meta.yaml'

base = YAMLBase(file_name, create_ok=True)
base.data['PyCon 2006'] = dict(location='Dallas, TX, USA', title='Extending the life of CVS with Python')
base.data['EuroPython 2016'] = dict(location='Bilbao, Spain', title='Beyond scraping')
base.changed = True
base.save()
print(open(file_name).read())

Which prints:

PyCon 2006:
  location: Dallas, TX, USA
  title: Extending the life of CVS with Python
EuroPython 2016:
  location: Bilbao, Spain
  title: Beyond scraping

The document is normally loaded using ruamel.yaml’s default round-trip mode. If the initial access to an existing document is done via .fast_data, the loading is done via the faster C loader (which is not fully YAML 1.2) compatible. In that case you should not save the resulting file.

The save will not actually dump out the YAML document file, unless .changed has been set to True. Saving to file sets .changed back to False. Using the force=True will write to file independent of changed. You can also add an extra out argument, e.g. instead of the last two lines in the example above, you could do:

import sys
base.save(out=sys.stdout)  # not changing `.changed`
base.save()

automatic saving

If YAMLBase is initialised with auto_save=True, and .changed has been set the YAML file will be dumped when the object goes out of scope.

internal progress

The initialisation has an optional verbose argument which can be set to a positive integer to get some information on what is going on internally.

alternative initialisation

When you subclass YAMLBase, you can pre set the create_ok and auto_save values by setting attributes before calling super():

class X(YAMLBase):
    def __init__(self, path):
        self._create_ok = True
        self._auto_save = True
        super().__init__(path=path)