0
# Document Operations
1

2
Core functions for parsing TOML content from strings and files, and serializing TOML documents back to formatted text. These operations maintain perfect formatting preservation while providing standard I/O patterns.
3

4
## Capabilities
5

6
### Parsing Functions
7

8
Convert TOML text into structured TOMLDocument objects that preserve all formatting, comments, and whitespace.
9

10
```python { .api }
11
def parse(string: str | bytes) -> TOMLDocument:
12
    """
13
    Parse TOML string or bytes into a TOMLDocument.
14
    
15
    Parameters:
16
    - string: TOML content as string or bytes
17
    
18
    Returns:
19
    TOMLDocument object with preserved formatting
20
    
21
    Raises:
22
    ParseError: If TOML syntax is invalid
23
    """
24

25
def loads(string: str | bytes) -> TOMLDocument:
26
    """
27
    Parse TOML string or bytes into a TOMLDocument.
28
    Alias for parse().
29
    
30
    Parameters:
31
    - string: TOML content as string or bytes
32
    
33
    Returns:
34
    TOMLDocument object with preserved formatting
35
    """
36

37
def load(fp: IO[str] | IO[bytes]) -> TOMLDocument:
38
    """
39
    Load TOML content from a file-like object.
40
    
41
    Parameters:
42
    - fp: File-like object to read from
43
    
44
    Returns:
45
    TOMLDocument object with preserved formatting
46
    
47
    Raises:
48
    ParseError: If TOML syntax is invalid
49
    """
50
```
51

52
### Serialization Functions  
53

54
Convert TOML documents and mappings back to properly formatted TOML text strings.
55

56
```python { .api }
57
def dumps(data: Mapping, sort_keys: bool = False) -> str:
58
    """
59
    Serialize a TOML document or mapping to a TOML string.
60
    
61
    Parameters:
62
    - data: TOMLDocument, Container, or mapping to serialize
63
    - sort_keys: If True, sort keys alphabetically
64
    
65
    Returns:
66
    Formatted TOML string
67
    
68
    Raises:
69
    TypeError: If data is not a supported mapping type
70
    """
71

72
def dump(data: Mapping, fp: IO[str], *, sort_keys: bool = False) -> None:
73
    """
74
    Serialize a TOML document to a file-like object.
75
    
76
    Parameters:
77
    - data: TOMLDocument, Container, or mapping to serialize  
78
    - fp: File-like object to write to
79
    - sort_keys: If True, sort keys alphabetically
80
    
81
    Raises:
82
    TypeError: If data is not a supported mapping type
83
    """
84
```
85

86
### Document Creation
87

88
Create new empty TOML documents for programmatic construction.
89

90
```python { .api }
91
def document() -> TOMLDocument:
92
    """
93
    Create a new empty TOMLDocument.
94
    
95
    Returns:
96
    Empty TOMLDocument ready for content
97
    """
98
```
99

100
## Usage Examples
101

102
### Basic Parsing
103

104
```python
105
import tomlkit
106

107
# Parse from string
108
toml_content = '''
109
title = "My Application"
110
version = "1.0.0"
111

112
[database]
113
host = "localhost"
114
port = 5432
115
'''
116

117
doc = tomlkit.parse(toml_content)
118
print(doc["title"])  # "My Application"
119
print(doc["database"]["port"])  # 5432
120

121
# Parse from bytes
122
doc_bytes = toml_content.encode('utf-8')
123
doc = tomlkit.loads(doc_bytes)
124
```
125

126
### File I/O
127

128
```python
129
import tomlkit
130

131
# Load from file
132
with open('config.toml', 'r') as f:
133
    doc = tomlkit.load(f)
134

135
# Modify content
136
doc["version"] = "1.1.0"
137
doc["database"]["port"] = 3306
138

139
# Save to file
140
with open('config.toml', 'w') as f:
141
    tomlkit.dump(doc, f)
142
```
143

144
### Document Construction
145

146
```python
147
import tomlkit
148

149
# Create new document
150
doc = tomlkit.document()
151

152
# Add content
153
doc["title"] = "New Project"
154
doc["metadata"] = {
155
    "author": "John Doe",
156
    "license": "MIT"
157
}
158

159
# Serialize to string
160
toml_str = tomlkit.dumps(doc)
161
print(toml_str)
162

163
# With sorted keys
164
sorted_toml = tomlkit.dumps(doc, sort_keys=True)
165
```
166

167
### Format Preservation
168

169
```python
170
import tomlkit
171

172
# Original with comments and spacing
173
original = '''# Configuration file
174
title = "My App"    # Application name
175

176
[server]
177
host = "localhost"  
178
port = 8080         # Default port
179
'''
180

181
# Parse and modify
182
doc = tomlkit.parse(original)
183
doc["server"]["port"] = 9000
184

185
# Comments and formatting preserved
186
print(doc.as_string())
187
# Output maintains original comments and spacing
188
```