Creating New TOML Documents

00:00 Create New TOML Documents.

00:03 You’ve seen how to quickly read and write TOML documents, and you’ve also noticed some of the limitations of toml_w in particular when it comes to formatting in the resulting TOML files.

00:12 In this section of the course, you’ll first explore how you can format TOML documents to make them easier to use for users, and then you’ll try out another library called tomlkit that you can use to take full control over your TOML documents.

00:27 In general, whitespace is ignored in TOML files. You can take advantage of this to make your configuration files well-organized, readable, and intuitive. Additionally, a hash symbol marks the rest of the line as a comment, and you should use comments liberally.

00:42 There’s no style guide for TOML documents in the sense that PEP 8 is a style guide for Python code, but the specification does include some recommendations while leaving some style aspects open for you to choose.

00:54 Some features in TOML are quite flexible. For example, you can define tables in any order you wish. Because the table names are fully qualified, you can even define a sub-table before its parent.

01:07 Furthermore, whitespace is ignored around keys. The two headers seen on screen start the same nested table. The recommendations in the TOML specification can be summarized as: Don’t abuse flexibility.

01:20 Keep your focus on consistency and readability, and you and your users will be happier. To see a list of styling options where you can reasonably make choices based on your personal preferences, check out the available configuration options for the Taplo formatter.

01:36 Here are some questions you can ponder: Indent sub-tables? Or rely on table headers to indicate structure? Align the equal signs in key-value pairs within each table?

01:46 Or always stick with one space on either side of the equal sign? Split long arrays to multiple lines? Or always keep them together on one line? Add a trailing comma after the last value in a multi-line array? Or leave it bare?

02:00 And order tables and keys semantically, or alphabetically?

02:04 Each of these choices comes down to personal taste, so feel free to experiment to find something you are comfortable with. But whatever you choose, it’s good to be consistent. For consistency, you can use a formatter such as Taplo in your projects and include its configuration file in your version control.

02:23 You may be able to integrate it into your editor as well.

02:27 Looking back at the previous questions, if you use tomli_w to write your TOML document, then the only question where you have a choice is how to order your tables and keys.

02:37 If you want more control over your TOML documents, then you need a different tool.

02:42 So next you’ll see how to use tomlkit, which gives you both more power and more responsibility.