Read and write YAML¶

Start with text¶

from yamluna import YAML

yaml = YAML()
config = yaml.load('replicas: 3  # production\n')
config['replicas'] = 5
print(yaml.dump(config), end='')

Output:

replicas: 5  # production

load() returns a dictionary, list, or value. The mapping and list types also remember the YAML formatting. An empty document returns None.

Edit a file¶

Given this config.yaml:

replicas: 3  # production

from pathlib import Path
from yamluna import YAML

yaml = YAML()
path = Path('config.yaml')
config = yaml.load(path)
config['replicas'] = 5
yaml.dump(config, path)

The file now contains:

replicas: 5  # production

Pass a Path for a filename. yaml.load('config.yaml') reads the literal text config.yaml, so it returns a string instead of opening the file.

Choose an input or output¶

Bytes are accepted too: UTF-8 is the default, and a byte-order mark identifies UTF-16 or UTF-32 input. File output defaults to UTF-8.

Multiple documents¶

Use load_all() and dump_all() for files containing documents separated by ---:

from yamluna import YAML

yaml = YAML()
documents = yaml.load_all('---\nname: web\n---\nname: worker\n')
documents[1]['name'] = 'jobs'
print(yaml.dump_all(documents), end='')

Output:

---
name: web
---
name: jobs

load_all() returns a list. load() raises ComposerError if it finds more than one document.

Use the same YAML() instance for a load-edit-save cycle. For empty or comment-only documents, save before loading another stream on that instance so their comments and markers stay associated with them.

Next: add comments, keep quotes when editing, or handle errors.