Working with TOML Files in Python

TOML files (Tom’s Obvious Minimal Language) are the brain-child of Mr. Tom Preston-Werner. They were developed as an alternative configuration file format that is easily readable by humans. The dictionary-like structure lends itself to usage with the Python programming language.

In this article we’ll explore the basics of working with TOML files using Python. Specifically, we’ll be using two libraries:

1. tomllib
2. tomlkit

Download both libraries with

pip install tomllib
pip install tomlkit

We’ll be using the tomllib libary just to load contents from a TOML file and the tomlkit for everything else.

The TOML File Structure

The structure of TOML files is detailed in the toml.io specification. The current version as of 2024 is 1.0.0.

TOML files support the following basic features:

• Key/Value Pairs
• Arrays
• Tables

The concept of TOML tables and key-value pairs are basically synonymous with Python dictionaries. The Arrays can be likened to Python lists.

We will go over how to add values to a TOML file for all the above features using Python in Building a TOML File with Python below. For now, here’s what each of the concepts look like:

Key/Value Pairs

key = "value"

Arrays

array_of_ints = [10, 20, 30]
array_of_strings = ["Hello", "I'm", "a", "TOML", "array"]
array_of_arrays = [ [10, 20, 30], ["Hello", "I'm", "a", "TOML", "array"] ]

Tables

[example-table-1]
table1integer: 1
table1string: "This is table 1"

[example-table-2]
table2integer: 2
table2string: "This is table 2"

Creating a TOML File

The most obvious way to create a TOML file is manually. Create a new file and type the following contents. Name it “example.toml”.

name = "example"
example_list = ["This", "is", "a", "list"]
version = 1

You can also create a TOML file programmatically with Python using the following code:

import tomlkit
from pathlib import Path

doc: tomlkit.TOMLDocument = tomlkit.document()

with open(Path(".") / "empty.toml", 'w') as toml_file:
    toml_file.write(tomlkit.dumps(doc))

toml_file.close()

First, we import the tomlkit library and the Path class from pathlib. Second, we create a variable called doc which holds a TOMLDocument object, defined in the tomlkit library. We’re going to use this later on to build the contents of a .toml document.

Third, we create a file called “empty.toml” in the current working directory and write the contents of the TOMLDocument object into the file. At this point there are no contents, so the file will be empty (hence the name).

Finally, we close the file with toml_file.close().

Building a TOML File with Python

To programmatically build a TOML file I’ve found that it’s best to use a dedicated library called tomlkit. The tomlkit library gives us the tools needed to create TOML file structure elements (key-value pairs, comments, arrays, tables, etc).

Our first example shows us how to start – with a TOMLDocument object.

import tomlkit

doc: tomlkit.TOMLDocument = tomlkit.document()

Adding a Key-Value Pair to a TOML File

To add a key-value pair, use the add(key, value) method of the TOMLDocument object:

doc.add("key", "value")

Adding a Comment to a TOML File

For single-line comments, use the following:

comment1 = tomlkit.comment("This is a comment")
doc.add(comment1)

Adding an Array to a TOML File

Since Python lists easily map to TOML array structures, it’s fairly simple to create a TOML array using a Python list. Use the following code:

toml_array: list = [10, 20, 30]
doc.add("my_toml_array", toml_array)

Adding a New Line to a TOML File

It’s often necessary to include new lines in your configuration files for a more ergonomic reading experience. Use the nl() method to add a new line:

doc.add(tomlkit.nl())

Adding a Table to a TOML File

Tables are sub-structures, onto which you append key-value pairs. For example, to construct a table named “My Table” with a key “table-number” holding value 1:

table = tomlkit.table()
table.append('table-number', 1)
doc.append('My Table', table)

Full Example

import tomlkit
from pathlib import Path

doc: tomlkit.TOMLDocument = tomlkit.document()

doc.add("key", "value")
comment1 = tomlkit.comment("This is a comment")
doc.add(comment1)
toml_array: list = [10, 20, 30]
doc.add("my_toml_array", toml_array)
doc.add(tomlkit.nl())

table = tomlkit.table()
table.append('table-number', 1)
doc.append('My Table', table)

with open(Path(".") / "write_toml.toml", 'w') as toml_file:
    toml_file.write(tomlkit.dumps(doc))

toml_file.close()

And the resulting TOML file:

key = "value"
# This is a comment
my_toml_array = [10, 20, 30]

["My Table"]
table-number = 1

Reading a TOML File Into a Python Dictionary

The easiest way I’ve found to read a TOML file is by using the tomllib library’s load() function.

Here is an example TOML file, called “example.toml”:

name = "example"
example_list = ["This", "is", "a", "list"]
version = 1

Here is the code to extract the contents of the TOML file into a dictionary:

import tomllib
from pathlib import Path

toml_filepath = Path(".") / "example.toml"
toml_dict: dict = {}

with open(toml_filepath, 'rb') as toml_file:
    toml_dict = tomllib.load(toml_file)

toml_file.close()
print(toml_dict)

The contents of the TOML file are stored in the toml_dict variable and can be accessed using basic Pythonic dictionary syntax.

For example, to get the version number:

version = toml_dict['version']

Editing a TOML File Using Python

The best method I’ve found for editing a TOML file in Python is to read the contents of the TOML file into a dictionary object (see above).

Then, use the dictionary object and basic Python syntax to update the value. Third, create another TOMLDocument instance by using the tomlkit library. Finally, dump everything into the original file using tomlkit.dumps().

For example, to modify the example.toml file’s version number from 1 to 2 we can use the following code:

import tomllib
import tomlkit
from pathlib import Path

toml_filepath = Path(".") / "example.toml"
toml_dict: dict = {}

# Open the example.toml file
with open(toml_filepath, 'rb') as toml_file:
    toml_dict = tomllib.load(toml_file)
toml_file.close()

# Modify the dictionary
toml_dict['version'] = 2

# Create a new document object based on modified toml_dict
doc: tomlkit.TOMLDocument = tomlkit.document()
for key in toml_dict.keys():
    doc.add(key, toml_dict[key])

# Dump the results into the original example file
with open(toml_filepath, 'w') as toml_file:
    toml_file.write(tomlkit.dumps(doc))

toml_file.close()

The resulting TOML file looks as follows, with the version number incremented by 1.

name = "example"
example_list = ["This", "is", "a", "list"]
version = 2

Article Corrections and Contributions

Did you know you can contribute to Quantastic Research articles? For contributions, fill out the Article Contribution Form. For corrections, see the Article Correction Form. Use the standard Contact Form for all other inquiries.