Python TOML

last modified January 29, 2024

In this article we show how to work with TOML configuration file format in Python. We use the tomllib module, which was introduced in Python 3.11.

TOML format

YAML (Tom's Obvious Minimal Language) is a human-readable data-serialization language. It is a minimal configuration file format that is easy to read.

TOML supports the following types:

key/value pairs
arrays
tables
inline tables
arrays of tables
ints and floats
booleans
dates and times

TOML files have the .toml extension.

Python tomllib module

This tomllib provides an interface for parsing TOML. It does not support writing to TOML files.

The module defines two functions. The tomllib.load parses TOML from a file. The tomllib.loads parses TOML from a string.

The following is a TOML to Python data conversion table.

TOML	Python
table	dict
string	str
integer	int
float	float
boolean	bool
local date-time	datetime.datetime
local date	datetime.date
local time	datetime.time
array	list

Python TOML simple example

The following is a simple TOML example.

simple.py

#!/usr/bin/python

import tomllib

source = """
name = "John Doe"
occupation = "gardener"
"""

data = tomllib.loads(source)

for e in data.items():
    print(e)

print('----------------------------')

for e in data.keys():
    print(e)

print('----------------------------')

for e in data.values():
    print(e)

In the program, we load TOML data from a string and print the loaded pairs, keys and values.

source = """
name = "John Doe"
occupation = "gardener"
"""

In the TOML string, we define two key/value pairs.

data = tomllib.loads(source)

We load TOML data from the string with tomllib.loads.

for e in data.items():
  print(e)

We iterate over the pairs using the items method.

for e in data.keys():
  print(e)

We iterate over the keys using the keys method.

for e in data.values():
  print(e)

Finally, we loop over the values using the values method.

$ ./simple.py
('name', 'John Doe')
('occupation', 'gardener')
----------------------------
name
occupation
----------------------------
John Doe
gardener

Python TOML read from file

We use the tomllib.load method to parse TOML from a file.

data.toml

# Simple TOML document

title = "Simple document"

[data]
enabled = true
words = ['sky', 'note', 'cup', 'toast', 'falcon']
vals = [2, 3, 1, 6, 5, 3, 9]

We have a TOML file.

title = "Simple document"

This is a TOML key/value pair.

[data]
enabled = true
words = ['sky', 'note', 'cup', 'toast', 'falcon']
vals = [2, 3, 1, 6, 5, 3, 9]

This is a TOML table.

read_file.py

#!/usr/bin/python

import tomllib

fname = 'data.toml'

with open(fname, 'rb') as f:
    
    data = tomllib.load(f)

    title = data.get('title')
    print(title)

    enabled = data.get('data')['enabled']
    print(enabled)

    words = data.get('data')['words']
    print(words)

    vals = data['data']['vals']
    print(vals)

We read the TOML data from a file.

data = tomllib.load(f)

We load the TOML data.

title = data.get('title')

We get the value of a pair with get.

enabled = data.get('data')['enabled']

From the TOML table called data, we get the enabled value.

words = data.get('data')['words']
print(words)

From the same table, we get the words array.

$ ./read_file.py
Simple document
True
['sky', 'note', 'cup', 'toast', 'falcon']
[2, 3, 1, 6, 5, 3, 9]

TOML array on multiple lines

TOML arrays can span multiple lines.

multiple.toml

words = [
  "small",
  "cup",
  "forest",
  "toast",
  "mold"
]

We define a words array.

multiple.py

#!/usr/bin/python

import tomllib

fname = 'multiple.toml'

with open(fname, 'rb') as f:

    data = tomllib.load(f)
    print(data['words'])
    print(data['words'][0])
    print(data['words'][1])

We parse the TOML file and print the array values.

$ ./multiple.py
['small', 'cup', 'forest', 'toast', 'mold']
small
cup

Python TOML type conversion

In the next example we show the TOML to Python type conversion.

types.toml

married = false
dob = 1999-09-20
weight = 58.5
siblings = 2
favcols = ['red', 'blue']

We have a few pairs with different types.

dtypes.py

#!/usr/bin/python

import tomllib

fname = 'types.toml'

with open(fname, 'rb') as f:

    data = tomllib.load(f)
    
    print(type(data['married']))
    print(type(data['dob']))
    print(type(data['weight']))
    print(type(data['siblings']))
    print(type(data['favcols']))

We parse the pairs and print the Python data type of each value. We use the built-in type function.

$ ./dtypes.py
<class 'bool'>
<class 'datetime.date'>
<class 'float'>
<class 'int'>
<class 'list'>

Python TOML decode error

A TOMLDecodeError is raised if a TOML document is invalid.

decode_error.py

#!/usr/bin/python

import tomllib

source = """
name = "John Doe"
occupation: "gardener"
"""

try:
    data = tomllib.loads(source)
    name = data['name']
    occupation = data['occupation']

    print(name)
    print(occupation)

except tomllib.TOMLDecodeError as e:
    print('Invalid TOML document')
    print(e)

In the example, we parse an invalid TOML document in a string.

$ ./decode_error.py
Invalid TOML document
Expected '=' after a key in a key/value pair (at line 3, column 11)

Source

Python tomllib — Parse TOML files

In this article we have worked with the TOML format in Python.

Author

My name is Jan Bodnar and I am a passionate programmer with many years of programming experience. I have been writing programming articles since 2007. So far, I have written over 1400 articles and 8 e-books. I have over eight years of experience in teaching programming.

List all Python tutorials.

Ebooks