# 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**](https://toml.io/en/v0.5.0) (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.

```ini
# 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.

```json
{
  "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](https://peps.python.org/pep-0621/) 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.

```python
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.

```bash
{'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.

```python
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.

```bash
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.

```python
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.

```bash
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.

```python
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.

```python
{'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](https://geekpython.in/python-split-method).

✅[Map a function to each item in an iterable using the map() function](https://geekpython.in/map-function-in-python).

✅[Serialize and deserialize Python objects using the pickle module](https://geekpython.in/pickle-module-in-python).

✅[Why if \_\_name\_\_ == ‘\_\_main\_\_’ is used in Python programs](https://geekpython.in/understanding-if-__name__-__main__-in-python-programs)?

✅[Create a WebSocket server and client in Python](https://geekpython.in/build-websocket-server-and-client-using-python).

✅[Upload and display images on the frontend using Flask](https://geekpython.in/render-images-from-flask).

---

**That's all for now**

**Keep Coding✌✌**