ruamel.yaml.split 0.2.1

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.

This has the advantage over using load_all(), that you can skip individual documents that you know that don’t load or that you test for 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 the header had been followed by --- | instead of only a directory-end-marker (---), so 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)

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.