Loading TOML With Python

00:00 Load TOML With Python. In the next few sections of the course, you’ll fire up your Python interpreter and load TOML documents into Python. You’ve seen how the main use case for the TOML format is configuration files.

00:13 These are often written by hand, so in this section you’ll look at how you can read such configuration files with Python and work with them inside your project.

00:23 Since version 3.11, Python has been able to read TOML documents without any external dependencies. You simply have to import tomllib, and you can start working with TOML.

00:32 Older versions of the language will need to use a third-party dependency called tomli, which works from Python 3.7 through 3.10. The handy part of this as a developer is that the standard library version was essentially made by adopting the tomli code base into CPython, meaning that the only change needed is the import.

00:50 tomli and tomllib are compatible with each other. So if you’re working on Python between 3.7 and 3.10, or you know your project will be, then you’ll want to install the package into a virtual environment. On screen you can see how to do this on macOS and Linux,

01:20 and here you can see how to do it on Windows.

01:35 Even if you’re working on Python 3.11 or later and don’t need to use tomli, you will need to install a package later on, so you may want to create the virtual environment and activate it at this point in the course.

01:48 With all of this in place, you’ll just need to alter any code to import and use tomli instead of toml or tomllib, as in the example seen on screen.

01:58 One way to ensure that the code is consistent, regardless of which versions of Python you’re using and which library you’re using, is the import seen on screen.

02:07 It’s slightly more complicated, but it will mean the code will be consistent. It first tries to import tomllib, and if that fails, it will import tomli instead, but alias it to tomllib.

02:19 As the two libraries are compatible, you can now refer to tomllib in your code and it will work in all versions of Python 3.7 and up. It’s time to explore how you can read TOML files. Start by creating the TOML file seen on screen and saving it as tic_tac_toe.toml.

02:49 The tomllib module only exposes two functions, load() and loads(). You use these to load a TOML document from a file object and from a string respectively.

03:01 Start by using load() to read the file that you created.

03:08 First, you open the file using a context manager to handle any issues that may show up. Importantly, you need to open the file in binary mode by specifying mode="rb".

03:18 This allows the correct handling of the encoding of the TOML file. You stored the TOML configuration in a variable named config. Now go ahead and explore its contents.

03:30 The TOML document is represented as a dictionary in Python. All the tables and sub-tables in the TOML file show up as nested dictionaries in config. You can pick out individual values by following the keys into the nested dictionary.

03:52 If you already have the TOML document represented as a string, then you can use loads() instead of load(). Think of the trailing s in the function name as a mnemonic for string.

04:08 The following example passes the TOML document stored as toml_str.

04:20 Again, you’ll produce a dictionary with keys and values corresponding to the key-value pairs in the TOML document. Note that the TOML time and date types are represented by Python’s datetime types, and the TOML array is turned into a Python list.

04:36 You can see that the time zone information expressed in the .tzinfo attribute is attached to offset datetime UTC as expected.

04:48 Note that an offset datetime is a datetime with a specified time zone. Adding the time zone to a datetime means that you provide enough information to describe an exact moment in time, which is important in many applications that handle real-world data.

05:02 If you want to read more about how Python handles time zones then check out the zoneinfo module that was added in version 3.9 of Python, Real Python has you covered with this article.

05:14 Both load() and loads() convert TOML documents to Python dictionaries and you can use them interchangeably. Pick the one that’s most convenient for your use case.

05:25 As a final example, you’ll combine loads() with pathlib to reconstruct the tic-tac-toe configuration example.

05:46 One difference between load() and loads() is that you use regular strings and not bytes when you use the latter. In this case, tomllib assumes that you’ve correctly handled the encoding.

06:10 You’ve got started by loading and parsing your first TOML documents in Python. And in the next section of the course, you’ll take a look at the similarities and differences between TOML and Python types.