Working With TOML Files in Python

We use different configuration file formats to store configuration data for our software systems. In this article, we will discuss how to work with TOML configuration files in Python.

What is The TOML File Format?

TOML stands for Tom’s Obvious, Minimal Language. It is a file format used for storing configuration data. TOML file format is easy to read and parse by both humans and machines. It was designed to be a more readable alternative to other configuration file formats like JSON and XML.

TOML files are structured using key-value pairs. Here, keys are separated from their values by an equals sign, and each key-value pair is separated from the next by a new line. We use Tables to group related key-value pairs together, which are indicated by square brackets.

A sample TOML file will be as follows.

[employee]
name = "John Doe"
age = 35

[job]
title = "Software Engineer"
department = "IT"
years_of_experience = 10

[address]
street = "123 Main St."
city = "San Francisco"
state = "CA"
zip = 94102

The above TOML file contains three tables: employee, job, and address. All the tables have several key-value pairs associated with them. 

• The name key in the employee table has a value of "John Doe", and the age key has a value of 35. 
• The job table has three keys: title, department, and years_of_experience, which respectively have the values "Software Engineer", "IT", and 10. 
• The address table has four keys: street, city, state, and zip, which respectively have the values "123 Main St.", "San Francisco", "CA", and 94102.

Looking at the structure, you can observe that the TOML file format is somewhat similar to the INI file format. However, the naming conventions are different for the elements in the file.

Having discussed the basic structure of a TOML file, let us discuss how to create, read, and edit a toml file in Python. For this task, we will use the toml module. You can install the toml module by executing the following command in the command-line terminal.

pip install toml

Create a TOML Configuration File in Python

To create a toml configuration file, we will use the dump() method defined in the toml module. The syntax for the dump() method is as follows.

toml.dump(python_obj, file_ptr,)

Here, python_obj is the Python object whose data we want to store in the configuration file. The parameter file_ptr takes a file pointer as its input argument. After execution, the dump() method writes the data to the file referred to by file_ptr.

To create a toml file in Python, we will use the following steps.

• First, we will create an empty toml file. For this, we will open a file in write mode using the open() function. The open() function takes the filename as its first input argument and the Python literal “w” as its second input argument. After execution, it returns a file pointer.
• Next, we will create a Python dictionary with all the data that we need to convert to the toml format. 
• After creating the dictionary, we will use the dump() function to write the data to the toml file. For this, we will pass the dictionary as the first input argument and the file pointer as the second input argument to the dump() method.
• Finally, we will close the toml file using the close() method.

After executing the above steps, we can easily create a toml configuration file in Python. You can observe this in the following example.

import toml
file=open("employee.toml","w")
data_dict={
    "employee": {
        "name": "John Doe",
        "age": 35
    },
    "job": {
        "title": "Software Engineer",
        "department": "IT",
        "years_of_experience": 10
    },
    "address": {
        "street": "123 Main St.",
        "city": "San Francisco",
        "state": "CA",
        "zip": 94102
    }
}
toml.dump(data_dict,file)
file.close()

The output file looks as follows.

Instead of creating a file, we can also create a toml string. For this, we will use the dumps() function defined in the toml module. The dumps() method takes the Python dictionary as its input argument and returns a toml string. You can observe this in the following example.

import toml
data_dict={
    "employee": {
        "name": "John Doe",
        "age": 35
    },
    "job": {
        "title": "Software Engineer",
        "department": "IT",
        "years_of_experience": 10
    },
    "address": {
        "street": "123 Main St.",
        "city": "San Francisco",
        "state": "CA",
        "zip": 94102
    }
}
print("The data dictionary is:")
print(data_dict)
toml_string=toml.dumps(data_dict)
print("The toml string is:")
print(toml_string)

Output:

The data dictionary is:
{'employee': {'name': 'John Doe', 'age': 35}, 'job': {'title': 'Software Engineer', 'department': 'IT', 'years_of_experience': 10}, 'address': {'street': '123 Main St.', 'city': 'San Francisco', 'state': 'CA', 'zip': 94102}}
The toml string is:
[employee]
name = "John Doe"
age = 35

[job]
title = "Software Engineer"
department = "IT"
years_of_experience = 10

[address]
street = "123 Main St."
city = "San Francisco"
state = "CA"
zip = 94102

Read a TOML File in Python

To read a toml file in Python, we can use the load() method defined in the toml module. The load() method takes the file name of the toml file as its input argument and returns a Python dictionary containing the data from the file. You can observe this in the following example.

import toml
data=toml.load("employee.toml")
print("The data from toml file is:")
print(data)

Output:

The data from toml file is:
{'employee': {'name': 'John Doe', 'age': 35}, 'job': {'title': 'Software Engineer', 'department': 'IT', 'years_of_experience': 10}, 'address': {'street': '123 Main St.', 'city': 'San Francisco', 'state': 'CA', 'zip': 94102}}

Instead of a file, you can also read a toml string. For this, you can use the loads() method defined in the toml module. The loads() method takes the toml string as its input and returns a Python dictionary containing the data from the input string. You can observe this in the following example.

import toml
toml_string="""[employee]
name = "John Doe"
age = 35

[job]
title = "Software Engineer"
department = "IT"
years_of_experience = 10

[address]
street = "123 Main St."
city = "San Francisco"
state = "CA"
zip = 94102"""
print("The toml string is:")
print(toml_string)
data=toml.loads(toml_string)
print("The data from toml string is:")
print(data)

Output:

The toml string is:
[employee]
name = "John Doe"
age = 35

[job]
title = "Software Engineer"
department = "IT"
years_of_experience = 10

[address]
street = "123 Main St."
city = "San Francisco"
state = "CA"
zip = 94102
The data from toml string is:
{'employee': {'name': 'John Doe', 'age': 35}, 'job': {'title': 'Software Engineer', 'department': 'IT', 'years_of_experience': 10}, 'address': {'street': '123 Main St.', 'city': 'San Francisco', 'state': 'CA', 'zip': 94102}}

Update a TOML file in Python

To add, update, or delete data from a toml configuration file, we can use the following steps.

• First, we will read the configuration file into a Python dictionary using the load() method.
• Then, we will modify the dictionary as per the requirements to add, update, or delete data from the configuration file.
• Finally, we will write the dictionary back to the toml file using the dump() method.

By using the above steps, you can easily edit, update and delete data from a toml configuration file in Python.

Advantages of Using TOML File Format

There are many configuration file formats like yaml,xml, json, ini, and other file formats apart from the toml file format. Then, why should some use the toml file format? Following are some of the advantages of using the toml file format for storing configuration files.

1. Easy to read and write: TOML files are designed to be easy for humans to read and write. It has a simple, intuitive, and unambiguous syntax. This makes it easy to create and edit configuration files without needing specialized tools or knowledge.
2. Less error-prone: The TOML format is less error-prone than other formats because it enforces strict rules for key-value pairs, data types, and nesting. This reduces the risk of syntax errors, typos, and other mistakes that can cause problems in your code.
3. More flexible: TOML supports a wider range of data types and structures than other formats, including arrays, tables, and inline tables. This makes it more flexible and adaptable to different use cases and scenarios.
4. Cross-language compatibility: TOML has libraries and tools available for many programming languages, including Python, Ruby, Rust, and more. This makes it easy to work with TOML files across different platforms and programming languages.

Conclusion

In this article, we have discussed how to work with toml configuration files in Python. We discussed how to create, read, and update toml configuration files. We also discussed the advantages of toml file format over some other file formats. 

To learn more about Python programming, you can read this article on the Python finally keyword. You might also like this article on custom JSON encoders in Python.

I hope you enjoyed reading this article. Stay tuned for more informative articles. 

Happy Learning!