0
# pyserde
1

2
A comprehensive Python serialization library built on dataclasses that enables automatic conversion of Python objects to and from multiple data formats including JSON, YAML, TOML, MessagePack, and Pickle. Inspired by Rust's serde, it provides a decorator-based approach with extensive type system support and high-performance serialization.
3

4
## Package Information
5

6
- **Package Name**: pyserde
7
- **Language**: Python  
8
- **Installation**: `pip install pyserde`
9
- **Optional dependencies**: `pip install pyserde[all]` for all formats
10

11
## Core Imports
12

13
```python
14
from serde import serde, to_dict, from_dict, to_json, from_json
15
```
16

17
Format-specific imports:
18
```python
19
from serde.json import to_json, from_json
20
from serde.yaml import to_yaml, from_yaml  
21
from serde.toml import to_toml, from_toml
22
from serde.msgpack import to_msgpack, from_msgpack
23
from serde.pickle import to_pickle, from_pickle
24
```
25

26
## Basic Usage
27

28
```python
29
from serde import serde, to_dict, from_dict
30
from serde.json import to_json, from_json
31

32
@serde
33
class Person:
34
    name: str
35
    age: int
36
    email: str | None = None
37

38
# Create an instance
39
person = Person(name="Alice", age=30, email="alice@example.com")
40

41
# Serialize to JSON
42
json_data = to_json(person)
43
# '{"name":"Alice","age":30,"email":"alice@example.com"}'
44

45
# Deserialize from JSON  
46
person_copy = from_json(Person, json_data)
47
# Person(name='Alice', age=30, email='alice@example.com')
48

49
# Serialize to dictionary
50
dict_data = to_dict(person)
51
# {'name': 'Alice', 'age': 30, 'email': 'alice@example.com'}
52

53
# Deserialize from dictionary
54
person_from_dict = from_dict(Person, dict_data)
55
```
56

57
## Architecture
58

59
pyserde uses a code generation approach for high performance:
60

61
- **@serde decorator**: Analyzes dataclass fields and generates specialized serialization/deserialization functions
62
- **Type introspection**: Leverages Python's type hints for automatic (de)serialization logic
63
- **Format abstraction**: Common serialization core with pluggable format-specific backends
64
- **Scope management**: Generated code is cached and managed efficiently for performance
65

66
## Capabilities
67

68
### Core Serialization
69

70
The fundamental serialization and deserialization functionality that powers all format-specific modules. Provides the @serde decorator and core conversion functions.
71

72
```python { .api }
73
def serde(
74
    _cls: Any = None,
75
    rename_all: Optional[str] = None,
76
    reuse_instances_default: bool = True,
77
    convert_sets_default: bool = False,
78
    serializer: Optional[SerializeFunc] = None,
79
    deserializer: Optional[DeserializeFunc] = None,
80
    tagging: Tagging = DefaultTagging,
81
    type_check: TypeCheck = strict,
82
    serialize_class_var: bool = False,
83
    class_serializer: Optional[ClassSerializer] = None,
84
    class_deserializer: Optional[ClassDeserializer] = None,
85
    deny_unknown_fields: bool = False,
86
) -> Any: ...
87

88
def to_dict(
89
    o: Any,
90
    c: Optional[type[Any]] = None,
91
    reuse_instances: Optional[bool] = None,
92
    convert_sets: Optional[bool] = None,
93
    skip_none: bool = False,
94
) -> dict[Any, Any]: ...
95

96
def from_dict(cls: type[T], o: dict[str, Any], reuse_instances: Optional[bool] = None) -> T: ...
97

98
def to_tuple(
99
    o: Any,
100
    c: Optional[type[Any]] = None,
101
    reuse_instances: Optional[bool] = None,
102
    convert_sets: Optional[bool] = None,
103
    skip_none: bool = False,
104
) -> tuple[Any, ...]: ...
105

106
def from_tuple(cls: type[T], o: Any, reuse_instances: Optional[bool] = None) -> T: ...
107
```
108

109
[Core Serialization](./core-serialization.md)
110

111
### Format-Specific Modules
112

113
Serialization and deserialization functions for specific data formats including JSON, YAML, TOML, MessagePack, and Pickle.
114

115
```python { .api }
116
# JSON
117
def to_json(
118
    obj: Any, 
119
    cls: Optional[Any] = None, 
120
    se: type[Serializer[str]] = JsonSerializer,
121
    reuse_instances: bool = False,
122
    convert_sets: bool = True,
123
    skip_none: bool = False,
124
    **opts: Any
125
) -> str: ...
126

127
def from_json(
128
    c: type[T], 
129
    s: AnyStr, 
130
    de: type[Deserializer[AnyStr]] = JsonDeserializer, 
131
    **opts: Any
132
) -> T: ...
133

134
# YAML  
135
def to_yaml(
136
    obj: Any,
137
    cls: Optional[Any] = None,
138
    se: type[Serializer[str]] = YamlSerializer,
139
    reuse_instances: bool = False,
140
    convert_sets: bool = True,
141
    skip_none: bool = False,
142
    **opts: Any,
143
) -> str: ...
144

145
def from_yaml(
146
    c: type[T], 
147
    s: str, 
148
    de: type[Deserializer[str]] = YamlDeserializer, 
149
    **opts: Any
150
) -> T: ...
151

152
# TOML
153
def to_toml(
154
    obj: Any,
155
    cls: Optional[Any] = None,
156
    se: type[Serializer[str]] = TomlSerializer,
157
    reuse_instances: bool = False,
158
    convert_sets: bool = True,
159
    skip_none: bool = True,
160
    **opts: Any,
161
) -> str: ...
162

163
def from_toml(
164
    c: type[T], 
165
    s: str, 
166
    de: type[Deserializer[str]] = TomlDeserializer, 
167
    **opts: Any
168
) -> T: ...
169
```
170

171
[Format Modules](./format-modules.md)
172

173
### Field Configuration and Customization
174

175
Advanced field-level configuration for custom serialization behavior, field renaming, skipping, and custom serializers.
176

177
```python { .api }
178
def field(
179
    default=...,
180
    default_factory=...,
181
    init: bool = True,
182
    repr: bool = True,
183
    hash: bool | None = None,
184
    compare: bool = True,
185
    metadata: dict | None = None,
186
    rename: str | None = None,
187
    serializer: Callable | None = None,
188
    deserializer: Callable | None = None,
189
    flatten: bool = False,
190
    skip: bool = False,
191
    skip_if: Callable | None = None,
192
    skip_if_false: bool = False,
193
    skip_if_default: bool = False,
194
) -> Any: ...
195
```
196

197
[Field Configuration](./field-configuration.md)
198

199
### Union Handling and Type Checking
200

201
Advanced type system features including union type handling with different tagging strategies and configurable type checking modes.
202

203
```python { .api }
204
# Tagging strategies
205
class ExternalTagging: ...
206
class InternalTagging: ...  
207
class AdjacentTagging: ...
208
class Untagged: ...
209

210
# Type checking modes
211
class TypeCheck: ...
212
strict: TypeCheck
213
disabled: TypeCheck
214
coerce: TypeCheck
215
```
216

217
[Union Handling](./union-handling.md)
218

219
### Type System Compatibility
220

221
Comprehensive type introspection and compatibility utilities for working with Python's type system, generics, and complex nested types.
222

223
```python { .api }
224
def is_union(typ) -> bool: ...
225
def is_opt(typ) -> bool: ...
226
def is_list(typ) -> bool: ...
227
def is_dict(typ) -> bool: ...
228
def get_origin(typ): ...
229
def get_args(typ): ...
230
```
231

232
[Type System](./type-system.md)
233

234
### Inspection and Debugging
235

236
Tools for debugging and inspecting generated serialization code.
237

238
```python { .api }
239
def inspect(cls: type[Any]) -> None:
240
    """
241
    Inspect a pyserde class and print generated code.
242
    
243
    Parameters:
244
    - cls: Pyserde-decorated class to inspect
245
    """
246
```
247

248
## Types
249

250
```python { .api }
251
from typing import TypeVar, Protocol, Callable, Any
252

253
T = TypeVar('T')
254

255
class SerializeFunc(Protocol):
256
    def __call__(self, obj: Any) -> Any: ...
257

258
class DeserializeFunc(Protocol):  
259
    def __call__(self, cls: type, obj: Any) -> Any: ...
260

261
class ClassSerializer(Protocol):
262
    def serialize(self, obj: Any) -> Any: ...
263

264
class ClassDeserializer(Protocol):
265
    def deserialize(self, cls: type, data: Any) -> Any: ...
266

267
class Tagging:
268
    """Base class for union tagging strategies."""
269

270
class TypeCheck:
271
    """Type checking configuration."""
272

273
class SerdeError(Exception):
274
    """Base exception for serde errors."""
275

276
class SerdeSkip(Exception):
277
    """Exception to skip field serialization."""
278
```