Timing and Arrays

00:00 Times, Dates and Arrays. TOML supports defining times and dates directly in your documents. You can choose between four different representations, each with its own specific use case: offset date-times, local date-times, a local date, and a local time.

00:22 An offset date-time is a timestamp with time zone information representing a specific instant in time. A local date-time is a timestamp without time zone information.

00:34 A local date is a date without any time zone information. You typically use this to represent a full day. A local time is a time without any date or time zone information.

00:45 You can use a local time to represent a time of day.

00:50 TOML bases its representation of times and dates on RFC 3339. This document defines a time and date format that’s commonly used to represent timestamps on the internet.

01:01 A fully defined timestamp would look as seen on screen. It’s composed of several fields split by different separators. An offset date-time is a timestamp that includes the offset information.

01:14 A local date-time is a timestamp that doesn’t include this. Local timestamps are also called naive timestamps.

01:23 The fields are detailed on screen.

01:28 In TOML, the microsecond field is optional for all date, time, and time types. You’re also allowed to replace the T that separates the date and time with a space. On screen, you can see examples of the timestamp-related types.

01:46 Note that you can’t wrap the timestamp values within quotation marks as that would turn them into text strings. These different time and date types give you a fair amount of flexibility. If you have use cases that aren’t covered by these, for example, if you want to specify a time interval such as one day, then you can use strings and use your application to properly process those.

02:09 A final data type that TOML supports is arrays, and these allow you to combine several other values in a list. TOML arrays represent an ordered list of values.

02:19 You can specify them using square brackets, so they resemble a Python list. Here, the value of packages is an array containing four string elements.

02:30 You can use any TOML data type, including other arrays inside arrays, and one array can contain different data types. You’re allowed to specify an array over several lines, and you can use a trailing comma after the last element in the array.

02:46 All of the examples seen on screen are valid TOML arrays. You can see that potpourri is an array with four elements with different data types, while skiers is an array containing three strings.

02:57 The final array, players, adapts your earlier example to represent two inline tables as elements in an array. Note that players is defined over four lines, and there’s an optional comma after the last inline table.

03:11 While this last example shows one way you can create arrays of tables, as you saw previously, inline tables don’t scale well. If you want to represent an array of tables where the tables are bigger, you should use a different syntax.

03:25 In general, you should express an array of tables by writing table headers inside double square brackets. This syntax isn’t necessarily pretty, but it is effective.

03:36 You can represent players from the example as seen on screen. This array of tables is equivalent to the array of inline tables you wrote previously.

03:45 The double square brackets define an array of tables instead of a regular table. You need to repeat the array name for each nested table inside the array. On screen is a more extensive example, an excerpt from a TOML document listing questions for a quiz application.

04:03 Here the Python table has two keys, label and questions. The value of questions is an array of tables with two elements.

04:11 Each element is a table with three keys, question, answers, and alternatives.

04:18 You’ve now seen all the data types that TOML has to offer. In addition to simple data types like strings, numbers, Booleans, times, and dates, you can also combine and organize your keys and values with tables and arrays.

04:31 There are some details and edge cases that we’ve glossed over here, and you can learn all the details in the TOML specification.

04:40 With the groundwork of knowledge of the TOML format under your belt, in the next section of the course, you’ll start working with TOML files in Python by seeing how to load TOML data.