0
# Item Creation
1

2
Functions for creating individual TOML items with proper type representation and formatting control. These functions provide fine-grained control over TOML value creation and formatting.
3

4
## Capabilities
5

6
### Numeric Items
7

8
Create integer and floating-point TOML items from Python numbers or strings.
9

10
```python { .api }
11
def integer(raw: str | int) -> Integer:
12
    """
13
    Create an integer TOML item.
14
    
15
    Parameters:
16
    - raw: Integer value as int or string representation
17
    
18
    Returns:
19
    Integer item with proper TOML formatting
20
    """
21

22
def float_(raw: str | float) -> Float:
23
    """
24
    Create a float TOML item.
25
    
26
    Parameters:
27
    - raw: Float value as float or string representation
28
    
29
    Returns:
30
    Float item with proper TOML formatting
31
    """
32
```
33

34
### Boolean Items
35

36
Create boolean TOML items from string representations.
37

38
```python { .api }
39
def boolean(raw: str) -> Bool:
40
    """
41
    Create a boolean TOML item from string.
42
    
43
    Parameters:
44
    - raw: "true" or "false" string
45
    
46
    Returns:
47
    Bool item with proper TOML representation
48
    """
49
```
50

51
### String Items
52

53
Create string TOML items with extensive formatting control including literal strings, multiline strings, and escape handling.
54

55
```python { .api }
56
def string(
57
    raw: str,
58
    *,
59
    literal: bool = False,
60
    multiline: bool = False,
61
    escape: bool = True,
62
) -> String:
63
    """
64
    Create a string TOML item with formatting options.
65
    
66
    Parameters:
67
    - raw: String content
68
    - literal: If True, create literal string (single quotes)
69
    - multiline: If True, create multiline string  
70
    - escape: If True, apply standard TOML escaping rules
71
    
72
    Returns:
73
    String item with specified formatting
74
    """
75
```
76

77
### Array Items
78

79
Create TOML arrays from string representations or empty arrays for programmatic population.
80

81
```python { .api }
82
def array(raw: str = "[]") -> Array:
83
    """
84
    Create an array TOML item.
85
    
86
    Parameters:
87
    - raw: String representation of array (default: empty array)
88
    
89
    Returns:
90
    Array item that can be extended with values
91
    """
92
```
93

94
### Table Items
95

96
Create TOML tables and inline tables for structured data organization.
97

98
```python { .api }
99
def table(is_super_table: bool | None = None) -> Table:
100
    """
101
    Create a TOML table.
102
    
103
    Parameters:
104
    - is_super_table: If True, create super table for nested sections
105
    
106
    Returns:
107
    Empty Table that can contain key-value pairs
108
    """
109

110
def inline_table() -> InlineTable:
111
    """
112
    Create an inline TOML table.
113
    
114
    Returns:
115
    Empty InlineTable for single-line table representation
116
    """
117
```
118

119
### Generic Item Creation
120

121
Convert Python values to appropriate TOML items with automatic type detection.
122

123
```python { .api }
124
def item(value: Any, _parent: Item | None = None, _sort_keys: bool = False) -> Item:
125
    """
126
    Convert a Python value to appropriate TOML item.
127
    
128
    Parameters:
129
    - value: Python value to convert
130
    - _parent: Parent item for context (internal use)
131
    - _sort_keys: Sort dictionary keys alphabetically
132
    
133
    Returns:
134
    Appropriate TOML item type based on input value
135
    
136
    Raises:
137
    ConvertError: If value cannot be converted to TOML
138
    """
139
```
140

141
## Usage Examples
142

143
### Basic Item Creation
144

145
```python
146
import tomlkit
147

148
# Create numeric items
149
num = tomlkit.integer(42)
150
pi = tomlkit.float_(3.14159)
151
big_num = tomlkit.integer("123456789012345678901234567890")
152

153
# Create boolean
154
enabled = tomlkit.boolean("true")
155
disabled = tomlkit.boolean("false")
156

157
# Add to document
158
doc = tomlkit.document()
159
doc["count"] = num
160
doc["pi"] = pi
161
doc["enabled"] = enabled
162
```
163

164
### String Formatting Options
165

166
```python
167
import tomlkit
168

169
# Basic string
170
basic = tomlkit.string("Hello, World!")
171

172
# Literal string (preserves backslashes)
173
literal = tomlkit.string(r"C:\Users\Name", literal=True)
174

175
# Multiline string
176
multiline = tomlkit.string("""Line 1
177
Line 2
178
Line 3""", multiline=True)
179

180
# Multiline literal
181
ml_literal = tomlkit.string("""Raw text\nwith\backslashes""", 
182
                           literal=True, multiline=True)
183

184
# String without escaping
185
raw_string = tomlkit.string('Contains "quotes"', escape=False)
186
```
187

188
### Array Construction
189

190
```python
191
import tomlkit
192

193
# Empty array
194
arr = tomlkit.array()
195
arr.append(1)
196
arr.append(2)
197
arr.append(3)
198

199
# Array from string
200
parsed_array = tomlkit.array("[1, 2, 3, 4]")
201

202
# Array with mixed types
203
mixed = tomlkit.array()
204
mixed.extend([1, "hello", True, 3.14])
205
```
206

207
### Table Creation
208

209
```python
210
import tomlkit
211

212
# Create standard table
213
config = tomlkit.table()
214
config["host"] = "localhost"
215
config["port"] = 8080
216
config["ssl"] = True
217

218
# Create inline table
219
credentials = tomlkit.inline_table()
220
credentials["username"] = "admin"
221
credentials["password"] = "secret"
222

223
# Add to document
224
doc = tomlkit.document()
225
doc["server"] = config
226
doc["auth"] = credentials
227

228
print(doc.as_string())
229
# [server]
230
# host = "localhost"
231
# port = 8080
232
# ssl = true
233
# auth = {username = "admin", password = "secret"}
234
```
235

236
### Automatic Item Conversion
237

238
```python
239
import tomlkit
240

241
# Convert Python values automatically
242
doc = tomlkit.document()
243

244
# These use item() internally
245
doc["string"] = "Hello"
246
doc["number"] = 42
247
doc["float"] = 3.14
248
doc["bool"] = True
249
doc["list"] = [1, 2, 3]
250
doc["dict"] = {"nested": "value"}
251

252
# Explicit conversion
253
python_dict = {"key": "value", "num": 123}
254
toml_table = tomlkit.item(python_dict)
255
```
256

257
### Complex Structures
258

259
```python
260
import tomlkit
261

262
# Build complex document
263
doc = tomlkit.document()
264

265
# Add metadata table
266
metadata = tomlkit.table()
267
metadata["title"] = "My Application"
268
metadata["version"] = "1.0.0"
269
metadata["authors"] = tomlkit.array()
270
metadata["authors"].extend(["John Doe", "Jane Smith"])
271

272
# Add server configuration
273
server = tomlkit.table()
274
server["host"] = "0.0.0.0"
275
server["port"] = 8080
276
server["workers"] = 4
277
server["debug"] = False
278

279
# Add inline database config
280
db = tomlkit.inline_table()
281
db["url"] = "postgresql://localhost/myapp"
282
db["pool_size"] = 10
283

284
doc["metadata"] = metadata
285
doc["server"] = server
286
doc["database"] = db
287
```