DOCSEARCHbyAlgolia
Submit Docs

tomlkit

repository·master·Indexed 21 days ago

https://github.com/python-poetry/tomlkit

A style-preserving, 1.1.0-compliant TOML library for Python. It is designed to parse and edit TOML files while maintaining comments, whitespace, indentation, and element ordering, making it ideal for tools that modify configuration files without destroying user formatting.

Tokens
10.1K
Snippets
39
Records
53
Agent score
73%

What's inside tomlkit

  1. Overview of TOML Kit

    master

    TOML Kit is a 1.0.0-compliant TOML library for Python. Unlike standard parsers, it is style-preserving, meaning it maintains all comments, indentations, whitespace, and internal element ordering during parsing and editing. This makes it ideal for tools that need to programmatically modify configuration files without destroying the user's formatting and comments.

    Key features:

    • Style Preservation: Preserves comments, whitespace, and indentation.
    • Editable API: Provides an intuitive API to access and modify the preserved elements.
    • Document Creation: Includes helpers to create new TOML documents from scratch.

  2. Understand tomlkit's style-preserving capabilities

    master

    TOML Kit is a 1.1.0-compliant TOML library designed to preserve the original layout of a document. Unlike standard parsers, it maintains:

    • Comments
    • Indentations
    • Whitespace
    • Internal element ordering

    These elements remain accessible and editable via the API, making it ideal for tools that need to modify TOML files without destroying user formatting.

    Limitation: Sub-table normalization

    There is one exception to the layout preservation: if a sub-table extends an array of tables out of order (e.g., a [fruit.apple.texture] header appearing after a [[fruit]] entry with an unrelated table in between), tomlkit will normalize that sub-table into the array's last element upon re-serialization. The data itself is preserved, but its physical position in the file may change.

  3. Modify existing TOML documents

    master

    You can modify a TOMLDocument using standard dictionary operations. You can add new keys to existing tables, create new tables using table(), or remove elements using .pop() or the del keyword.

    To add a new table:

    1. Create a table object using table().
    2. Populate it using .add(key, value) or dictionary-style assignment.
    3. Assign the table to a key in the main document.
    from tomlkit import parse, dumps, table

doc = parse("[table]\nfoo = 'bar'  # String\n")

# Modify existing key
doc["table"]["baz"] = 13

# Add a new table
tab = table()
tab.add("array", [1, 2, 3])
doc["table2"] = tab

print(dumps(doc))

  4. Install tomlkit

    master

    You can install tomlkit using pip or uv depending on your preferred package manager.

    Using uv

    If you are using uv, you can add it to your pyproject.toml or install it directly into your environment:

    uv add tomlkit
    uv pip install tomlkit

    Using pip

    For standard Python environments, use pip:

    pip install tomlkit
    pip install tomlkit

  5. Create a new TOML document from scratch

    master

    To build a TOML document programmatically, start with tomlkit.document(). You can build the structure using several methods:

    • doc.add(item): Adds elements like comments (comment("...")), newlines (nl()), or key-value pairs.
    • table(): Creates a new table object to hold grouped data.
    • doc["key"] = value: A shorthand for adding key-value pairs to the document or tables.
    • .comment("..."): Can be called on specific values/keys to attach comments to them.
    from tomlkit import document, comment, nl, table
from datetime import datetime, timezone

doc = document()
doc.add(comment("This is a TOML document."))
doc.add(nl())
doc.add("title", "TOML Example")

# Creating and adding a table
owner = table()
owner.add("name", "Tom Preston-Werner")
owner.add("organization", "GitHub")
owner.add("bio", "GitHub Cofounder & CEO\nLikes tater tots and beer.")
owner.add("dob", datetime(1979, 5, 27, 7, 32, tzinfo=timezone.utc))
owner["dob"].comment("First class dates? Why not?")

doc.add("owner", owner)

# Adding another table via dictionary assignment
database = table()
database["server"] = "192.168.1.1"
database["ports"] = [8001, 8001, 8002]
database["connection_max"] = 5000
database["enabled"] = True

doc["database"] = database

  6. Parse TOML strings with parse() or loads()

    master

    Use tomlkit.parse() or tomlkit.loads() to convert a TOML string into a TOMLDocument instance. The resulting TOMLDocument behaves like a standard Python dictionary, allowing you to access nested values using key lookups. Because tomlkit is style-preserving, calling dumps() on the parsed document will return a string that is identical to the original input (including comments and whitespace).

    from tomlkit import parse, dumps

content = """[table]
foo = 'bar'  # String
"""
doc = parse(content)

# Accessing data like a dictionary
assert doc["table"]["foo"] == "bar"

# Style-preserving output
assert dumps(doc) == content

  7. Manage parser state with Source.state context managers

    master

    The Source class includes a state property which returns a _StateHandler. This allows you to save the current position of the parser and restore it later, which is useful for backtracking during parsing.

    When using the state context manager:

    • Entering the context saves the current idx, current, and marker.
    • If an exception occurs or if restore=True is passed to the context manager, the Source cursor is reverted to the saved state upon exiting.

    Use save_marker=True if you also need to restore the marker position.

    source = Source("key = 'value' extra_data = 123")

# Save state at the start of a potential match
with source.state(save_marker=True, restore=True):
    source.mark()
    # ... attempt to parse something ...
    # If parsing fails or we want to backtrack, the 'with' block
    # ensures source.idx and source.marker return to where they were.
    pass

  8. Create TOML elements with the tomlkit public API

    master
    The tomlkit module provides top-level functions used to create individual TOML elements (such as tables, arrays, or strings) which can then be composed into a complete TOML document. Use these functions to programmatically construct TOML structures.

  9. Manipulate TOML items

    master
    The tomlkit.items module contains the core classes for representing various TOML data types (such as tables, arrays, strings, integers, etc.). These items are the building blocks of a TOML document and support style-preserving operations.

  11. Use Integer and Float items for arithmetic

    master
    The Integer and Float classes wrap Python's native numeric types but implement arithmetic operators (like __add__, __sub__, __mul__, etc.) that return new Integer or Float instances. This ensures that mathematical operations on TOML items preserve their Item status and associated Trivia.

  12. Define TOML keys with SingleKey and DottedKey

    master

    TOML keys can be 'bare' (unquoted) or 'quoted' (using Basic or Literal styles).

    • SingleKey: Represents a single part of a key. It automatically determines if a key should be bare or quoted based on its content.
    • DottedKey: Represents a key composed of multiple parts separated by dots (e.g., a.b.c).

    Use concat() on a SingleKey to create a DottedKey.