0
# PyYAML Type Stubs
1

2
Type stubs for PyYAML, a full-featured YAML framework for Python. This package provides comprehensive type annotations enabling static type checking for YAML parsing and serialization operations, covering the complete YAML processing pipeline from reading to dumping with support for both safe and unsafe operations.
3

4
## Package Information
5

6
- **Package Name**: types-PyYAML
7
- **Language**: Python
8
- **Installation**: `pip install types-PyYAML`
9

10
## Core Imports
11

12
```python
13
import yaml
14
```
15

16
For specific functionality:
17

18
```python
19
from yaml import load, dump, safe_load, safe_dump
20
from yaml import SafeLoader, SafeDumper, FullLoader
21
from yaml import YAMLError, YAMLObject
22
```
23

24
## Basic Usage
25

26
```python
27
import yaml
28

29
# Safe loading (recommended for untrusted input)
30
data = yaml.safe_load('hello: world\nlist:\n  - item1\n  - item2')
31
print(data)  # {'hello': 'world', 'list': ['item1', 'item2']}
32

33
# Safe dumping
34
yaml_string = yaml.safe_dump({'name': 'John', 'age': 30, 'items': [1, 2, 3]})
35
print(yaml_string)
36

37
# Full loading (more features, safer than unsafe)
38
with open('config.yaml', 'r') as file:
39
    config = yaml.full_load(file)
40

41
# Dumping to file
42
with open('output.yaml', 'w') as file:
43
    yaml.safe_dump(data, file, default_flow_style=False)
44
```
45

46
## Architecture
47

48
PyYAML provides a complete YAML processing pipeline with multiple abstraction levels:
49

50
- **High-level API**: Convenience functions (`load`, `dump`, `safe_load`, `safe_dump`)
51
- **Processing Pipeline**: Reader → Scanner → Parser → Composer → Constructor for loading
52
- **Output Pipeline**: Representer → Serializer → Emitter for dumping
53
- **Customization Layer**: Custom constructors, representers, resolvers for advanced use cases
54
- **Performance Layer**: C extensions (CLoader, CDumper) for improved performance
55

56
## Capabilities
57

58
### High-Level Loading Functions
59

60
Core functions for loading YAML documents with different safety levels and processing modes.
61

62
```python { .api }
63
def safe_load(stream) -> Any: ...
64
def safe_load_all(stream) -> Iterator[Any]: ...
65
def full_load(stream) -> Any: ...
66
def full_load_all(stream) -> Iterator[Any]: ...
67
def load(stream, Loader=None) -> Any: ...
68
def load_all(stream, Loader=None) -> Iterator[Any]: ...
69
def unsafe_load(stream) -> Any: ...
70
def unsafe_load_all(stream) -> Iterator[Any]: ...
71
```
72

73
[Loading Functions](./loading.md)
74

75
### High-Level Dumping Functions
76

77
Core functions for serializing Python objects to YAML with different safety levels and formatting options.
78

79
```python { .api }
80
def safe_dump(data, stream=None, **kwargs) -> str | None: ...
81
def safe_dump_all(documents, stream=None, **kwargs) -> str | None: ...
82
def dump(data, stream=None, Dumper=None, **kwargs) -> str | None: ...
83
def dump_all(documents, stream=None, Dumper=None, **kwargs) -> str | None: ...
84
```
85

86
[Dumping Functions](./dumping.md)
87

88
### Loaders and Dumpers
89

90
Configurable loader and dumper classes that combine different processing components for customized YAML processing.
91

92
```python { .api }
93
class BaseLoader(Reader, Scanner, Parser, Composer, BaseConstructor, BaseResolver): ...
94
class SafeLoader(Reader, Scanner, Parser, Composer, SafeConstructor, Resolver): ...
95
class FullLoader(Reader, Scanner, Parser, Composer, FullConstructor, Resolver): ...
96
class Loader(Reader, Scanner, Parser, Composer, Constructor, Resolver): ...
97
class UnsafeLoader(Reader, Scanner, Parser, Composer, Constructor, Resolver): ...
98
class BaseDumper(Emitter, Serializer, BaseRepresenter, BaseResolver): ...
99
class SafeDumper(Emitter, Serializer, SafeRepresenter, Resolver): ...
100
class Dumper(Emitter, Serializer, Representer, Resolver): ...
101
```
102

103
[Loaders and Dumpers](./loaders-dumpers.md)
104

105
### Error Handling
106

107
Exception classes for handling various YAML processing errors with position information and detailed error messages.
108

109
```python { .api }
110
class YAMLError(Exception): ...
111
class MarkedYAMLError(YAMLError):
112
    context: str | None
113
    context_mark: Mark | None
114
    problem: str | None
115
    problem_mark: Mark | None
116
    note: str | None
117

118
class Mark:
119
    name: str
120
    index: int
121
    line: int
122
    column: int
123
    def get_snippet(self, indent=4, max_length=75) -> str: ...
124
```
125

126
[Error Handling](./errors.md)
127

128
### Custom YAML Objects
129

130
Base classes and utilities for creating custom YAML-serializable Python objects with automatic tag registration.
131

132
```python { .api }
133
class YAMLObject(metaclass=YAMLObjectMetaclass):
134
    yaml_loader: Any
135
    yaml_dumper: Any
136
    yaml_tag: Any
137
    yaml_flow_style: Any
138
    @classmethod
139
    def from_yaml(cls, loader, node): ...
140
    @classmethod
141
    def to_yaml(cls, dumper, data): ...
142
```
143

144
[Custom Objects](./custom-objects.md)
145

146
### Registration Functions
147

148
Functions for registering custom constructors, representers, and resolvers to extend YAML processing capabilities.
149

150
```python { .api }
151
def add_constructor(tag: str, constructor: Callable, Loader=None) -> None: ...
152
def add_multi_constructor(tag_prefix: str, multi_constructor: Callable, Loader=None) -> None: ...
153
def add_representer(data_type: type, representer: Callable, Dumper=None) -> None: ...
154
def add_multi_representer(data_type: type, multi_representer: Callable, Dumper=None) -> None: ...
155
def add_implicit_resolver(tag: str, regexp: Pattern[str], first=None, Loader=None, Dumper=None) -> None: ...
156
def add_path_resolver(tag: str, path: Iterable[Any], kind=None, Loader=None, Dumper=None) -> None: ...
157
```
158

159
[Registration](./registration.md)
160

161
### Low-Level Processing
162

163
Lower-level YAML processing functions for advanced use cases requiring fine-grained control over the processing pipeline.
164

165
```python { .api }
166
def scan(stream, Loader=None): ...
167
def parse(stream, Loader=None): ...
168
def compose(stream, Loader=None): ...
169
def compose_all(stream, Loader=None): ...
170
def serialize(node, stream=None, Dumper=None, **kwargs): ...
171
def serialize_all(nodes, stream=None, Dumper=None, **kwargs): ...
172
def emit(events, stream=None, Dumper=None, **kwargs): ...
173
```
174

175
[Low-Level Processing](./low-level.md)
176

177
### Advanced Components
178

179
Internal processing components for custom loader and dumper construction, including constructors, representers, resolvers, and processing pipeline components.
180

181
```python { .api }
182
class BaseConstructor: ...
183
class SafeConstructor(BaseConstructor): ...
184
class FullConstructor(SafeConstructor): ...
185
class BaseRepresenter: ...
186
class SafeRepresenter(BaseRepresenter): ...
187
class Representer(SafeRepresenter): ...
188
class BaseResolver: ...
189
class Resolver(BaseResolver): ...
190
```
191

192
[Advanced Components](./advanced-components.md)
193

194
### C Extensions
195

196
High-performance C-based implementations of loaders, dumpers, and processing components for improved performance.
197

198
```python { .api }
199
class CBaseLoader(CParser, BaseConstructor, BaseResolver): ...
200
class CLoader(CParser, SafeConstructor, Resolver): ...
201
class CSafeLoader(CParser, SafeConstructor, Resolver): ...
202
class CFullLoader(CParser, FullConstructor, Resolver): ...
203
class CUnsafeLoader(CParser, UnsafeConstructor, Resolver): ...
204
class CBaseDumper(CEmitter, BaseRepresenter, BaseResolver): ...
205
class CDumper(CEmitter, SafeRepresenter, Resolver): ...
206
class CSafeDumper(CEmitter, SafeRepresenter, Resolver): ...
207

208
# Type alias
209
CSafeDumper = CDumper
210
```
211

212
[C Extensions](./c-extensions.md)
213

214
## Common Types
215

216
```python { .api }
217
# Module constants
218
__with_libyaml__: Any  # Indicates whether C extensions are available
219
__version__: str  # PyYAML version string
220

221
# Type aliases used throughout the API
222
_Yaml = Any  # YAML data type
223
_Str = str | Union[Text, str]  # String type for Python 2/3 compatibility
224

225
# Stream types
226
StreamType = Union[str, bytes, IO[str], IO[bytes], Text, IO[Text]]
227

228
# Constructor and representer type variables  
229
_Constructor = TypeVar("_Constructor", bound=BaseConstructor)
230
_Representer = TypeVar("_Representer", bound=BaseRepresenter)
231
```