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.

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