Comments¶

Comments and blank lines are kept automatically when you load and save a file. Use the methods below when you want to change them.

Add a comment¶

from yamluna import YAML

yaml = YAML()
config = yaml.load('replicas: 3\nports: [80, 443]\n')
config.yaml_set_start_comment('Production service')
config.yaml_add_eol_comment('extra capacity', 'replicas')
config.yaml_set_comment_before_after_key('ports', before='Public ports')
print(yaml.dump(config), end='')

Output:

# Production service
replicas: 3 # extra capacity
# Public ports
ports: [80, 443]

Pass the comment text without #; yamluna adds it. To comment on a list item, pass its index instead of a mapping key.

Remove a setting and its comment¶

from yamluna import YAML

yaml = YAML()
config = yaml.load("""image: app:1.4
# staging only
debug: true
# production capacity
replicas: 3
""")

del config['debug']
print(yaml.dump(config), end='')

Output:

image: app:1.4
# production capacity
replicas: 3

Rename a key¶

Use rename() to keep the key's position and comments:

from yamluna import YAML

yaml = YAML()
config = yaml.load('name: demo\nreplicas: 3  # production capacity\n')
config.rename('replicas', 'workers')
print(yaml.dump(config), end='')

Output:

name: demo
workers: 3   # production capacity

move_to_end(key) reorders a mapping entry with its comments. List reverse() and sort() also carry comments with their items. See a list example.

Useful methods¶

With no column, a new trailing comment aligns with nearby comments when possible.

Comments above the first item and insertions into commented lists have known edge cases. See limitations before relying on those operations.