tomlite

English | 한국어

Change values in a TOML config file from Python, keeping the comments and layout the user wrote. tomlite rewrites only the lines that change, so hand-written comments, blank lines, and aligned = survive the edit.

1. Install

pip install tomlite

No dependencies. Python 3.11+. Works on Windows, macOS, and Linux.

2. Quickstart

from tomlite import TOMLEditor

doc = TOMLEditor.load("config.toml")                      # read the file, or an empty document if it is new

# add a [[user]] block only if no user named "bob" is there yet
if not doc.has_in_array("user", match_field="name", match_value="bob"):
    doc.append_to_array("user", [("name", "bob"), ("role", "guest")])

doc.set_root_key("title", "My App", only_if_absent=True)  # set title only if it is absent
doc.set_table_key("server", "debug", False)               # change [server].debug to false
doc.save("config.toml")                                   # write it back, keeping the comments and layout

Read the values back with tomllib:

import tomllib

with open("config.toml", "rb") as f:
    config = tomllib.load(f)

3. Supported formats

tomlite edits three shapes — the ones a machine-managed config file uses:

title = "My App"                 # top-level key

[server]                         # table
host = "localhost"
port = 8080
debug = true
tags = ["web", "prod"]           # values: str, int, float, bool, string array

[[user]]                         # table array, entries matched by a field
name = "alice"
role = "admin"

A construct its line scanner can't edit safely — a multi-line string or a dotted key (a.b = 1) — raises UnsupportedTOMLError instead of risking corruption; reading and dumps still work.

4. Round-trip

Any value is stored safely and reads back unchanged, even one with quotes, brackets, or backslashes. Changing a value keeps the comment on its line, an array you wrote across several lines stays multi-line, and the file's newline style (LF or CRLF) is preserved. An edit that would make the file invalid TOML is refused and the file left untouched.

5. API

Values are str, int, float, bool, or a sequence of str. Match arguments are keyword-only. multiline=True writes an array value one item per line; replacing a multi-line array with a non-empty one keeps it multi-line.

6. License

MIT