How to Parse TOML in Python

How to parse TOML in Python

Parsing TOML (Tom's Obvious, Minimal Language) files is a common requirement in many Python projects, as TOML has become a popular configuration file format due to its simplicity and readability. In this article, we will explore how to parse TOML files in Python using the toml library, which is the official Python implementation of the TOML specification.

Quick Example

import toml

# Load the TOML file
with open('example.toml', 'r') as f:
    toml_string = f.read()

# Parse the TOML string
data = toml.loads(toml_string)

# Access the parsed data
print(data['title'])  # Output: "TOML Example"

Assuming you have a example.toml file with the following contents:

title = "TOML Example"

You can install the toml library using pip:

pip install toml

Step-by-Step Breakdown

Let's walk through the code line by line:

import toml: We import the toml library, which provides the functionality to parse TOML files.
with open('example.toml', 'r') as f:: We open the example.toml file in read-only mode ('r') using a with statement, which ensures the file is properly closed when we're done with it.
toml_string = f.read(): We read the contents of the file into a string variable toml_string.
data = toml.loads(toml_string): We use the toml.loads() function to parse the TOML string into a Python dictionary. The loads() function takes a TOML string as input and returns a Python dictionary representing the parsed data.
print(data['title']): We access the parsed data using the dictionary key 'title' and print its value.

Handling Edge Cases

Empty/null input

If the input TOML string is empty or null, the toml.loads() function will raise a toml.TomlDecodeError exception. You can handle this case by wrapping the toml.loads() call in a try-except block:

try:
    data = toml.loads(toml_string)
except toml.TomlDecodeError:
    print("Error: Empty or invalid TOML input")

Invalid input

If the input TOML string is invalid (e.g., syntax errors), the toml.loads() function will also raise a toml.TomlDecodeError exception. You can handle this case similarly to the empty/null input case.

try:
    data = toml.loads(toml_string)
except toml.TomlDecodeError:
    print("Error: Invalid TOML input")

Large input

If the input TOML string is very large, you may encounter performance issues or memory errors. In such cases, you can use the toml.load() function instead, which parses the TOML file in a streaming fashion:

with open('example.toml', 'r') as f:
    data = toml.load(f)

This approach can help reduce memory usage and improve performance for large TOML files.

Unicode/special characters

TOML supports Unicode characters, and the toml library handles them correctly. However, if you encounter issues with special characters, you can specify the encoding when opening the file:

with open('example.toml', 'r', encoding='utf-8') as f:
    toml_string = f.read()

Common Mistakes

Mistake 1: Using `toml.loads()` with a file object

# Wrong code
with open('example.toml', 'r') as f:
    data = toml.loads(f)

# Corrected code
with open('example.toml', 'r') as f:
    toml_string = f.read()
    data = toml.loads(toml_string)

Mistake 2: Not handling `TomlDecodeError` exceptions

# Wrong code
data = toml.loads(toml_string)

# Corrected code
try:
    data = toml.loads(toml_string)
except toml.TomlDecodeError:
    print("Error: Invalid TOML input")

Mistake 3: Using `toml.load()` with a string

# Wrong code
data = toml.load(toml_string)

# Corrected code
data = toml.loads(toml_string)

Performance Tips

Use toml.load() for large files: As mentioned earlier, toml.load() parses the TOML file in a streaming fashion, which can help reduce memory usage and improve performance for large files.
Use toml.loads() with a string: If you have a TOML string in memory, use toml.loads() to parse it, as it is faster than reading the string from a file.
Avoid parsing TOML files repeatedly: If you need to access the same TOML file multiple times, consider parsing it once and storing the parsed data in memory to avoid repeated parsing overhead.

FAQ

Q: What is the difference between `toml.loads()` and `toml.load()`?

A: toml.loads() parses a TOML string into a Python dictionary, while toml.load() parses a TOML file into a Python dictionary.

Q: How do I handle invalid TOML input?

A: You can handle invalid TOML input by wrapping the toml.loads() or toml.load() call in a try-except block and catching the toml.TomlDecodeError exception.

Q: Can I use TOML with Python 2.x?

A: The toml library supports Python 2.7 and later. However, it is recommended to use Python 3.x for new projects.

Q: How do I parse a TOML file with a non-standard encoding?

A: You can specify the encoding when opening the file using the encoding parameter, e.g., open('example.toml', 'r', encoding='utf-16').

Q: Can I use TOML with other Python libraries?

A: Yes, TOML can be used with other Python libraries, such as json or yaml, to handle different configuration file formats.

How to Parse TOML in Python