1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
.. _jsonpickle-api:
==============
jsonpickle API
==============
.. testsetup:: *
import jsonpickle
import jsonpickle.pickler
import jsonpickle.unpickler
import jsonpickle.handlers
import jsonpickle.util
.. contents::
.. _api-docs:
:mod:`jsonpickle` -- High Level API
===================================
.. note::
For performance and compatibility reasons, jsonpickle does not preserve
non-string dictionary keys by default. This results in a simpler, but
sometimes lossy, JSON representation.
Specify ``keys=True`` when encoding and decoding to preserve integers,
tuples, and other non-strings types as dictionary keys.
.. autofunction:: jsonpickle.encode
.. autofunction:: jsonpickle.decode
Choosing and Loading Backends
-----------------------------
jsonpickle allows the user to specify what JSON backend to use
when encoding and decoding. By default, jsonpickle will try to use, in
the following order: :mod:`simplejson` and :mod:`json`.
The preferred backend can be set via :func:`jsonpickle.set_preferred_backend`.
Additional JSON backends can be used via :func:`jsonpickle.load_backend`.
For example, users of `Django <http://www.djangoproject.com/>`_ can use the
version of simplejson that is bundled in Django::
jsonpickle.load_backend('django.util.simplejson', 'dumps', 'loads', ValueError))
jsonpickle.set_preferred_backend('django.util.simplejson')
Supported backends:
* :mod:`json`
* `simplejson <http://undefined.org/python/#simplejson>`_
Experimental backends:
* `jsonlib <https://pypi.org/project/jsonlib/>`_
* yajl via `py-yajl <https://github.com/rtyler/py-yajl/>`_
* `ujson <https://pypi.org/project/ujson/>`_
.. autofunction:: jsonpickle.set_preferred_backend
.. autofunction:: jsonpickle.load_backend
.. autofunction:: jsonpickle.remove_backend
.. autofunction:: jsonpickle.set_encoder_options
.. autofunction:: jsonpickle.set_decoder_options
Customizing JSON output
-----------------------
jsonpickle supports the standard :mod:`pickle` `__getstate__` and `__setstate__`
protocol for representing object instances.
.. method:: object.__getstate__()
Classes can further influence how their instances are pickled; if the class
defines the method :meth:`__getstate__`, it is called and the return state is
pickled as the contents for the instance, instead of the contents of the
instance's dictionary. If there is no :meth:`__getstate__` method, the
instance's :attr:`__dict__` is pickled.
.. method:: object.__setstate__(state)
Upon unpickling, if the class also defines the method :meth:`__setstate__`,
it is called with the unpickled state. If there is no
:meth:`__setstate__` method, the pickled state must be a dictionary and its
items are assigned to the new instance's dictionary. If a class defines both
:meth:`__getstate__` and :meth:`__setstate__`, the state object needn't be a
dictionary and these methods can do what they want.
:mod:`jsonpickle.handlers` -- Custom Serialization Handlers
-----------------------------------------------------------
The `jsonpickle.handlers` module allows plugging in custom
serialization handlers at run-time. This feature is useful when
jsonpickle is unable to serialize objects that are not
under your direct control.
.. automodule:: jsonpickle.handlers
:members:
:undoc-members:
Low Level API
=============
Typically this low level functionality is not needed by clients.
Note that arguments like ``safe=True`` do not make it safe to load an untrusted
jsonpickle string.
:mod:`jsonpickle.pickler` -- Python to JSON-compatible dict
-----------------------------------------------------------
.. automodule:: jsonpickle.pickler
:members:
:undoc-members:
:mod:`jsonpickle.unpickler` -- JSON-compatible dict to Python
-------------------------------------------------------------
.. automodule:: jsonpickle.unpickler
:members:
:undoc-members:
:mod:`jsonpickle.backend` -- JSON Backend Management
----------------------------------------------------
.. automodule:: jsonpickle.backend
:members:
:mod:`jsonpickle.util` -- Helper functions
------------------------------------------
.. automodule:: jsonpickle.util
:members:
:undoc-members:
|
