0
# Extension Modules
1

2
Built-in extensions for popular Python libraries including numpy, pandas, GMPY, and YAML integration. These extensions provide specialized handlers for complex data types.
3

4
## Capabilities
5

6
### NumPy Extension
7

8
Comprehensive support for NumPy arrays, data types, and generic objects with multiple serialization strategies.
9

10
```python { .api }
11
from jsonpickle.ext import numpy
12

13
def register_handlers():
14
    """Register all NumPy handlers with jsonpickle"""
15

16
def unregister_handlers():
17
    """Remove all NumPy handlers from jsonpickle"""
18

19
def get_byteorder():
20
    """Get the system byte order for array serialization"""
21

22
# Handler classes
23
class NumpyBaseHandler(BaseHandler):
24
    """Base handler for NumPy objects"""
25

26
class NumpyDTypeHandler(BaseHandler):
27
    """Handler for NumPy data types"""
28

29
class NumpyGenericHandler(BaseHandler):
30
    """Handler for NumPy generic scalar types"""
31

32
class NumpyDatetimeHandler(BaseHandler):
33
    """Handler for NumPy datetime types"""
34

35
class UnpickleableNumpyGenericHandler(BaseHandler):
36
    """Handler for unpickleable NumPy generic types"""
37

38
class NumpyNDArrayHandler(BaseHandler):
39
    """Handler for NumPy N-dimensional arrays"""
40

41
class NumpyNDArrayHandlerBinary(BaseHandler):
42
    """Binary serialization handler for NumPy arrays"""
43

44
class NumpyNDArrayHandlerView(BaseHandler):
45
    """View-based handler for NumPy arrays"""
46
```
47

48
**NumPy Usage Example:**
49

50
```python
51
import numpy as np
52
import jsonpickle
53
from jsonpickle.ext import numpy
54

55
# Register NumPy handlers
56
numpy.register_handlers()
57

58
# Serialize NumPy arrays
59
arr = np.array([[1, 2, 3], [4, 5, 6]], dtype=np.float32)
60
json_str = jsonpickle.encode(arr)
61
restored_arr = jsonpickle.decode(json_str)
62

63
# Serialize NumPy data types
64
dtype = np.dtype('float64')
65
json_str = jsonpickle.encode(dtype)
66
restored_dtype = jsonpickle.decode(json_str)
67

68
# Serialize NumPy scalars
69
scalar = np.float64(3.14159)
70
json_str = jsonpickle.encode(scalar)
71
restored_scalar = jsonpickle.decode(json_str)
72

73
# Unregister when done (optional)
74
numpy.unregister_handlers()
75
```
76

77
### Pandas Extension
78

79
Support for pandas DataFrames, Series, Index objects, and time-related data types.
80

81
```python { .api }
82
from jsonpickle.ext import pandas
83

84
def register_handlers():
85
    """Register all pandas handlers with jsonpickle"""
86

87
def unregister_handlers():
88
    """Remove all pandas handlers from jsonpickle"""
89

90
def pd_encode(obj):
91
    """Encode pandas objects to dictionary format"""
92

93
def pd_decode(data):
94
    """Decode dictionary data back to pandas objects"""
95

96
def rle_encode(types):
97
    """Run-length encode type arrays for efficiency"""
98

99
def rle_decode(encoded_types):
100
    """Decode run-length encoded type arrays"""
101

102
def make_read_csv_params(data):
103
    """Create parameters for CSV reading operations"""
104

105
# Handler classes
106
class PandasProcessor:
107
    """Process pandas objects for serialization"""
108

109
class PandasDfHandler(BaseHandler):
110
    """Handler for pandas DataFrame objects"""
111

112
class PandasSeriesHandler(BaseHandler):
113
    """Handler for pandas Series objects"""
114

115
class PandasIndexHandler(BaseHandler):
116
    """Handler for pandas Index objects"""
117

118
class PandasPeriodIndexHandler(BaseHandler):
119
    """Handler for pandas PeriodIndex objects"""
120

121
class PandasMultiIndexHandler(BaseHandler):
122
    """Handler for pandas MultiIndex objects"""
123

124
class PandasTimestampHandler(BaseHandler):
125
    """Handler for pandas Timestamp objects"""
126

127
class PandasPeriodHandler(BaseHandler):
128
    """Handler for pandas Period objects"""
129

130
class PandasIntervalHandler(BaseHandler):
131
    """Handler for pandas Interval objects"""
132
```
133

134
**Pandas Usage Example:**
135

136
```python
137
import pandas as pd
138
import jsonpickle
139
from jsonpickle.ext import pandas
140

141
# Register pandas handlers
142
pandas.register_handlers()
143

144
# Serialize DataFrame
145
df = pd.DataFrame({
146
    'A': [1, 2, 3],
147
    'B': ['x', 'y', 'z'],
148
    'C': pd.date_range('2023-01-01', periods=3)
149
})
150
json_str = jsonpickle.encode(df)
151
restored_df = jsonpickle.decode(json_str)
152

153
# Serialize Series
154
series = pd.Series([1, 2, 3, 4], name='numbers')
155
json_str = jsonpickle.encode(series)
156
restored_series = jsonpickle.decode(json_str)
157

158
# Serialize Index objects
159
index = pd.date_range('2023-01-01', periods=10, freq='D')
160
json_str = jsonpickle.encode(index)
161
restored_index = jsonpickle.decode(json_str)
162

163
# Serialize MultiIndex
164
multi_index = pd.MultiIndex.from_tuples([
165
    ('A', 1), ('A', 2), ('B', 1), ('B', 2)
166
], names=['letter', 'number'])
167
json_str = jsonpickle.encode(multi_index)
168
restored_multi = jsonpickle.decode(json_str)
169

170
# Unregister when done (optional)
171
pandas.unregister_handlers()
172
```
173

174
### GMPY Extension
175

176
Support for GMPY (GNU Multiple Precision Arithmetic) high-precision integer types.
177

178
```python { .api }
179
from jsonpickle.ext import gmpy
180

181
def register_handlers():
182
    """Register GMPY handlers with jsonpickle"""
183

184
def unregister_handlers():
185
    """Remove GMPY handlers from jsonpickle"""
186

187
# Handler classes
188
class GmpyMPZHandler(BaseHandler):
189
    """Handler for GMPY MPZ (arbitrary precision integer) objects"""
190
```
191

192
**GMPY Usage Example:**
193

194
```python
195
import gmpy2
196
import jsonpickle
197
from jsonpickle.ext import gmpy
198

199
# Register GMPY handlers
200
gmpy.register_handlers()
201

202
# Serialize high-precision integers
203
big_int = gmpy2.mpz(2**1000)  # Very large integer
204
json_str = jsonpickle.encode(big_int)
205
restored_int = jsonpickle.decode(json_str)
206

207
assert big_int == restored_int
208

209
# Unregister when done (optional)
210
gmpy.unregister_handlers()
211
```
212

213
### YAML Extension
214

215
Integration with YAML backends for YAML serialization support.
216

217
```python { .api }
218
from jsonpickle.ext import yaml
219

220
def register(backend=None):
221
    """Register YAML as a backend for jsonpickle"""
222
```
223

224
**YAML Usage Example:**
225

226
```python
227
import jsonpickle
228
from jsonpickle.ext import yaml
229

230
# Register YAML backend
231
yaml.register()
232

233
# Set YAML as preferred backend
234
jsonpickle.set_preferred_backend('yaml')
235

236
# Now jsonpickle will output YAML instead of JSON
237
obj = {'name': 'Alice', 'data': [1, 2, 3]}
238
yaml_str = jsonpickle.encode(obj)  # Outputs YAML format
239
restored_obj = jsonpickle.decode(yaml_str)
240
```
241

242
### Extension Usage Patterns
243

244
#### Automatic Registration at Import
245

246
```python
247
# Register extension handlers automatically
248
import jsonpickle
249
from jsonpickle.ext import numpy, pandas
250

251
# Extensions auto-register on import
252
numpy.register_handlers()
253
pandas.register_handlers()
254

255
# Now all numpy/pandas objects are supported
256
data = {
257
    'array': np.array([1, 2, 3]),
258
    'dataframe': pd.DataFrame({'A': [1, 2], 'B': [3, 4]})
259
}
260
json_str = jsonpickle.encode(data)
261
```
262

263
#### Conditional Extension Loading
264

265
```python
266
import jsonpickle
267

268
# Only load extensions if libraries are available
269
try:
270
    import numpy as np
271
    from jsonpickle.ext import numpy
272
    numpy.register_handlers()
273
    HAS_NUMPY = True
274
except ImportError:
275
    HAS_NUMPY = False
276

277
try:
278
    import pandas as pd
279
    from jsonpickle.ext import pandas
280
    pandas.register_handlers()
281
    HAS_PANDAS = True
282
except ImportError:
283
    HAS_PANDAS = False
284
```
285

286
#### Selective Handler Registration
287

288
```python
289
from jsonpickle.ext import numpy
290
import jsonpickle.handlers
291

292
# Register only specific NumPy handlers
293
registry = jsonpickle.handlers.registry
294
registry.register(np.ndarray, numpy.NumpyNDArrayHandler())
295
registry.register(np.dtype, numpy.NumpyDTypeHandler())
296
```
297

298
### Performance Considerations
299

300
- **NumPy**: Binary handlers provide better performance for large arrays
301
- **Pandas**: Consider using `unpicklable=False` for simpler data export
302
- **Extension Overhead**: Only register extensions you actually need
303
- **Memory Usage**: Large arrays and DataFrames consume significant memory during serialization
304

305
### Compatibility Notes
306

307
- **NumPy**: Supports NumPy 1.10+ with automatic dtype preservation
308
- **Pandas**: Supports pandas 0.20+ with full Index hierarchy support
309
- **GMPY**: Requires gmpy2 library for high-precision arithmetic
310
- **YAML**: Requires PyYAML library for YAML backend functionality
311

312
These extensions integrate seamlessly with jsonpickle's core functionality and can be mixed with custom handlers for comprehensive serialization support.