TOML for configuration

After the recent Python release 3.11 on 24th October 2022, the TOML file format has gained a lot more traction. Python now supports parsing TOML file built-in by adding tomllib in the standard library. TOML configuration has been around gradually finding its usefulness. It has been used in Cargo to store package configuration(https://doc.rust-lang.org/cargo/guide/creating-a-new-project.html). It has been also used in Python packaging (https://peps.python.org/pep-0518/). Here’s a complete list https://github.com/toml-lang/toml/wiki#projects-using-toml.

What is TOML?

It is a configuration file format that is intended to be human-readable. It is explicitly made for configurations and not for serializing data structures. The defined semantics for TOML is very simple and easy to read.

It supports the following data types:

• Key/Value Pairs

Key/Value Pairs

• Arrays

• Tables

• Inline tables

• Arrays of tables

• Integers & Floats

• Boolean

• Dates & Times, with optional offsets

TOML with Python

Python in a recent release has provided support for TOML in release 3.11. It supports loading TOML format from a file or a string. It has 2 simple functions load and loads.

load_settings.py

import logging
import tomllib

logger = logging.getLogger(__name__)

def load():
    with open('path/to/file/setting.toml', 'rb') as f:
        t = tomllib.load(f)
        logger.debug('Settings loaded successfuly')
    return t

SETTINGS = load()

setting.toml

[app_name]
name = "My app name"
version = "1.0.0"
debug = true
# comments

Above are 2 files, load_settings.py, and settings.toml, creates a basic setup for loading toml. But there are a few things important without which this code will not work.

So this will only work on 3.11. import tomllib is a built-in module as on Python 3.11. So this will only work on 3.11 or later versions.

tomllib.load requires the file to be opened in ‘rb’ mode. ‘r’ stands for read mode and ‘b’ stands for byte. In ‘rb’ mode python opens the file in read mode and returns bytes on read. open function by default returns string and load function expects bytes.

Another useful thing to note is that we only need with while we load the configurations. We should close the file immediately.

Now that we have configurations loaded, we can access these configurations by importing load_settings the module.

from load_settings import SETTINGS

#... feature logic
print(SETTINGS['app_name']['name'])

tomllib.load and tomllib.loads returns a dictionary and can be easily used.

Conclusion

TOML is an easy and readable format to maintain configuration. And it can be easily implemented and it is supported by default in the latest python. It is used in multiple projects and it's increasingly becoming a convenient choice.