0
# Dumping and Serialization
1

2
YAML output generation with extensive formatting options and multiple dumper classes for different security levels and feature sets. Convert Python objects to YAML text with fine-grained control over output format.
3

4
## Capabilities
5

6
### High-Level Dumping
7

8
Convert Python objects to YAML strings or streams with comprehensive formatting control.
9

10
```python { .api }
11
def dump(data, stream=None, Dumper=Dumper, **kwds):
12
    """
13
    Serialize a Python object into a YAML stream.
14
    
15
    Args:
16
        data (Any): Python object to serialize
17
        stream (IO, optional): Output stream. If None, return as string
18
        Dumper (type, optional): Dumper class to use (default: Dumper)
19
        **kwds: Formatting options
20
        
21
    Keyword Arguments:
22
        default_style (str): Default scalar style (None, '"', "'", '|', '>')
23
        default_flow_style (bool): Use flow style for collections (default: False)
24
        canonical (bool): Produce canonical YAML (default: False)
25
        indent (int): Number of spaces for indentation (default: 2)
26
        width (int): Maximum line width (default: 80)
27
        allow_unicode (bool): Allow unicode characters (default: True)
28
        line_break (str): Line break character(s) (default: platform default)
29
        encoding (str): Output encoding for byte streams (default: 'utf-8')
30
        explicit_start (bool): Write document start marker --- (default: False)
31
        explicit_end (bool): Write document end marker ... (default: False)
32
        version (tuple): YAML version to use (default: (1, 1))
33
        tags (dict): Custom tag mappings
34
        sort_keys (bool): Sort dictionary keys (default: True)
35
        
36
    Returns:
37
        str | None: YAML string if stream is None, otherwise None
38
        
39
    Raises:
40
        RepresenterError: If an object cannot be represented
41
        EmitterError: If output cannot be generated
42
    """
43

44
def dump_all(documents, stream=None, Dumper=Dumper, **kwds):
45
    """
46
    Serialize a sequence of Python objects into a YAML stream.
47
    
48
    Args:
49
        documents (Iterable[Any]): Sequence of Python objects to serialize
50
        stream (IO, optional): Output stream. If None, return as string
51
        Dumper (type, optional): Dumper class to use
52
        **kwds: Formatting options (same as dump)
53
        
54
    Returns:
55
        str | None: YAML string if stream is None, otherwise None
56
        
57
    Raises:
58
        RepresenterError: If any object cannot be represented
59
        EmitterError: If output cannot be generated
60
    """
61
```
62

63
#### Usage Examples
64

65
```python
66
import yaml
67
from datetime import datetime, date
68

69
data = {
70
    'application': 'MyApp',
71
    'version': '2.1.0',
72
    'release_date': date(2023, 12, 15),
73
    'last_updated': datetime(2023, 12, 15, 14, 30, 0),
74
    'features': ['authentication', 'api', 'dashboard'],
75
    'settings': {
76
        'debug': False,
77
        'max_connections': 100,
78
        'timeout': 30.0
79
    },
80
    'servers': [
81
        {'name': 'web1', 'ip': '192.168.1.10'},
82
        {'name': 'web2', 'ip': '192.168.1.11'}
83
    ]
84
}
85

86
# Basic dumping
87
yaml_output = yaml.dump(data)
88
print(yaml_output)
89

90
# Pretty formatted output
91
yaml_pretty = yaml.dump(
92
    data,
93
    default_flow_style=False,
94
    indent=4,
95
    width=120,
96
    sort_keys=False
97
)
98

99
# Canonical YAML (strict format)
100
yaml_canonical = yaml.dump(data, canonical=True)
101

102
# With explicit document markers
103
yaml_explicit = yaml.dump(
104
    data,
105
    explicit_start=True,
106
    explicit_end=True
107
)
108

109
# Multiple documents
110
documents = [
111
    {'config': 'development', 'debug': True},
112
    {'config': 'production', 'debug': False}
113
]
114

115
yaml_multi = yaml.dump_all(
116
    documents,
117
    explicit_start=True,
118
    default_flow_style=False
119
)
120

121
# Output to file
122
with open('output.yaml', 'w') as f:
123
    yaml.dump(data, f, default_flow_style=False, sort_keys=False)
124

125
# Output to binary file with encoding
126
with open('output.yaml', 'wb') as f:
127
    yaml.dump(data, f, encoding='utf-8')
128
```
129

130
### Low-Level Serialization
131

132
Access lower-level serialization stages for advanced output control.
133

134
```python { .api }
135
def serialize_all(nodes, stream=None, Dumper=Dumper, canonical=None, indent=None, width=None, allow_unicode=None, line_break=None, encoding=None, explicit_start=None, explicit_end=None, version=None, tags=None):
136
    """
137
    Serialize a sequence of representation trees into a YAML stream.
138
    
139
    Args:
140
        nodes (Iterable[Node]): Sequence of representation tree nodes
141
        stream (IO, optional): Output stream. If None, return as string
142
        Dumper (type, optional): Dumper class to use
143
        canonical (bool, optional): Produce canonical YAML
144
        indent (int, optional): Indentation width
145
        width (int, optional): Maximum line width
146
        allow_unicode (bool, optional): Allow unicode characters
147
        line_break (str, optional): Line break character(s)
148
        encoding (str, optional): Output encoding for byte streams
149
        explicit_start (bool, optional): Write document start marker
150
        explicit_end (bool, optional): Write document end marker
151
        version (tuple, optional): YAML version to use
152
        tags (dict, optional): Custom tag mappings
153
        
154
    Returns:
155
        str | None: YAML string if stream is None, otherwise None
156
    """
157

158
def serialize(node, stream=None, Dumper=Dumper, **kwds):
159
    """
160
    Serialize a representation tree into a YAML stream.
161
    
162
    Args:
163
        node (Node): Root node of representation tree
164
        stream (IO, optional): Output stream. If None, return as string
165
        Dumper (type, optional): Dumper class to use
166
        **kwds: Formatting options
167
        
168
    Returns:
169
        str | None: YAML string if stream is None, otherwise None
170
    """
171

172
def emit(events, stream=None, Dumper=Dumper, canonical=None, indent=None, width=None, allow_unicode=None, line_break=None):
173
    """
174
    Emit YAML parsing events into a stream.
175
    
176
    Args:
177
        events (Iterable[Event]): Sequence of YAML events
178
        stream (IO, optional): Output stream. If None, return as string
179
        Dumper (type, optional): Dumper class to use for emission
180
        canonical (bool, optional): Produce canonical YAML
181
        indent (int, optional): Indentation width
182
        width (int, optional): Maximum line width
183
        allow_unicode (bool, optional): Allow unicode characters
184
        line_break (str, optional): Line break character(s)
185
        
186
    Returns:
187
        str | None: YAML string if stream is None, otherwise None
188
    """
189
```
190

191
#### Usage Examples
192

193
```python
194
import yaml
195
from yaml import SafeLoader, Dumper
196
from yaml.nodes import ScalarNode, MappingNode
197

198
# Create representation tree manually
199
key_node = ScalarNode(tag='tag:yaml.org,2002:str', value='name')
200
value_node = ScalarNode(tag='tag:yaml.org,2002:str', value='John')
201
mapping_node = MappingNode(tag='tag:yaml.org,2002:map', value=[(key_node, value_node)])
202

203
# Serialize the node
204
yaml_output = yaml.serialize(mapping_node)
205
print(yaml_output)  # name: John
206

207
# Work with events from parsing
208
yaml_content = "name: John\nage: 30"
209
events = list(yaml.parse(yaml_content, SafeLoader))
210

211
# Re-emit the events
212
yaml_recreated = yaml.emit(events)
213
print(yaml_recreated)  # Recreates original YAML
214
```
215

216
## Output Formatting Options
217

218
### Scalar Styles
219

220
Control how scalar values are formatted in the output:
221

222
```python
223
data = {'multiline': 'Line 1\nLine 2\nLine 3', 'simple': 'value'}
224

225
# Literal style (preserves newlines)
226
yaml.dump(data, default_style='|')
227
# multiline: |
228
#   Line 1
229
#   Line 2
230
#   Line 3
231

232
# Folded style (folds newlines to spaces)
233
yaml.dump(data, default_style='>')
234
# multiline: >
235
#   Line 1 Line 2 Line 3
236

237
# Quoted styles
238
yaml.dump(data, default_style='"')  # Double quoted
239
yaml.dump(data, default_style="'")  # Single quoted
240
```
241

242
### Collection Styles
243

244
Control how collections (lists and dictionaries) are formatted:
245

246
```python
247
data = {
248
    'list': [1, 2, 3],
249
    'dict': {'a': 1, 'b': 2}
250
}
251

252
# Block style (default)
253
yaml.dump(data, default_flow_style=False)
254
# list:
255
# - 1
256
# - 2
257
# - 3
258
# dict:
259
#   a: 1
260
#   b: 2
261

262
# Flow style  
263
yaml.dump(data, default_flow_style=True)
264
# {dict: {a: 1, b: 2}, list: [1, 2, 3]}
265
```
266

267
### Indentation and Width
268

269
```python
270
data = {'nested': {'deep': {'value': 'test'}}, 'list': [1, 2, 3, 4, 5]}
271

272
# Custom indentation
273
yaml.dump(data, indent=4)
274

275
# Line width control
276
yaml.dump(data, width=40)  # Shorter lines
277
yaml.dump(data, width=200)  # Longer lines allowed
278
```
279

280
## Dumper Classes
281

282
### SafeDumper
283
- Outputs only basic YAML types
284
- Safe for any consumer to read
285
- Recommended for configuration files
286

287
### Dumper  
288
- Full Python object support
289
- Can output Python-specific tags
290
- May not be readable by non-Python YAML parsers
291

292
### Custom Dumpers
293

294
```python
295
# Create custom dumper with specific behavior
296
class CustomDumper(yaml.SafeDumper):
297
    pass
298

299
# Use custom dumper
300
yaml.dump(data, Dumper=CustomDumper)
301
```
302

303
## Performance Considerations
304

305
### C Extensions
306

307
When LibYAML is available, use C-based dumpers for better performance:
308

309
```python
310
import yaml
311

312
if yaml.__with_libyaml__:
313
    # Use C dumper for better performance
314
    yaml_output = yaml.dump(data, Dumper=yaml.CDumper)
315
else:
316
    # Fall back to pure Python
317
    yaml_output = yaml.dump(data, Dumper=yaml.Dumper)
318
```
319

320
### Memory Management
321

322
For large documents:
323
- Use streaming output with file objects
324
- Process documents in chunks when possible
325
- Consider memory limits for very large data structures
326

327
```python
328
# Stream directly to file to avoid memory buildup
329
with open('large_output.yaml', 'w') as f:
330
    yaml.dump_all(large_document_sequence, f)
331
```
332

333
## Error Handling
334

335
Dumping operations can raise several types of errors:
336

337
```python
338
try:
339
    result = yaml.dump(data)
340
except yaml.RepresenterError as e:
341
    print(f"Cannot represent object: {e}")
342
except yaml.EmitterError as e:
343
    print(f"Cannot emit YAML: {e}")
344
except Exception as e:
345
    print(f"Unexpected error: {e}")
346
```
347

348
Common error scenarios:
349
- Circular references in data structures
350
- Objects that cannot be represented
351
- I/O errors when writing to streams
352
- Encoding issues with special characters