Learning About Data Types in TOML

00:00 Data Types in TOML. TOML is built around key-value pairs that map nicely to hash table data structures. TOML values have different types and every value must be one of the types seen on screen.

00:15 Additionally, you can use tables and arrays of tables as collections that organize several key-value pairs. You’ll learn more about these later on. TOML supports comments with the same syntax as Python.

00:29 A hash symbol marks the rest of the line as a comment. Use comments to make your configuration files easy to understand and use for yourself and your users.

00:39 You’ll see all the different elements of TOML in this course, but some details and edge cases will be glossed over. Check out TOML’s documentation if you’re interested in the fine print.

00:53 As noted, key-value pairs are the basic building blocks in a TOML document. You specify them with the syntax seen on screen where the key is separated from the value with an equal sign.

01:05 This is a valid TOML document with one key-value pair. In this example, greeting is the key and “Hello, TOML!” is the value. Values have types.

01:16 In this example, the value is a text string. You’ll learn more about the different value types soon.

01:23 Keys are always interpreted as strings, even if quotation marks don’t surround them. Consider the example seen on screen. Here, 42 is a valid key, but it’s interpreted as a string, not a number.

01:37 Usually you want to use bare keys. These are keys that consist only of ASCII letters and numbers, as well as underscores and dashes. All such keys can be written without quotation marks as seen.

01:51 TOML documents must be encoded in UTF-8 Unicode. This gives you great flexibility when representing your values. Despite the restrictions on bare keys, you can also use Unicode when spelling out your keys, but this comes at a cost.

02:06 To use Unicode keys, you must add quotation marks around them. All these keys contain characters that aren’t allowed in bare keys: the dot, Norwegian characters, and a space.

02:18 You are allowed to use quotation marks around any key, but in general, you want to stick to bare keys that don’t use or require quotation marks.

02:28 Dots play a special role in TOML keys. You can use dots in quoted keys, but in that case, they’ll trigger grouping by splitting the dotted key at each dot.

02:39 Consider the example seen on screen. Here you specify two dotted keys. Since they both start with player_x, the key symbol and color will be grouped together inside a section named player_x.

02:51 You’ll learn more about this when you start exploring tables.

02:57 TOML uses familiar syntax for the basic data types. Coming from Python, you’ll recognize strings, integers, floats, and Booleans. The immediate difference between TOML and Python is that TOML’s Boolean values are lowercase.

03:12 A TOML string should typically use double quotation marks. Inside strings, you can escape special characters with the help of backslashes. You can see how the strings seen on screen will be interpreted.

03:26 You can also specify TOML strings using single quotation marks. Single-quoted strings are called literal strings and behave similarly to raw strings in Python.

03:35 Nothing is escaped and interpreted in a literal string, and you can see the effect of this on screen. Finally, TOML strings can also be specified using triple quotation marks, whether double or single. Triple-quoted strings allow you to write a string over multiple lines similar to a Python multi-line string. Control characters, including literal new lines, aren’t allowed in basic strings, but you can use n to represent a new line inside a basic string.

04:04 You must use a multi-line string if you want to format your strings over several lines, and you can also use triple-quoted strings. In addition to being multi-line as seen on screen.

04:15 these are the only way to include a single quotation mark inside a literal string. You should be careful with special characters when you create TOML documents inside your Python code because Python will also interpret the special characters. On screen, you can see a valid TOML document. Here, the value of numbers is a string that split over three lines.

04:37 You may try to represent the same document in Python as seen,

04:47 but this won’t work because Python parses the backslash characters and creates an invalid TOML document. You need to keep the special characters away from Python by using raw strings.

05:02 This string represents the same TOML document as your original one.

05:08 Numbers in TOML are either integers or floating-point numbers. Integers represent whole numbers and are specified as plain numeric characters. As in Python, you can use underscores to enhance readability.

05:23 Floating-point numbers represent decimal numbers and include an integer part, a dot representing the decimal point, and a fractional part. Floats can use scientific notation to represent very small or very large numbers.

05:36 TOML also supports special float values such as infinity and NaN.

05:42 The TOML specification requires that integers at least are represented as 64-bit signed integers. Python handles arbitrarily large integers but only ones with up to about 19 digits are guaranteed to work on all TOML implementations.

05:57 TOML is a configuration file format, not a programming language. Expressions like one plus two are not supported, only literal numbers. Non-negative integer values may also be represented as hexadecimal, octal, or binary values as seen. Boolean values are represented as true and false, which must be lowercase.

06:21 TOML also includes several time and date types. Before you explore those though, in the next section of the course, you’ll see how you can use tables to organize and structure your key-value pairs.