Comment

Comment objects can be attached to keymap entries to associate comments with specific keys or values. Comments are automatically captured and attached to a keymap entry by load() / loads() when a keymap is supplied. It is also possible to build a keymap up from scratch and attach comments using annotate(). Then, the output of dump() / dumps() via map_keys= is adorned with the comments when such a keymap is passed in via map_keys=. See Comments for the full story (attribution rules, read/write API, and round-tripping).

class nestedtext.Comment(text='', indent=0, *, tab=None, before=0, after=0)

A single comment captured during load or built by the user.

Holds the comment text (joined by \n for multi-line comments) plus indent and per-comment blank-line metadata.

indent is the absolute indentation (in spaces) at which the comment’s # will be placed. It is set by the loader and is used by the dumper when tab is None.

tab is the alternative way to express indent: a tabstop offset relative to the slot’s natural indent. When tab is not None, the dumper computes the absolute indent at emit time as natural_for_slot + tab * dumps.indent; the indent field is ignored. The loader leaves tab as None; annotate() and user-built Comments may set it.

before / after are the number of blank lines emitted before and after this comment. The loader does not set these; they exist for user-built comments only.

text may also be None: a Comment with text=None emits no # line at all; only its before / after blank lines are rendered. This is a convenient way to inject pure blank-line separators inside a comment list (for example, between two Comments returned by a provider).

The Location class exposes accessor methods for reading and modifying the comments attached to each key (get_key_leading_comments and friends). Document-level header and footer comments live on the root Location at keymap[()], accessed via Location.get_header_comments() / set_header_comments() / add_header_comment() and the equivalent footer trio. Every key in the keymap is a tuple, so depth-based iteration using len(keys) remains safe.

Per-Location spacing is also supported via Location.get_spacing() / set_spacing(). A non-empty spacing dict attached to a Location replaces the dumps() spacing argument for that Location’s entire subtree; integer keys are interpreted as relative depth (0 = blank lines between this Location’s direct children, 1 = grandchildren, …) and absent depth keys default to zero. The "edges" key is only consulted on the document-root Location (keymap[()]).