0
# Backend Management System
1

2
Pluggable JSON encoder/decoder backend system supporting multiple JSON libraries with configuration options and fallback mechanisms.
3

4
## Capabilities
5

6
### JSONBackend Class
7

8
Core backend management class that handles multiple JSON encoder/decoder implementations.
9

10
```python { .api }
11
class JSONBackend:
12
    def __init__(self):
13
        """Initialize backend manager with default backends."""
14
        
15
    def encode(self, obj):
16
        """
17
        Encode object using the active backend.
18
        
19
        Parameters:
20
        - obj: Object to encode
21
        
22
        Returns:
23
        JSON string
24
        """
25
        
26
    def decode(self, s):
27
        """
28
        Decode JSON string using the active backend.
29
        
30
        Parameters:
31
        - s: JSON string to decode
32
        
33
        Returns:
34
        Decoded Python object
35
        """
36
        
37
    def dumps(self, obj):
38
        """Alias for encode() - json.dumps compatibility"""
39
        
40
    def loads(self, s):
41
        """Alias for decode() - json.loads compatibility"""
42
        
43
    def load_backend(self, name, dumps=None, loads=None, 
44
                     encoder_options=None, decoder_options=None):
45
        """
46
        Load and register a new JSON backend.
47
        
48
        Parameters:
49
        - name: Backend name
50
        - dumps: Function for encoding objects
51
        - loads: Function for decoding strings
52
        - encoder_options: Default encoder options
53
        - decoder_options: Default decoder options
54
        """
55
        
56
    def remove_backend(self, name):
57
        """
58
        Remove a registered backend.
59
        
60
        Parameters:
61
        - name: Backend name to remove
62
        """
63
        
64
    def set_preferred_backend(self, name):
65
        """
66
        Set the preferred backend to use.
67
        
68
        Parameters:
69
        - name: Backend name ('json', 'simplejson', 'ujson', etc.)
70
        """
71
        
72
    def set_encoder_options(self, name, **options):
73
        """
74
        Configure encoder options for a backend.
75
        
76
        Parameters:
77
        - name: Backend name
78
        - **options: Encoder-specific options
79
        """
80
        
81
    def set_decoder_options(self, name, **options):
82
        """
83
        Configure decoder options for a backend.
84
        
85
        Parameters:
86
        - name: Backend name
87
        - **options: Decoder-specific options
88
        """
89
        
90
    def enable_fallthrough(self, enable=True):
91
        """
92
        Enable/disable fallthrough to next backend on failure.
93
        
94
        Parameters:
95
        - enable: Whether to enable fallthrough
96
        """
97
        
98
    def backend_encode(self, name, obj, indent=None, separators=None):
99
        """
100
        Encode object using a specific backend.
101
        
102
        Parameters:
103
        - name: Backend name to use
104
        - obj: Object to encode
105
        - indent: JSON indentation level
106
        - separators: JSON separators for compact output
107
        
108
        Returns:
109
        JSON string
110
        """
111
        
112
    def backend_decode(self, name, string):
113
        """
114
        Decode JSON string using a specific backend.
115
        
116
        Parameters:
117
        - name: Backend name to use
118
        - string: JSON string to decode
119
        
120
        Returns:
121
        Decoded Python object
122
        """
123
```
124

125
### Module-Level Backend Functions
126

127
Convenience functions for backend management at the module level.
128

129
```python { .api }
130
def set_preferred_backend(name):
131
    """Set the preferred JSON backend"""
132

133
def set_encoder_options(name, **options):
134
    """Set encoder options for a backend"""
135

136
def set_decoder_options(name, **options):
137
    """Set decoder options for a backend"""
138

139
def load_backend(name, **kwargs):
140
    """Load and register a new backend"""
141

142
def remove_backend(name):
143
    """Remove a registered backend"""
144

145
def enable_fallthrough(enable=True):
146
    """Enable/disable backend fallthrough"""
147
```
148

149
**Basic Backend Usage:**
150

151
```python
152
import jsonpickle
153

154
# Set preferred backend
155
jsonpickle.set_preferred_backend('simplejson')
156

157
# Configure encoder options for pretty printing
158
jsonpickle.set_encoder_options('json', indent=2, sort_keys=True)
159

160
# Configure decoder options
161
jsonpickle.set_decoder_options('json', strict=False)
162

163
# Enable fallthrough to next backend on failure
164
jsonpickle.enable_fallthrough(True)
165
```
166

167
### Supported Backends
168

169
jsonpickle supports several JSON backends with automatic detection:
170

171
#### Standard Library json
172

173
```python
174
# Built-in Python json module (default)
175
jsonpickle.set_preferred_backend('json')
176

177
# Common encoder options
178
jsonpickle.set_encoder_options('json',
179
    indent=2,           # Pretty printing
180
    sort_keys=True,     # Sort dictionary keys
181
    separators=(',', ':'),  # Compact output
182
    ensure_ascii=False  # Allow unicode
183
)
184
```
185

186
#### simplejson
187

188
```python
189
# High-performance JSON library
190
jsonpickle.set_preferred_backend('simplejson')
191

192
# simplejson-specific options
193
jsonpickle.set_encoder_options('simplejson',
194
    use_decimal=True,   # Support Decimal objects
195
    namedtuple_as_object=True,  # Handle namedtuples
196
    indent=2
197
)
198

199
jsonpickle.set_decoder_options('simplejson',
200
    use_decimal=True,   # Preserve Decimal precision
201
    parse_float=float   # Custom float parsing
202
)
203
```
204

205
#### ujson
206

207
```python
208
# Ultra-fast JSON library
209
jsonpickle.set_preferred_backend('ujson')
210

211
# ujson options (limited compared to others)
212
jsonpickle.set_encoder_options('ujson',
213
    indent=2,
214
    sort_keys=True
215
)
216
```
217

218
### Custom Backend Implementation
219

220
Load custom JSON backends for specialized needs.
221

222
```python
223
import jsonpickle
224

225
# Custom encoder/decoder functions
226
def custom_dumps(obj, **kwargs):
227
    # Custom encoding logic
228
    return custom_json_encode(obj)
229

230
def custom_loads(s, **kwargs):
231
    # Custom decoding logic
232
    return custom_json_decode(s)
233

234
# Register custom backend
235
jsonpickle.load_backend(
236
    'custom',
237
    dumps=custom_dumps,
238
    loads=custom_loads,
239
    encoder_options={'custom_option': True},
240
    decoder_options={'parse_mode': 'strict'}
241
)
242

243
# Use the custom backend
244
jsonpickle.set_preferred_backend('custom')
245
```
246

247
### Backend Configuration Examples
248

249
#### High-Precision Decimal Support
250

251
```python
252
import jsonpickle
253
from decimal import Decimal
254

255
# Configure for decimal precision
256
jsonpickle.set_preferred_backend('simplejson')
257
jsonpickle.set_encoder_options('simplejson', use_decimal=True, sort_keys=True)
258
jsonpickle.set_decoder_options('simplejson', use_decimal=True)
259

260
# Now Decimal objects preserve precision
261
value = Decimal('123.456789012345678901234567890')
262
json_str = jsonpickle.encode(value)
263
restored = jsonpickle.decode(json_str)
264
assert value == restored
265
```
266

267
#### Performance Optimization
268

269
```python
270
import jsonpickle
271

272
# Use ujson for maximum speed
273
jsonpickle.set_preferred_backend('ujson')
274

275
# Compact output for minimal size
276
jsonpickle.set_encoder_options('ujson', sort_keys=False)
277

278
# Enable fallthrough for compatibility
279
jsonpickle.enable_fallthrough(True)
280
```
281

282
#### Development/Debugging Configuration
283

284
```python
285
import jsonpickle
286

287
# Pretty printing for readability
288
jsonpickle.set_preferred_backend('json')
289
jsonpickle.set_encoder_options('json',
290
    indent=2,
291
    sort_keys=True,
292
    ensure_ascii=False
293
)
294
```
295

296
### Backend Selection Strategy
297

298
jsonpickle automatically selects backends in order of availability:
299

300
1. **Preferred backend** (if set and available)
301
2. **simplejson** (if installed)
302
3. **ujson** (if installed)
303
4. **json** (standard library fallback)
304

305
Use `enable_fallthrough(True)` to automatically try the next backend if the current one fails.
306

307
### Global Backend Instance
308

309
```python { .api }
310
# The global backend instance used by jsonpickle
311
from jsonpickle.backend import json
312

313
# Access backend methods directly
314
json.set_preferred_backend('simplejson')
315
json.encode({'key': 'value'})
316
json.decode('{"key": "value"}')
317
```
318

319
## Error Handling
320

321
Backend operations may raise various exceptions:
322

323
- **ImportError**: When a backend module is not available
324
- **ValueError**: When invalid options are provided
325
- **TypeError**: When unsupported data types are encountered
326
- **Backend-specific errors**: Depending on the JSON library used
327

328
Always handle these appropriately in production code.