ruamel.yaml.split 0.2.2

YAML document splitter, with iterator that returns document, start linenumber and optionally data

This package provides a YAML document splitter, that allows you to iterate over a UTF-8 encoded file with YAML documents, and that returns each document, start linenumber and optionally loaded data.

Using this has the advantage over using load_all(), that you can skip individual documents that you know don’t load, or that you test/transform before proper loading. E.g. R markdown files have a YAML header followed by a non-YAML body (of course it would have been much better if in R markdown, the header had been followed by --- | instead of only a directory-end-marker (---), that way you could use any compliant YAML parser to load both)

You can use the following to get to each document:

from pathlib import Path
from ruamel.yaml.split import split

for doc, line_nr in split(Path('input.yaml')):
    print(doc.decode('utf-8'), line_nr)

The line_nr indicates the starting line of the document and can be used as an offset for e.g. errors that are generated when parsing the document.

You can also provide a YAML() instance to get the document loaded for you:

import ruamel.yaml

for doc, data, line_nr in split(Path('input.yaml'), yaml=ruamel.yaml.YAML()):
    print(doc.decode('utf-8'), data, line_nr)

the YAML() instance you provide is used to load all documents.

By default split() splits on the line-ending after the document-end-marker (...), so that any comment on the line of the document-end-marker is part of the document before it. Using some constants imported from ruamel.yaml.split that you provide to the the cmnt parameter of split(), you can influence where the comments “between” documents are split. C_PRE adds any such comments to the preceding document, C_POST to the following document. C_SPLIT_ON_FIRST_BLANK, splits after the first blank line and assigns to both.

from ruamel.yaml.split import C_SPLIT_ON_FIRST_BLANK

for doc, data, line_nr in split(Path('input.yaml'), cmnt=C_SPLIT_ON_FIRST_BLANK):
    print(doc.decode('utf-8'), line_nr)

Comments at the end of the document stream are all attached to the last document, independent of the cmnt parameter.