Layout¶

These operations change how a document is written without changing its values. Comments stay with their entries.

Sorting child keys¶

doc.sort() and table.sort() reorder their direct keys in place, keeping comments and formatting. They accept key and reverse, like list.sort().

import tomlrt

doc = tomlrt.loads("""\
# the name
name = "tomlrt"
# the version
version = "0.1"
# the author
author = "me"
""")
doc.sort()
print(tomlrt.dumps(doc))

# the author
author = "me"
# the name
name = "tomlrt"
# the version
version = "0.1"

Single-line and multi-line values¶

Use multiline on arrays and inline tables to change their layout. For a custom indent, use set_multiline:

arr = doc.array("tags")
arr.multiline = True
arr.set_multiline(multiline=True, indent=2)

tbl = doc.table("pkg")
tbl.set_multiline(multiline=True, indent=2)

Setting multiline=False makes the value single-line. This raises TOMLError if it would lose a comment; remove the comments first.

Converting inline tables to sections¶

Use promote_inline to turn an inline table into a section:

import tomlrt

doc = tomlrt.loads("""\
[tool]
ruff = { line-length = 88 }
""")
doc.table("tool").promote_inline("ruff")
print(tomlrt.dumps(doc))

[tool]

[tool.ruff]
line-length = 88

Use promote_array to turn an array of inline tables into repeated [[table]] blocks:

import tomlrt

doc = tomlrt.loads('pkgs = [{a = 1}, {b = 2}]\n')
doc.promote_array("pkgs")
print(tomlrt.dumps(doc))

[[pkgs]]
a = 1

[[pkgs]]
b = 2

Conversion raises TOMLError if it would lose comments inside the value.

Canonical formatting¶

Call format() to replace the original spacing with consistent formatting. It works in place on a document, table, or array:

import tomlrt

doc = tomlrt.loads("""
a   =1
b=2
arr=[1,2 ,3 ]


[bar]
x={a=1,b=2}
""")

doc.format()
print(tomlrt.dumps(doc))

a = 1
b = 2
arr = [1, 2, 3]

[bar]
x = { a = 1, b = 2 }

Formatting normalizes whitespace, indentation, and blank lines. Comments stay with their entries, and multi-line values stay multi-line. Formatting one section leaves other sections alone.

For a newly created table, add it to a document before calling format().

Pass FormatOptions to customize the result:

doc.format(options=tomlrt.FormatOptions(indent=4, normalize_comments=False))

Quote style¶

By default, formatting preserves string and quoted-key spelling, including escapes. Set quote_style to prefer single or double quotes:

doc.format(options=tomlrt.FormatOptions(quote_style=tomlrt.QuoteStyle.DOUBLE))

The formatter avoids adding escapes, even when that means using the other quote style:

Bare keys stay bare, and multi-line strings stay multi-line.

Comment normalization¶

Formatting adds one space after # and removes trailing whitespace from comment text. Empty comments remain #.

Pass FormatOptions(normalize_comments=False) to leave comment text untouched.