Comments¶

tomlrt exposes comments at every level of a document: end-of-line, above an entry, above a section header, and at the top or bottom of the file.

End-of-line comments¶

Table.comments is a live MutableMapping[str, str] keyed by entry name. Assign a string to set or replace the comment; del removes it entirely.

doc = tomlrt.loads("""
[server]
host = "localhost"  # default
port = 8080
""")

server = doc.table("server")
server.comments["port"] = "override with $PORT"
del server.comments["host"]                 # remove the comment entirely

print(tomlrt.dumps(doc))
# [server]
# host = "localhost"
# port = 8080 # override with $PORT

Comments above an entry¶

Table.leading_comments is keyed by entry name and stores a tuple of bare comment lines (no leading #):

server.leading_comments["port"] = (
    "Port the server listens on.",
    "Defaults to 8080.",
)

Section header comments¶

Table.header_comment is the end-of-line comment on the [section] line itself; Table.header_leading_comments is the run of # … lines immediately above it:

server.header_comment = "HTTP listener"
server.header_leading_comments = ("Server configuration.",)

Array-item comments¶

Array exposes comments and leading_comments keyed by integer index:

tags = doc.array("tags")
tags.comments[0] = "primary"
tags.leading_comments[1] = ("alternate",)

Inline-table comments¶

Because tomlrt targets TOML 1.1, inline tables may span multiple lines and carry comments. Table.comments and Table.leading_comments work on an inline table just as they do on a [section], keyed by entry name:

doc = tomlrt.loads('pkg = { name = "tomlrt", version = "0.1" }\n')
pkg = doc.table("pkg")
pkg.comments["name"] = "the package name"

print(tomlrt.dumps(doc))
# pkg = {
#     name = "tomlrt", # the package name
#     version = "0.1",
# }

A single-line inline table has nowhere to put a comment, so setting one promotes the table to multi-line form automatically — exactly as it does for an inline array. You can also control the layout explicitly with Table.multiline / Table.set_multiline(multiline=…); collapsing back to a single line raises if it would orphan a comment.

For a dotted-key inline table such as { a.b = 1 }, address the comment through the inner table — doc["t"]["a"].comments["b"] — mirroring how a top-level a.b = 1 is reached via doc["a"].comments["b"].

Table.header_comment and Table.header_leading_comments remain unavailable on inline tables: an inline table has no header line to attach them to.

Orphan comments between sections¶

leading_comments and header_leading_comments cover only the run of # … lines that sit directly above an entry or section header. A comment group separated from the entry by a blank line — for example a free-standing # … block between [a] and [b] — is not part of either view, and is silently dropped if the entry is removed and reinserted.

Table.leading_block and Table.header_leading_block are the lossless counterparts: they expose the whole leading region — both the blank- separated groups above and the attached run immediately above the entry — as a tuple in which each str is a bare comment line and each None is a blank line. Round-tripping a value through them therefore preserves exact line structure.

[a]
x = 1

# orphan

[b]
y = 2

assert doc["b"].header_leading_block == (None, "orphan", None)
doc["b"].header_leading_block = ("orphan", None, "attached")

For the first slot in a document, Document.preamble is disjoint from this view: it is read and written through Document.preamble only.

Document preamble and epilogue¶

The top-of-file and bottom-of-file comment blocks are reachable via Document.preamble and Document.epilogue — both are tuples of bare comment lines, and both have setters that replace the entire block. Assign () to clear.

doc.preamble = ("Generated by build.py — do not edit.",)
doc.epilogue = ("end of file",)

A "preamble" is the run of # … lines that opens the file and is blank-line-separated from anything below. Comments that sit directly above the first key (no blank line) are leading comments of that key, not preamble.