0
# Loading Functions
1

2
Functions for loading YAML documents with different safety levels and processing modes. These functions parse YAML streams and convert them to Python objects.
3

4
## Capabilities
5

6
### Safe Loading
7

8
Recommended functions for loading YAML from untrusted sources. These functions only construct standard YAML tags and are safe from arbitrary code execution.
9

10
```python { .api }
11
def safe_load(stream: bytes | IO[bytes] | str | IO[str]) -> Any:
12
    """
13
    Parse a YAML document using SafeLoader.
14
    
15
    Parameters:
16
    - stream: YAML input as string, bytes, or file-like object
17
    
18
    Returns:
19
    - Python object representing the YAML document
20
    
21
    Raises:
22
    - YAMLError: If YAML parsing fails
23
    """
24

25
def safe_load_all(stream: bytes | IO[bytes] | str | IO[str]) -> Iterator[Any]:
26
    """
27
    Parse all YAML documents from a stream using SafeLoader.
28
    
29
    Parameters:
30
    - stream: YAML input containing multiple documents separated by ---
31
    
32
    Yields:
33
    - Python objects representing each YAML document
34
    
35
    Raises:
36
    - YAMLError: If YAML parsing fails
37
    """
38
```
39

40
### Full Loading
41

42
Enhanced loading with additional Python object support, safer than unsafe loading but allows more constructs than safe loading.
43

44
```python { .api }
45
def full_load(stream: bytes | IO[bytes] | str | IO[str]) -> Any:
46
    """
47
    Parse a YAML document using FullLoader.
48
    
49
    Supports Python objects like tuples, sets, and other built-in types
50
    while remaining safer than UnsafeLoader.
51
    
52
    Parameters:
53
    - stream: YAML input as string, bytes, or file-like object
54
    
55
    Returns:
56
    - Python object representing the YAML document
57
    
58
    Raises:
59
    - YAMLError: If YAML parsing fails
60
    """
61

62
def full_load_all(stream: bytes | IO[bytes] | str | IO[str]) -> Iterator[Any]:
63
    """
64
    Parse all YAML documents from a stream using FullLoader.
65
    
66
    Parameters:
67
    - stream: YAML input containing multiple documents
68
    
69
    Yields:
70
    - Python objects representing each YAML document
71
    
72
    Raises:
73
    - YAMLError: If YAML parsing fails
74
    """
75
```
76

77
### Generic Loading
78

79
Configurable loading functions that accept custom Loader classes for advanced use cases.
80

81
```python { .api }
82
def load(stream: bytes | IO[bytes] | str | IO[str], Loader=None) -> Any:
83
    """
84
    Parse a YAML document using specified Loader.
85
    
86
    Parameters:
87
    - stream: YAML input as string, bytes, or file-like object
88
    - Loader: Loader class to use (defaults to FullLoader)
89
    
90
    Returns:
91
    - Python object representing the YAML document
92
    
93
    Raises:
94
    - YAMLError: If YAML parsing fails
95
    """
96

97
def load_all(stream: bytes | IO[bytes] | str | IO[str], Loader=None) -> Iterator[Any]:
98
    """
99
    Parse all YAML documents from a stream using specified Loader.
100
    
101
    Parameters:
102
    - stream: YAML input containing multiple documents
103
    - Loader: Loader class to use (defaults to FullLoader)
104
    
105
    Yields:
106
    - Python objects representing each YAML document
107
    
108
    Raises:
109
    - YAMLError: If YAML parsing fails
110
    """
111
```
112

113
### Unsafe Loading
114

115
**WARNING**: These functions can execute arbitrary Python code and should never be used with untrusted input.
116

117
```python { .api }
118
def unsafe_load(stream: bytes | IO[bytes] | str | IO[str]) -> Any:
119
    """
120
    Parse a YAML document using UnsafeLoader.
121
    
122
    DANGER: Can execute arbitrary Python code. Only use with trusted input.
123
    
124
    Parameters:
125
    - stream: YAML input as string, bytes, or file-like object
126
    
127
    Returns:
128
    - Python object representing the YAML document
129
    
130
    Raises:
131
    - YAMLError: If YAML parsing fails
132
    """
133

134
def unsafe_load_all(stream: bytes | IO[bytes] | str | IO[str]) -> Iterator[Any]:
135
    """
136
    Parse all YAML documents from a stream using UnsafeLoader.
137
    
138
    DANGER: Can execute arbitrary Python code. Only use with trusted input.
139
    
140
    Parameters:
141
    - stream: YAML input containing multiple documents
142
    
143
    Yields:
144
    - Python objects representing each YAML document
145
    
146
    Raises:
147
    - YAMLError: If YAML parsing fails
148
    """
149
```
150

151
## Usage Examples
152

153
### Basic Safe Loading
154

155
```python
156
import yaml
157

158
# Load from string
159
yaml_str = """
160
name: John Doe
161
age: 30
162
skills:
163
  - Python
164
  - YAML
165
  - Docker
166
"""
167

168
data = yaml.safe_load(yaml_str)
169
print(data['name'])  # "John Doe"
170
print(data['skills'])  # ["Python", "YAML", "Docker"]
171

172
# Load from file
173
with open('config.yaml', 'r') as file:
174
    config = yaml.safe_load(file)
175
```
176

177
### Multiple Documents
178

179
```python
180
import yaml
181

182
multi_doc = """
183
name: Document 1
184
type: config
185
---
186
name: Document 2  
187
type: data
188
---
189
name: Document 3
190
type: settings
191
"""
192

193
documents = list(yaml.safe_load_all(multi_doc))
194
print(len(documents))  # 3
195
print(documents[0]['name'])  # "Document 1"
196
```
197

198
### Error Handling
199

200
```python
201
import yaml
202

203
try:
204
    data = yaml.safe_load('invalid: yaml: content: [')
205
except yaml.YAMLError as e:
206
    print(f"YAML parsing error: {e}")
207
    if hasattr(e, 'problem_mark'):
208
        mark = e.problem_mark
209
        print(f"Error at line {mark.line + 1}, column {mark.column + 1}")
210
```
211

212
### Custom Loader
213

214
```python
215
import yaml
216

217
# Using a specific loader
218
data = yaml.load(yaml_content, Loader=yaml.SafeLoader)
219

220
# Equivalent to safe_load
221
data = yaml.safe_load(yaml_content)
222
```