Parse TOML files Using tomllib Module in Python

You might have seen files with the .toml extension in programming projects. What is that TOML?

TOML (Tom's Obvious Minimal Language) files can be used to store application metadata in an easily readable format. Its format is extremely simple due to its minimal syntax.

The TOML file, like the JSON file in web development, is used to store application-specific configuration data, however, the syntax varies and is often preferred in projects where human readability and simplicity are prioritized.

In this article, you will learn how to parse TOML files with the Python standard library tomllib.

TOML File

TOML file contains data in key-value pairs and has native types such as string, integer, float, booleans, tables, arrays, and more.

Here's an example of a TOML file.

# This is a TOML configuration file

title = "TOML Config File"

[author]
name = "John Doe"
dob = 1979-05-27T07:32:00-08:00

[app]
app_name = "Tomparse"
version = 0.10
site."google.com" = true

[app.dependency]
libs = ["tomllib", "tomli"]

[database]
enabled = true
ports = [ 8000, 8001, 8002 ]
data = [ ["delta", "phi"], [3.14] ]
temp_targets = { cpu = 79.5, case = 72.0 }

In the above file, title, owner, app, app.dependency, and database are the keys, and name, dob, app_name, version, etc., are the subkeys.

You can see values ["tomllib", "tomli"], [ ["delta", "phi"], [3.14] ] are array and array of tables respectively and value { cpu = 79.5, case = 72.0 } is inline table.

If the above file is put into JSON land, it would give the following structure.

{
  "title": "TOML Config File",
  "author": {
    "name": "John Doe",
    "dob": "1979-05-27T15:32:00.000Z"
  },
  "app": {
    "app_name": "Tomparse",
    "version": 0.1,
    "site": {
      "google.com": true
    },
    "dependency": {
      "libs": [
        "tomllib",
        "tomli"
      ]
    }
  },
  "database": {
    "enabled": true,
    "ports": [
      8000,
      8001,
      8002
    ],
    "data": [
      [
        "delta",
        "phi"
      ],
      [
        3.14
      ]
    ],
    "temp_targets": {
      "cpu": 79.5,
      "case": 72
    }
  }
}

Now you can understand how TOML syntax works if you haven't worked with the TOML files before.

You can use TOML for storing Python project metadata. See PEP 621 for more details.

tomllib - Parsing TOML Files

With the release of Python 3.11, the tomllib is added to the Python standard library to parse the TOML files using Python. This library is intended to read TOML files.

Having said that, the tomllib has only two functions: reading TOML from a file and loading TOML from a string.

Functions

tomllib.load(fp , parse_float=float)

The load() function reads a TOML file.

Parameters:

fp - A readable and binary file object. You can pass it positionally, but not as a keyword argument.
parse_float - You can specify a custom function for parsing the float in the TOML file. It defaults to using Python's float() function. This is a keyword-only argument.

Return value:

The load() function returns the TOML file content in dictionary format.

tomllib.loads(s, parse_float=float)

The loads() function loads the TOML from a string object.

Parameters:

s or string - A string object that contains the TOML document.
parse_float - It is the same as the load() function's parse_float.

Return value:

It also returns the results in dictionary format.

Parsing a TOML File

Here's a config.toml file that contains some configuration data of an application written in TOML. You'll use the tomllib's load() function to parse the file.

import tomllib

# Opening a TOML file and reading in binary mode
with open("config.toml", "rb") as tfile:
    # Parsing TOML file content
    result = tomllib.load(tfile)
    print(result)

When you run the code, you'll get the file's content in a dictionary format.

{'title': 'TOML Config File', 'owner': {'name': 'John Doe', 'dob': datetime.datetime(1979, 5, 27, 7, 32, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=57600)))}, 'app': {'app_name': 'Tomparse', 'version': 0.1, 'site': {'google.com': True}, 'dependency': {'libs': ['tomllib', 'tomli']}}, 'database': {'enabled': True, 'ports': [8000, 8001, 8002], 'data': [['delta', 'phi'], [3.14]], 'temp_targets': {'cpu': 79.5, 'case': 72.0}}}

Since the data is in dictionary format you can separate the keys and values from the data.

import tomllib

# Opening a TOML file and reading in binary mode
with open("config.toml", "rb") as tfile:
    # Parsing TOML file content
    result = tomllib.load(tfile)
    for key, value in result.items():
        print(f"Key: {key}")
        print(f"Value: {value}")

Now when you run this code, you'll get the following result.

Key: title
Value: TOML Config File
Key: author
Value: {'name': 'John Doe', 'dob': datetime.datetime(1979, 5, 27, 7, 32, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=57600)))}
Key: app
Value: {'app_name': 'Tomparse', 'version': 0.1, 'site': {'google.com': True}, 'dependency': {'libs': ['tomllib', 'tomli']}}
Key: database
Value: {'enabled': True, 'ports': [8000, 8001, 8002], 'data': [['delta', 'phi'], [3.14]], 'temp_targets': {'cpu': 79.5, 'case': 72.0}}

Exception Handling

The tomllib includes a TOMLDecodeError class that can handle errors encountered while decoding the TOML document.

import tomllib

# Opening a TOML file and reading in binary mode
try:
    with open("config.toml", "rb") as tfile:
        # Parsing TOML file content
        result = tomllib.load(tfile)
        for key, value in result.items():
            print(f"Key: {key}")
            print(f"Value: {value}")

except tomllib.TOMLDecodeError as e:
    print(e)

As you can see, the code is wrapped in a try-except block, and any errors are handled by the tomllib.TOMLDecodeError in the except block.

Expected '=' after a key in a key/value pair (at line 12, column 18)

Loading TOML from String

Assume you have a string with a TOML document. How do you parse that TOML? To achieve your desired result, use the tomllib.loads() function.

import tomllib

my_toml = """
[app]
app_name = "Tomparse"
version = 0.1
site."google.com" = true

[app.dependency]
libs = ["tomllib", "tomli"]
"""

load_toml = tomllib.loads(my_toml)
print(load_toml)

The variable my_toml contains a string of TOML, which is passed to the tomllib.loads() function.

As usual, this code will return a dictionary and you'll get the following result.

{'app': {'app_name': 'Tomparse', 'version': 0.1, 'site': {'google.com': True}, 'dependency': {'libs': ['tomllib', 'tomli']}}}

Conclusion

So, if you write a configuration file or document in TOML and then want to parse it, you'll know what to do.

You can use the tomllib library, which was included in the Python standard library with the release of Python 3.11. This library includes functions that can be used to read TOML files.

🏆Other articles you might be interested in if you liked this one

✅Split your string into an array of words using the split() method in Python.

✅Map a function to each item in an iterable using the map() function.

✅Serialize and deserialize Python objects using the pickle module.

✅Why if __name__ == ‘__main__’ is used in Python programs?

✅Create a WebSocket server and client in Python.

✅Upload and display images on the frontend using Flask.

That's all for now

Keep Coding✌✌