Write TOML Documents With tomli_w

00:00 Write TOML Documents With tomli_w. The tomllib library in Python 3.11 and later doesn’t include dump and dumps, and there’s no tomlilib_w.

00:12 Instead, you can use tomli_w to write TOML on all versions of Python since 3.7. As the name indicates, tomli_w is related to tomli, the package that Python’s standard library implementation is based on.

00:25 It comes with two functions, dump and dumps that are designed to be more or less the opposite of load and loads.

00:33 You’ll need to install tomli_w into your virtual environment before you can use it.

00:44 Now, try to redo the example from the previous section of the course.

01:11 There are no surprises here. tomli_w writes the same TOML document that the handwritten dumps function did previously. Additionally, the third-party library supports all the features that you didn’t implement, including times and dates, inline tables, and arrays of tables.

01:28 dumps writes to a string that you can continue to process. If you want to store your new TOML document directly to disk, then you can call dump instead. As with load, you need to pass in a file pointer opened in binary mode.

01:42 You can do this by continuing the previous REPL session.

01:56 This stores the config data structure to the file, tic-tac-toe-config.toml. Take a look at the newly created file in an editor.

02:07 You find all the familiar tables and key-value pairs where you expect them.

02:13 tomllib, tomli and tomli_w are quite basic with somewhat limited functionality while implementing full support for TOML version 1.0.

02:23 In general, you can round-trip your data structures through TOML as long as they’re compatible.

02:39 Here, you confirm that you are able to recover data after first dumping to TOML and then loading back into Python. One reason you shouldn’t use TOML for data serialization is that there are many data types that aren’t supported.

02:52 For example, if you have a dictionary with numeric keys, then tomli_w rightfully refuses to convert it to TOML.

03:10 The error message isn’t very descriptive, but the problem is that non-string keys such as 1 and 2 aren’t supported in TOML. Earlier, you learned that tomllib discards comments.

03:20 In addition, you can’t distinguish between literal strings, multi-line strings, and regular strings in the dictionary that’s returned by load or loads altogether.

03:29 This means that you lose some meta information when you pass a TOML document and write it back.

03:53 The TOML content remains the same, but the output is different from what you passed in. The parent table [nested] isn’t explicitly included in the output, and the comment is gone.

04:05 Furthermore, the equal sign inside [nested.table] aren’t aligned any longer, and weird_string isn’t represented as a literal multi-line string.

04:15 Note that you can use the multi-line string parameter to instruct tomli_w to use multi-line strings where appropriate.

04:34 But in conclusion, tomli_w is a great option for writing TOML documents as long as you don’t need a lot of control over the output. In the next section of the course, you’ll take a look at creating TOML documents from scratch and other features of the TOML format that you may want to make use of.