Comments

New in Box 8.

Box keeps the comments of a YAML document when you load it, and writes them back out with to_yaml, so you can edit config files with dot access without losing the notes in them. You can also add, read and remove comments yourself on any Box or BoxList.

Comments are kept separately from the data: to_dict(), to_json(), comparisons and hashing never see them.

Round trip a YAML file

from box import Box

config = Box.from_yaml("""\
# Service settings

name: box  # the name
# Where to listen
server:
  host: localhost  # bind address
  port: 8080
""")

config.server.port = 9090
config.server.timeout = 30
print(config.to_yaml())

# Service settings

name: box  # the name
# Where to listen
server:
  host: localhost  # bind address
  port: 9090
  timeout: 30

Comments stay with their keys when you change values, add keys, or delete other keys. When a key is deleted, its comments go with it.

Adding your own

config.server.set_comment("timeout", "seconds")                 # end of the line
config.set_comment("server", "Change with care", position="before")  # line(s) above the key
config.set_comment(None, "Generated, do not edit")              # top of the document
config.set_comment(None, "end of file", position="end")         # bottom of the document

config.server.get_comment("timeout")
# {'eol': 'seconds'}

config.server.del_comment("timeout")

Position	Where
"eol" (default)	after the value, on the key's line
"before"	the lines above the key, text can have several lines and blank lines
"start" / "end"	with key=None, the top or bottom of the document

Passing an empty text (or None) removes the comment at that position. You don't need to include the #. Comments can only be attached to keys that exist.

With box_dots=True the key can be a path, including list items:

config = Box({"servers": [{"host": "a"}, {"host": "b"}]}, box_dots=True)
config.set_comment("servers[1].host", "backup")

For a BoxList, the key is the item index (negative indexes work too). Item comments follow their items through insert, pop, remove, del, reverse and sort. Assigning to a slice drops the list's item comments, because the items can't be matched up anymore.

Things to know

• Comments are read and written by ruamel.yaml with its default round trip mode. With PyYAML, or ruamel_typ="safe", they are ignored and the output is the same as without comments.
• Box writes YAML in ruamel's standard layout, so the text comes back normalized: two spaces before end of line comments, list items without extra indentation, and anchors / merge keys (<<) expanded, as before.
• Copies, deep copies, pickles and Box(other_box) keep the comments. merge_update and update keep the comments that are already there.
• With camel_killer_box the comments follow the renamed keys. With box_dots, a YAML key that is split into nested boxes (a.b: 1) loses its comment.
• ConfigBox finds comments whatever the case of the key, and a comment moves with its key when a later write changes the key's spelling.
• get_comment, set_comment and del_comment are protected names: keys with those names still work with box["get_comment"], but not as attributes.