0
# jsonpickle
1

2
A Python library for encoding/decoding any Python object to/from JSON format. jsonpickle builds upon existing JSON encoders (simplejson, json, ujson) and provides comprehensive support for complex Python objects including custom classes, numpy arrays, pandas dataframes, and other objects that cannot be directly serialized to JSON.
3

4
**Security Warning**: jsonpickle is not secure. Only unpickle data you trust. It can execute arbitrary code during unpickling, similar to Python's pickle module.
5

6
## Package Information
7

8
- **Package Name**: jsonpickle
9
- **Language**: Python
10
- **Installation**: `pip install jsonpickle`
11
- **Documentation**: https://jsonpickle.readthedocs.io/
12

13
## Core Imports
14

15
```python
16
import jsonpickle
17
```
18

19
For advanced usage:
20

21
```python
22
from jsonpickle import Pickler, Unpickler, register, unregister
23
from jsonpickle.backend import JSONBackend
24
```
25

26
## Basic Usage
27

28
```python
29
import jsonpickle
30

31
# Define a custom class
32
class Thing:
33
    def __init__(self, name):
34
        self.name = name
35

36
obj = Thing('Awesome')
37

38
# Encode to JSON string
39
json_string = jsonpickle.encode(obj)
40

41
# Decode back to Python object
42
restored_obj = jsonpickle.decode(json_string)
43

44
assert obj.name == restored_obj.name
45
```
46

47
For one-way serialization (no restoration capability):
48

49
```python
50
# Create simpler JSON without restoration metadata
51
oneway = jsonpickle.encode(obj, unpicklable=False)
52
result = jsonpickle.decode(oneway)
53
assert obj.name == result['name'] == 'Awesome'
54
```
55

56
## Architecture
57

58
jsonpickle uses a modular architecture with several key components:
59

60
- **Pickler/Unpickler**: Core serialization and deserialization engines with extensive configuration options
61
- **Handlers Registry**: Extensible system for custom type serialization with built-in handlers for common types
62
- **Backend System**: Pluggable JSON encoder/decoder backends (json, simplejson, ujson) with fallback support
63
- **Tag System**: Internal metadata tags for object type preservation and reference handling
64

65
This design allows jsonpickle to handle arbitrary Python objects while maintaining compatibility with multiple JSON backends and providing security controls for safe deserialization.
66

67
## Capabilities
68

69
### Core Serialization Functions
70

71
Essential encode/decode functions for converting Python objects to/from JSON strings, with extensive configuration options for controlling serialization behavior.
72

73
```python { .api }
74
def encode(
75
    value,
76
    unpicklable=True,
77
    make_refs=True,
78
    keys=False,
79
    max_depth=None,
80
    reset=True,
81
    backend=None,
82
    warn=False,
83
    context=None,
84
    max_iter=None,
85
    use_decimal=False,
86
    numeric_keys=False,
87
    use_base85=False,
88
    fail_safe=None,
89
    indent=None,
90
    separators=None,
91
    include_properties=False,
92
    handle_readonly=False,
93
) -> str
94
```
95

96
```python { .api }
97
def decode(
98
    string,
99
    backend=None,
100
    context=None,
101
    keys=False,
102
    reset=True,
103
    safe=True,
104
    classes=None,
105
    v1_decode=False,
106
    on_missing='ignore',
107
    handle_readonly=False,
108
) -> any
109
```
110

111
```python { .api }
112
# JSON compatibility aliases
113
dumps = encode
114
loads = decode
115
```
116

117
[Core Serialization](./core-serialization.md)
118

119
### Advanced Pickler and Unpickler Classes
120

121
Low-level serialization classes providing fine-grained control over the encoding/decoding process, including state management and reusability.
122

123
```python { .api }
124
class Pickler:
125
    def __init__(self, **options): ...
126
    def reset(self): ...
127
    def flatten(self, obj): ...
128

129
class Unpickler:
130
    def __init__(self, **options): ...
131
    def reset(self): ...
132
    def restore(self, obj): ...
133
    def register_classes(self, classes): ...
134
```
135

136
[Advanced Classes](./advanced-classes.md)
137

138
### Handler Management System
139

140
Extensible system for registering custom serialization handlers for specific types, allowing you to control how particular objects are encoded and decoded.
141

142
```python { .api }
143
def register(cls, handler=None, base=False): ...
144
def unregister(cls): ...
145

146
class BaseHandler:
147
    def __init__(self, context): ...
148
    def flatten(self, obj, data): ...
149
    def restore(self, data): ...
150
```
151

152
[Handler System](./handler-system.md)
153

154
### Backend Management
155

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

158
```python { .api }
159
class JSONBackend:
160
    def encode(self, obj): ...
161
    def decode(self, s): ...
162
    def load_backend(self, name): ...
163
    def set_preferred_backend(self, name): ...
164
    def set_encoder_options(self, name, **options): ...
165
    def set_decoder_options(self, name, **options): ...
166

167
# Module-level backend functions (exported to jsonpickle namespace)
168
def set_preferred_backend(name): ...
169
def set_encoder_options(name, **options): ...
170
def set_decoder_options(name, **options): ...
171
def load_backend(name): ...
172
def remove_backend(name): ...
173
def enable_fallthrough(enable): ...
174
```
175

176
[Backend System](./backend-system.md)
177

178
### Extension Modules
179

180
Built-in extensions for popular Python libraries including numpy, pandas, GMPY, and YAML integration.
181

182
```python { .api }
183
# NumPy extension
184
from jsonpickle.ext import numpy
185
numpy.register_handlers()
186
numpy.unregister_handlers()
187

188
# Pandas extension  
189
from jsonpickle.ext import pandas
190
pandas.register_handlers()
191
pandas.unregister_handlers()
192

193
# GMPY extension
194
from jsonpickle.ext import gmpy
195
gmpy.register_handlers()
196
gmpy.unregister_handlers()
197

198
# YAML backend
199
from jsonpickle.ext import yaml
200
yaml.register()
201
```
202

203
[Extensions](./extensions.md)
204

205
## Types
206

207
```python { .api }
208
# Core exception class
209
class ClassNotFoundError(BaseException):
210
    """Raised when a class cannot be found during unpickling"""
211
    pass
212

213
# Version information
214
__version__: str
215
```