jsonpickle Documentation¶
jsonpickle
is a Python library for
serialization and deserialization of complex Python objects to and from
JSON. The standard Python libraries for encoding Python into JSON, such as
the stdlib’s json and simplejson can only handle Python
primitives that have a direct JSON equivalent (e.g. dicts, lists, strings,
ints, etc.). jsonpickle builds on top of these libraries and allows more
complex data structures to be serialized to JSON. jsonpickle is highly
configurable and extendable–allowing the user to choose the JSON backend
and add additional backends.
jsonpickle Usage¶
Python library for serializing any arbitrary object graph into JSON.
Warning
The jsonpickle module is not secure. Only unpickle data you trust.
It is possible to construct malicious pickle data which will execute arbitrary code during unpickling. Never unpickle data that could have come from an untrusted source, or that could have been tampered with.
Consider signing data with an HMAC if you need to ensure that it has not been tampered with.
Safer deserialization approaches, such as reading the raw JSON directly, may be more appropriate if you are processing untrusted data.
jsonpickle can take almost any Python object and turn the object into JSON. Additionally, it can reconstitute the object back into Python.
The object must be accessible globally via a module and must inherit from object (AKA new-style classes).
Create an object:
class Thing(object):
def __init__(self, name):
self.name = name
obj = Thing('Awesome')
Use jsonpickle to transform the object into a JSON string:
import jsonpickle
frozen = jsonpickle.encode(obj)
Use jsonpickle to recreate a Python object from a JSON string:
thawed = jsonpickle.decode(frozen)
The new object has the same type and data, but essentially is now a copy of the original.
assert obj.name == thawed.name
If you will never need to load (regenerate the Python class from JSON), you can pass in the keyword unpicklable=False to prevent extra information from being added to JSON:
oneway = jsonpickle.encode(obj, unpicklable=False)
result = jsonpickle.decode(oneway)
assert obj.name == result['name'] == 'Awesome'
Note
Please see the note in the jsonpickle – High Level API when serializing dictionaries that contain non-string dictionary keys.
Download & Install¶
The easiest way to get jsonpickle is via PyPi with pip:
$ pip install -U jsonpickle
jsonpickle has no required dependencies (it uses the standard library’s
json
module by default).
You can also download or checkout the latest code and install from source:
$ python setup.py install
API Reference¶
- jsonpickle API
jsonpickle
– High Level API- Low Level API
jsonpickle.pickler
– Python to JSON-compatible dictjsonpickle.unpickler
– JSON-compatible dict to Pythonjsonpickle.backend
– JSON Backend Managementjsonpickle.util
– Helper functionsb64decode()
b64encode()
b85decode()
b85encode()
has_method()
has_reduce()
importable_name()
in_dict()
in_slots()
is_bytes()
is_collections()
is_dictionary()
is_dictionary_subclass()
is_enum()
is_function()
is_installed()
is_iterator()
is_list()
is_list_like()
is_module()
is_module_function()
is_noncomplex()
is_object()
is_picklable()
is_primitive()
is_reducible()
is_reducible_sequence_subclass()
is_sequence()
is_sequence_subclass()
is_set()
is_tuple()
is_type()
is_unicode()
itemgetter()
items()
translate_module_name()
untranslate_module_name()
Extensions¶
Contributing¶
Contact¶
Please join our mailing list. You can send email to jsonpickle@googlegroups.com.
Check https://github.com/jsonpickle/jsonpickle for project updates.
Change Log¶
License¶
jsonpickle is provided under a New BSD license,
Copyright (C) 2008-2011 John Paulett (john -at- paulett.org) Copyright (C) 2009-2021 David Aguilar (davvid -at- gmail.com)