0
# Pre-configured Converters
1

2
Ready-to-use converters pre-configured for specific serialization formats. Each converter is optimized for its target format with appropriate type handling, encoding settings, and serialization options.
3

4
## Capabilities
5

6
### JSON Converter
7

8
Converter optimized for JSON serialization with support for standard JSON types and common Python data structures.
9

10
```python { .api }
11
from cattrs.preconf.json import JsonConverter, make_converter, configure_converter
12

13
class JsonConverter(Converter):
14
    """Converter pre-configured for JSON serialization."""
15
    def __init__(self, **kwargs):
16
        """Initialize JSON converter with JSON-optimized settings."""
17

18
def make_converter(**kwargs) -> JsonConverter:
19
    """
20
    Factory function to create pre-configured JSON converters.
21
    
22
    Parameters:
23
    - **kwargs: Additional arguments passed to JsonConverter
24
    
25
    Returns:
26
    JsonConverter instance configured for JSON serialization
27
    """
28

29
def configure_converter(converter: Converter, **kwargs) -> Converter:
30
    """
31
    Configure any converter for JSON compatibility.
32
    
33
    Parameters:
34
    - converter: Converter instance to configure
35
    - **kwargs: Configuration options
36
    
37
    Returns:
38
    The configured converter
39
    """
40
```
41

42
#### Usage Example
43

44
```python
45
from cattrs.preconf.json import make_converter
46
import json
47

48
converter = make_converter()
49

50
# Works seamlessly with json module
51
data = converter.unstructure(my_object)
52
json_string = json.dumps(data)
53

54
parsed_data = json.loads(json_string)
55
my_object_copy = converter.structure(parsed_data, MyClass)
56
```
57

58
### YAML Converter
59

60
Converter for YAML serialization with support for YAML-specific features and PyYAML integration.
61

62
```python { .api }
63
from cattrs.preconf.pyyaml import PyyamlConverter, make_converter, configure_converter
64

65
class PyyamlConverter(Converter):
66
    """Converter pre-configured for YAML serialization."""
67
    def __init__(self, **kwargs):
68
        """Initialize YAML converter with YAML-optimized settings."""
69

70
def make_converter(**kwargs) -> PyyamlConverter:
71
    """
72
    Factory function to create pre-configured YAML converters.
73
    
74
    Returns:
75
    PyyamlConverter instance configured for YAML serialization
76
    """
77

78
def configure_converter(converter: Converter, **kwargs) -> Converter:
79
    """
80
    Configure any converter for YAML compatibility.
81
    
82
    Parameters:
83
    - converter: Converter instance to configure
84
    
85
    Returns:
86
    The configured converter
87
    """
88
```
89

90
### MessagePack Converter
91

92
Converter optimized for MessagePack binary serialization format.
93

94
```python { .api }
95
from cattrs.preconf.msgpack import MsgpackConverter, make_converter, configure_converter
96

97
class MsgpackConverter(Converter):
98
    """Converter pre-configured for MessagePack serialization."""
99
    def __init__(self, **kwargs):
100
        """Initialize MessagePack converter."""
101

102
def make_converter(**kwargs) -> MsgpackConverter:
103
    """Factory function to create pre-configured MessagePack converters."""
104

105
def configure_converter(converter: Converter, **kwargs) -> Converter:
106
    """Configure any converter for MessagePack compatibility."""
107
```
108

109
### OrJSON Converter
110

111
High-performance JSON converter using the orjson library for fast JSON processing.
112

113
```python { .api }
114
from cattrs.preconf.orjson import OrjsonConverter, make_converter, configure_converter
115

116
class OrjsonConverter(Converter):
117
    """Converter pre-configured for OrJSON serialization."""
118
    def __init__(self, **kwargs):
119
        """Initialize OrJSON converter with performance optimizations."""
120

121
def make_converter(**kwargs) -> OrjsonConverter:
122
    """Factory function to create pre-configured OrJSON converters."""
123

124
def configure_converter(converter: Converter, **kwargs) -> Converter:
125
    """Configure any converter for OrJSON compatibility."""
126
```
127

128
### UltraJSON Converter
129

130
JSON converter using ujson for improved JSON processing performance.
131

132
```python { .api }
133
from cattrs.preconf.ujson import UjsonConverter, make_converter, configure_converter
134

135
class UjsonConverter(Converter):
136
    """Converter pre-configured for UltraJSON serialization."""
137
    def __init__(self, **kwargs):
138
        """Initialize UltraJSON converter."""
139

140
def make_converter(**kwargs) -> UjsonConverter:
141
    """Factory function to create pre-configured UltraJSON converters."""
142

143
def configure_converter(converter: Converter, **kwargs) -> Converter:
144
    """Configure any converter for UltraJSON compatibility."""
145
```
146

147
### TOML Converter
148

149
Converter for TOML configuration file format using tomlkit.
150

151
```python { .api }
152
from cattrs.preconf.tomlkit import TomlkitConverter, make_converter, configure_converter
153

154
class TomlkitConverter(Converter):
155
    """Converter pre-configured for TOML serialization."""
156
    def __init__(self, **kwargs):
157
        """Initialize TOML converter with TOML-specific handling."""
158

159
def make_converter(**kwargs) -> TomlkitConverter:
160
    """Factory function to create pre-configured TOML converters."""
161

162
def configure_converter(converter: Converter, **kwargs) -> Converter:
163
    """Configure any converter for TOML compatibility."""
164
```
165

166
### BSON Converter
167

168
Converter for MongoDB's BSON binary format.
169

170
```python { .api }
171
from cattrs.preconf.bson import BsonConverter, make_converter, configure_converter
172

173
class BsonConverter(Converter):
174
    """Converter pre-configured for BSON serialization."""
175
    def __init__(self, **kwargs):
176
        """Initialize BSON converter for MongoDB compatibility."""
177

178
def make_converter(**kwargs) -> BsonConverter:
179
    """Factory function to create pre-configured BSON converters."""
180

181
def configure_converter(converter: Converter, **kwargs) -> Converter:
182
    """Configure any converter for BSON compatibility."""
183
```
184

185
### CBOR2 Converter
186

187
Converter for CBOR (Concise Binary Object Representation) format.
188

189
```python { .api }
190
from cattrs.preconf.cbor2 import Cbor2Converter, make_converter, configure_converter
191

192
class Cbor2Converter(Converter):
193
    """Converter pre-configured for CBOR2 serialization."""
194
    def __init__(self, **kwargs):
195
        """Initialize CBOR2 converter."""
196

197
def make_converter(**kwargs) -> Cbor2Converter:
198
    """Factory function to create pre-configured CBOR2 converters."""
199

200
def configure_converter(converter: Converter, **kwargs) -> Converter:
201
    """Configure any converter for CBOR2 compatibility."""
202
```
203

204
### msgspec Converter
205

206
High-performance converter using the msgspec library for JSON and MessagePack serialization.
207

208
```python { .api }
209
from cattrs.preconf.msgspec import MsgspecJsonConverter, make_converter, configure_converter
210

211
class MsgspecJsonConverter(Converter):
212
    """Converter pre-configured for msgspec JSON serialization."""
213
    def __init__(self, **kwargs):
214
        """Initialize msgspec converter with high-performance settings."""
215

216
def make_converter(**kwargs) -> MsgspecJsonConverter:
217
    """Factory function to create pre-configured msgspec converters."""
218

219
def configure_converter(converter: Converter, **kwargs) -> Converter:
220
    """Configure any converter for msgspec compatibility."""
221
```
222

223
## Usage Patterns
224

225
### Basic Pre-configured Converter Usage
226

227
```python
228
from cattrs.preconf.json import make_converter
229
from attrs import define
230

231
@define
232
class Config:
233
    host: str
234
    port: int
235
    debug: bool = False
236

237
# Create JSON-optimized converter
238
converter = make_converter()
239

240
config = Config(host="localhost", port=8080, debug=True)
241

242
# Serialize to JSON-compatible format
243
config_dict = converter.unstructure(config)
244
# Result: {'host': 'localhost', 'port': 8080, 'debug': True}
245

246
# Deserialize from JSON-compatible format
247
config_copy = converter.structure(config_dict, Config)
248
```
249

250
### Multiple Format Support
251

252
```python
253
from cattrs.preconf import json, msgpack, yaml
254
from attrs import define
255
from typing import List
256

257
@define
258
class DataModel:
259
    values: List[float]
260
    metadata: dict
261

262
data = DataModel(values=[1.1, 2.2, 3.3], metadata={"source": "sensor"})
263

264
# Create converters for different formats
265
json_converter = json.make_converter()
266
msgpack_converter = msgpack.make_converter()
267
yaml_converter = yaml.make_converter()
268

269
# Same data, different serialization formats
270
json_data = json_converter.unstructure(data)
271
msgpack_data = msgpack_converter.unstructure(data)
272
yaml_data = yaml_converter.unstructure(data)
273

274
# All can deserialize back to the same object
275
data_from_json = json_converter.structure(json_data, DataModel)
276
data_from_msgpack = msgpack_converter.structure(msgpack_data, DataModel)
277
data_from_yaml = yaml_converter.structure(yaml_data, DataModel)
278
```
279

280
### Configuring Existing Converters
281

282
```python
283
from cattrs import Converter
284
from cattrs.preconf.json import configure_converter
285

286
# Start with a custom converter
287
custom_converter = Converter(forbid_extra_keys=True)
288

289
# Configure it for JSON compatibility
290
json_converter = configure_converter(custom_converter)
291

292
# Now it has both custom settings and JSON optimizations
293
```
294

295
## Installation Requirements
296

297
Each pre-configured converter requires its corresponding serialization library:
298

299
- **json**: No additional requirements (uses stdlib json)
300
- **pyyaml**: `pip install PyYAML`
301
- **msgpack**: `pip install msgpack`
302
- **orjson**: `pip install orjson`
303
- **ujson**: `pip install ujson`
304
- **tomlkit**: `pip install tomlkit`
305
- **bson**: `pip install pymongo`
306
- **cbor2**: `pip install cbor2`
307
- **msgspec**: `pip install msgspec`
308

309
Install cattrs with specific format support:
310

311
```bash
312
pip install cattrs[orjson,msgpack,pyyaml]
313
```