0
# Advanced Types
1

2
Specialized TOML types including dates, times, keys, and complex data structures with full TOML 1.0.0 compliance. These types handle edge cases and advanced TOML features.
3

4
## Capabilities
5

6
### Date and Time Types
7

8
Create TOML date, time, and datetime items with RFC3339 compliance and timezone support.
9

10
```python { .api }
11
def date(raw: str) -> Date:
12
    """
13
    Create a TOML date from RFC3339 string.
14
    
15
    Parameters:
16
    - raw: Date string in format YYYY-MM-DD
17
    
18
    Returns:
19
    Date item representing the date
20
    
21
    Raises:
22
    ValueError: If string is not a valid date format
23
    """
24

25
def time(raw: str) -> Time:
26
    """
27
    Create a TOML time from RFC3339 string.
28
    
29
    Parameters:
30
    - raw: Time string in format HH:MM:SS or HH:MM:SS.fff
31
    
32
    Returns:
33
    Time item representing the time
34
    
35
    Raises:
36
    ValueError: If string is not a valid time format
37
    """
38

39
def datetime(raw: str) -> DateTime:
40
    """
41
    Create a TOML datetime from RFC3339 string.
42
    
43
    Parameters:
44
    - raw: Datetime string with optional timezone (ISO 8601/RFC3339)
45
    
46
    Returns:
47
    DateTime item representing the datetime
48
    
49
    Raises:
50
    ValueError: If string is not a valid datetime format
51
    """
52
```
53

54
### Key Types
55

56
Create and manipulate TOML keys including simple keys and dotted key paths for nested access.
57

58
```python { .api }
59
def key(k: str | Iterable[str]) -> Key:
60
    """
61
    Create a TOML key from string or key path.
62
    
63
    Parameters:
64
    - k: Single key string or iterable of strings for dotted key
65
    
66
    Returns:
67
    Key object (SingleKey or DottedKey)
68
    """
69

70
def key_value(src: str) -> tuple[Key, Item]:
71
    """
72
    Parse a key-value pair from string.
73
    
74
    Parameters:
75
    - src: String containing "key = value" pair
76
    
77
    Returns:
78
    Tuple of (Key, Item) representing the parsed pair
79
    
80
    Raises:
81
    ParseError: If string is not valid key-value format
82
    """
83
```
84

85
### Value Parsing
86

87
Parse arbitrary TOML values from strings with automatic type detection.
88

89
```python { .api }
90
def value(raw: str) -> Item:
91
    """
92
    Parse a TOML value from string with automatic type detection.
93
    
94
    Parameters:
95
    - raw: String representation of any TOML value
96
    
97
    Returns:
98
    Appropriate Item type based on parsed content
99
    
100
    Raises:
101
    ParseError: If string is not valid TOML value
102
    """
103
```
104

105
### Array of Tables
106

107
Create arrays of tables (AoT) for structured data collections.
108

109
```python { .api }
110
def aot() -> AoT:
111
    """
112
    Create an empty array of tables.
113
    
114
    Returns:
115
    AoT object that can contain Table items
116
    """
117
```
118

119
### Formatting Elements
120

121
Create whitespace and comment elements for precise formatting control.
122

123
```python { .api }
124
def ws(src: str) -> Whitespace:
125
    """
126
    Create a whitespace element.
127
    
128
    Parameters:
129
    - src: Whitespace string (spaces, tabs)
130
    
131
    Returns:
132
    Whitespace item for formatting control
133
    """
134

135
def nl() -> Whitespace:
136
    """
137
    Create a newline element.
138
    
139
    Returns:
140
    Whitespace item representing a newline
141
    """
142

143
def comment(string: str) -> Comment:
144
    """
145
    Create a comment element.
146
    
147
    Parameters:
148
    - string: Comment text (without # prefix)
149
    
150
    Returns:
151
    Comment item with proper TOML formatting
152
    """
153
```
154

155
## Usage Examples
156

157
### Date and Time Handling
158

159
```python
160
import tomlkit
161

162
# Create date items
163
birthday = tomlkit.date("1987-07-05")
164
release_date = tomlkit.date("2023-12-25")
165

166
# Create time items  
167
meeting_time = tomlkit.time("09:30:00")
168
precise_time = tomlkit.time("14:15:30.123")
169

170
# Create datetime items
171
created_at = tomlkit.datetime("1979-05-27T07:32:00Z")
172
updated_at = tomlkit.datetime("2023-01-15T10:30:45-08:00")
173
local_time = tomlkit.datetime("2023-06-01T12:00:00")
174

175
# Add to document
176
doc = tomlkit.document()
177
doc["user"] = {
178
    "birthday": birthday,
179
    "last_login": updated_at,
180
    "preferred_meeting": meeting_time
181
}
182
```
183

184
### Key Manipulation
185

186
```python
187
import tomlkit
188

189
# Simple keys
190
simple = tomlkit.key("title")
191
quoted = tomlkit.key("spaced key")
192

193
# Dotted keys for nested access
194
nested = tomlkit.key(["server", "database", "host"])
195
deep_nested = tomlkit.key(["app", "features", "auth", "enabled"])
196

197
# Parse key-value pairs
198
key_val = tomlkit.key_value("debug = true")
199
key_obj, value_obj = key_val
200
print(key_obj.key)  # "debug"
201
print(value_obj.value)  # True
202

203
# Complex key-value
204
complex_kv = tomlkit.key_value('database.connection = "postgresql://localhost"')
205
```
206

207
### Value Parsing
208

209
```python
210
import tomlkit
211

212
# Parse various value types
213
integer_val = tomlkit.value("42")
214
float_val = tomlkit.value("3.14159")
215
bool_val = tomlkit.value("true")
216
string_val = tomlkit.value('"Hello, World!"')
217

218
# Parse arrays
219
array_val = tomlkit.value("[1, 2, 3, 4]")
220
mixed_array = tomlkit.value('["text", 123, true]')
221

222
# Parse inline tables
223
table_val = tomlkit.value('{name = "John", age = 30}')
224

225
# Add parsed values to document
226
doc = tomlkit.document()
227
doc["count"] = integer_val
228
doc["ratio"] = float_val
229
doc["enabled"] = bool_val
230
doc["items"] = array_val
231
```
232

233
### Array of Tables
234

235
```python
236
import tomlkit
237

238
# Create array of tables
239
products = tomlkit.aot()
240

241
# Create individual tables
242
product1 = tomlkit.table()
243
product1["name"] = "Widget"
244
product1["price"] = 19.99
245
product1["in_stock"] = True
246

247
product2 = tomlkit.table()  
248
product2["name"] = "Gadget"
249
product2["price"] = 29.99
250
product2["in_stock"] = False
251

252
# Add tables to array
253
products.append(product1)
254
products.append(product2)
255

256
# Add to document
257
doc = tomlkit.document()
258
doc["products"] = products
259

260
print(doc.as_string())
261
# [[products]]
262
# name = "Widget"
263
# price = 19.99
264
# in_stock = true
265
#
266
# [[products]]
267
# name = "Gadget"
268
# price = 29.99
269
# in_stock = false
270
```
271

272
### Advanced Formatting
273

274
```python
275
import tomlkit
276

277
# Create document with precise formatting
278
doc = tomlkit.document()
279

280
# Add content with comments
281
doc.add("title", tomlkit.string("My App"))
282
doc.add(tomlkit.comment("Application metadata"))
283
doc.add(tomlkit.nl())
284

285
# Add table with formatting
286
server = tomlkit.table()
287
server.add("host", tomlkit.string("localhost"))
288
server.add(tomlkit.ws("  "))  # Add extra whitespace
289
server.add(tomlkit.comment("Server configuration"))
290

291
doc.add("server", server)
292

293
# Custom whitespace control
294
doc.add(tomlkit.nl())
295
doc.add(tomlkit.nl())  # Extra blank line
296
doc.add(tomlkit.comment("End of configuration"))
297
```
298

299
### Complex Data Structures
300

301
```python
302
import tomlkit
303

304
# Build complex nested structure
305
doc = tomlkit.document()
306

307
# Application metadata with dates
308
app_info = tomlkit.table()
309
app_info["name"] = "MyApp"
310
app_info["version"] = "2.1.0"
311
app_info["created"] = tomlkit.date("2020-01-15")
312
app_info["last_updated"] = tomlkit.datetime("2023-06-15T14:30:00Z")
313

314
# Database configurations array
315
databases = tomlkit.aot()
316

317
# Primary database
318
primary = tomlkit.table()
319
primary["name"] = "primary"
320
primary["host"] = "db1.example.com"
321
primary["port"] = 5432
322
primary["ssl"] = True
323

324
# Replica database
325
replica = tomlkit.table()
326
replica["name"] = "replica"  
327
replica["host"] = "db2.example.com"
328
replica["port"] = 5432
329
replica["ssl"] = True
330
replica["readonly"] = True
331

332
databases.append(primary)
333
databases.append(replica)
334

335
# Schedule with times
336
schedule = tomlkit.table()
337
schedule["backup_time"] = tomlkit.time("02:00:00")
338
schedule["maintenance_start"] = tomlkit.time("01:00:00") 
339
schedule["maintenance_end"] = tomlkit.time("04:00:00")
340

341
doc["app"] = app_info
342
doc["database"] = databases  
343
doc["schedule"] = schedule
344
```