jsonpickle API

Contents

jsonpickle – High Level API

jsonpickle.encode(value, unpicklable=True, make_refs=True, keys=False, max_depth=None, backend=None, warn=False, max_iter=None)

Return a JSON formatted representation of value, a Python object.

Parameters:
  • unpicklable – If set to False then the output will not contain the information necessary to turn the JSON data back into Python objects, but a simpler JSON stream is produced.
  • max_depth – If set to a non-negative integer then jsonpickle will not recurse deeper than ‘max_depth’ steps into the object. Anything deeper than ‘max_depth’ is represented using a Python repr() of the object.
  • make_refs – If set to False jsonpickle’s referencing support is disabled. Objects that are id()-identical won’t be preserved across encode()/decode(), but the resulting JSON stream will be conceptually simpler. jsonpickle detects cyclical objects and will break the cycle by calling repr() instead of recursing when make_refs is set False.
  • keys – If set to True then jsonpickle will encode non-string dictionary keys instead of coercing them into strings via repr().
  • warn – If set to True then jsonpickle will warn when it returns None for an object which it cannot pickle (e.g. file descriptors).
  • max_iter – If set to a non-negative integer then jsonpickle will consume at most max_iter items when pickling iterators.
>>> encode('my string')
'"my string"'
>>> encode(36)
'36'
>>> encode({'foo': True})
'{"foo": true}'
>>> encode({'foo': True}, max_depth=0)
'"{\'foo\': True}"'
>>> encode({'foo': True}, max_depth=1)
'{"foo": "True"}'
jsonpickle.decode(string, backend=None, keys=False)

Convert a JSON string into a Python object.

The keyword argument ‘keys’ defaults to False. If set to True then jsonpickle will decode non-string dictionary keys into python objects via the jsonpickle protocol.

>>> str(decode('"my string"'))
'my string'
>>> decode('36')
36

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: simplejson, json, and demjson. The prefered backend can be set via jsonpickle.set_preferred_backend(). Additional JSON backends can be used via jsonpickle.load_backend().

For example, users of Django 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:

Experimental backends:

jsonpickle.set_preferred_backend(self, name)

Set the preferred json backend.

If a preferred backend is set then jsonpickle tries to use it before any other backend.

For example:

set_preferred_backend('simplejson')

If the backend is not one of the built-in jsonpickle backends (json/simplejson, or demjson) then you must load the backend prior to calling set_preferred_backend.

AssertionError is raised if the backend has not been loaded.

jsonpickle.load_backend(self, name, encode_name, decode_name, decode_exc)

Load a JSON backend by name.

This method loads a backend and sets up references to that backend’s encode/decode functions and exception classes.

Parameters:
  • encode_name – is the name of the backend’s encode method. The method should take an object and return a string.
  • decode_name – names the backend’s method for the reverse operation – returning a Python object from a string.
  • decode_exc – can be either the name of the exception class used to denote decoding errors, or it can be a direct reference to the appropriate exception class itself. If it is a name, then the assumption is that an exception class of that name can be found in the backend module’s namespace.
jsonpickle.remove_backend(self, name)

Remove all entries for a particular backend.

jsonpickle.set_encoder_options(self, name, *args, **kwargs)

Associate encoder-specific options with an encoder.

After calling set_encoder_options, any calls to jsonpickle’s encode method will pass the supplied args and kwargs along to the appropriate backend’s encode method.

For example:

set_encoder_options('simplejson', sort_keys=True, indent=4)
set_encoder_options('demjson', compactly=False)

See the appropriate encoder’s documentation for details about the supported arguments and keyword arguments.

Customizing JSON output

jsonpickle supports the standard pickle __getstate__ and __setstate__ protocol for representating object instances.

object.__getstate__()

Classes can further influence how their instances are pickled; if the class defines the method __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 __getstate__() method, the instance’s __dict__ is pickled.

object.__setstate__(state)

Upon unpickling, if the class also defines the method __setstate__(), it is called with the unpickled state. If there is no __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 __getstate__() and __setstate__(), the state object needn’t be a dictionary and these methods can do what they want.

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.

Custom handlers may be created to handle other objects. Each custom handler must derive from jsonpickle.handlers.BaseHandler and implement flatten and restore.

A handler can be bound to other types by calling jsonpickle.handlers.register().

jsonpickle.customhandlers.SimpleReduceHandler is suitable for handling objects that implement the reduce protocol:

from jsonpickle import handlers

class MyCustomObject(handlers.BaseHandler):
    ...

    def __reduce__(self):
        return MyCustomObject, self._get_args()

handlers.register(MyCustomObject, handlers.SimpleReduceHandler)
class jsonpickle.handlers.BaseHandler(context)
flatten(obj, data)

Flatten obj into a json-friendly form and write result in data

classmethod handles(cls)

Register this handler for the given class. Suitable as a decorator, e.g.:

@SimpleReduceHandler.handles
class MyCustomClass:
    def __reduce__(self):
        ...
restore(obj)

Restore the json-friendly obj to the registered type

class jsonpickle.handlers.CloneFactory(exemplar)

Serialization proxy for collections.defaultdict’s default_factory

class jsonpickle.handlers.DatetimeHandler(context)

Custom handler for datetime objects

Datetime objects use __reduce__, and they generate binary strings encoding the payload. This handler encodes that payload to reconstruct the object.

flatten(obj, data)
restore(data)
class jsonpickle.handlers.OrderedDictReduceHandler(context)

Serialize OrderedDict on Python 3.4+

Python 3.4+ returns multiple entries in an OrderedDict’s reduced form. Previous versions return a two-item tuple. OrderedDictReduceHandler makes the formats compatible.

flatten(obj, data)
class jsonpickle.handlers.QueueHandler(context)

Opaquely serializes Queue objects

Queues contains mutex and condition variables which cannot be serialized. Construct a new Queue instance when restoring.

flatten(obj, data)
restore(data)
class jsonpickle.handlers.RegexHandler(context)

Flatten _sre.SRE_Pattern (compiled regex) objects

flatten(obj, data)
restore(data)
class jsonpickle.handlers.Registry
get(class_name)
register(cls, handler)

Register the a custom handler for a class

Parameters:
  • cls – The custom object class to handle
  • handler – The custom handler class
unregister(cls)
class jsonpickle.handlers.SimpleReduceHandler(context)

Follow the __reduce__ protocol to pickle an object.

As long as the factory and its arguments are pickleable, this should pickle any object that implements the reduce protocol.

flatten(obj, data)
restore(data)

Low Level API

Typically this low level functionality is not needed by clients.

jsonpickle.pickler – Python to JSON

class jsonpickle.pickler.Pickler(unpicklable=True, make_refs=True, max_depth=None, backend=None, keys=False, warn=False, max_iter=None)
flatten(obj, reset=True)

Takes an object and returns a JSON-safe representation of it.

Simply returns any of the basic builtin datatypes

>>> p = Pickler()
>>> p.flatten('hello world')
'hello world'
>>> p.flatten(49)
49
>>> p.flatten(350.0)
350.0
>>> p.flatten(True)
True
>>> p.flatten(False)
False
>>> r = p.flatten(None)
>>> r is None
True
>>> p.flatten(False)
False
>>> p.flatten([1, 2, 3, 4])
[1, 2, 3, 4]
>>> p.flatten((1,2,))[tags.TUPLE]
[1, 2]
>>> p.flatten({'key': 'value'})
{'key': 'value'}
reset()
jsonpickle.pickler.encode(value, unpicklable=False, make_refs=True, keys=False, max_depth=None, reset=True, backend=None, warn=False, context=None, max_iter=None)

jsonpickle.unpickler – JSON to Python

class jsonpickle.unpickler.Unpickler(backend=None, keys=False, safe=False)
reset()

Resets the object’s internal state.

restore(obj, reset=True)

Restores a flattened object to its original python state.

Simply returns any of the basic builtin types

>>> u = Unpickler()
>>> u.restore('hello world')
'hello world'
>>> u.restore({'key': 'value'})
{'key': 'value'}
jsonpickle.unpickler.decode(string, backend=None, context=None, keys=False, reset=True, safe=False)
jsonpickle.unpickler.getargs(obj)

Return arguments suitable for __new__()

jsonpickle.unpickler.has_tag(obj, tag)

Helper class that tests to see if the obj is a dictionary and contains a particular key/tag.

>>> obj = {'test': 1}
>>> has_tag(obj, 'test')
True
>>> has_tag(obj, 'fail')
False
>>> has_tag(42, 'fail')
False
jsonpickle.unpickler.loadclass(module_and_name)

Loads the module and returns the class.

>>> cls = loadclass('datetime.datetime')
>>> cls.__name__
'datetime'
>>> loadclass('does.not.exist')
>>> loadclass('__builtin__.int')()
0
jsonpickle.unpickler.loadrepr(reprstr)

Returns an instance of the object from the object’s repr() string. It involves the dynamic specification of code.

>>> obj = loadrepr('datetime/datetime.datetime.now()')
>>> obj.__class__.__name__
'datetime'
jsonpickle.unpickler.make_blank_classic(cls)

Implement the mandated strategy for dealing with classic classes which cannot be instantiated without __getinitargs__ because they take parameters

jsonpickle.backend – JSON Backend Management

class jsonpickle.backend.JSONBackend(fallthrough=True)

Manages encoding and decoding using various backends.

It tries these modules in this order:
simplejson, json, demjson

simplejson is a fast and popular backend and is tried first. json comes with python2.6 and is tried second. demjson is the most permissive backend and is tried last.

decode(string)

Attempt to decode an object from a JSON string.

This tries the loaded backends in order and passes along the last exception if no backends are able to decode the string.

enable_fallthrough(enable)

Disable jsonpickle’s fallthrough-on-error behavior

By default, jsonpickle tries the next backend when decoding or encoding using a backend fails.

This can make it difficult to force jsonpickle to use a specific backend, and catch errors, because the error will be suppressed and may not be raised by the subsequent backend.

Calling enable_backend(False) will make jsonpickle immediately re-raise any exceptions raised by the backends.

encode(obj)

Attempt to encode an object into JSON.

This tries the loaded backends in order and passes along the last exception if no backend is able to encode the object.

load_backend(name, encode_name, decode_name, decode_exc)

Load a JSON backend by name.

This method loads a backend and sets up references to that backend’s encode/decode functions and exception classes.

Parameters:
  • encode_name – is the name of the backend’s encode method. The method should take an object and return a string.
  • decode_name – names the backend’s method for the reverse operation – returning a Python object from a string.
  • decode_exc – can be either the name of the exception class used to denote decoding errors, or it can be a direct reference to the appropriate exception class itself. If it is a name, then the assumption is that an exception class of that name can be found in the backend module’s namespace.
remove_backend(name)

Remove all entries for a particular backend.

set_encoder_options(name, *args, **kwargs)

Associate encoder-specific options with an encoder.

After calling set_encoder_options, any calls to jsonpickle’s encode method will pass the supplied args and kwargs along to the appropriate backend’s encode method.

For example:

set_encoder_options('simplejson', sort_keys=True, indent=4)
set_encoder_options('demjson', compactly=False)

See the appropriate encoder’s documentation for details about the supported arguments and keyword arguments.

set_preferred_backend(name)

Set the preferred json backend.

If a preferred backend is set then jsonpickle tries to use it before any other backend.

For example:

set_preferred_backend('simplejson')

If the backend is not one of the built-in jsonpickle backends (json/simplejson, or demjson) then you must load the backend prior to calling set_preferred_backend.

AssertionError is raised if the backend has not been loaded.

jsonpickle.util – Helper functions

Helper functions for pickling and unpickling. Most functions assist in determining the type of an object.

jsonpickle.util.b64decode(payload)
jsonpickle.util.b64encode(data)
jsonpickle.util.has_reduce(obj)

Tests if __reduce__ or __reduce_ex__ exists in the object dict or in the class dicts of every class in the MRO except object.

Returns a tuple of booleans (has_reduce, has_reduce_ex)

jsonpickle.util.importable_name(cls)
>>> class Example(object):
...     pass
>>> ex = Example()
>>> importable_name(ex.__class__)
'jsonpickle.util.Example'
>>> importable_name(type(25))
'__builtin__.int'
>>> importable_name(None.__class__)
'__builtin__.NoneType'
>>> importable_name(False.__class__)
'__builtin__.bool'
>>> importable_name(AttributeError)
'__builtin__.AttributeError'
jsonpickle.util.in_dict(obj, key, default=False)

Returns true if key exists in obj.__dict__; false if not in. If obj.__dict__ is absent, return default

jsonpickle.util.in_slots(obj, key, default=False)

Returns true if key exists in obj.__slots__; false if not in. If obj.__slots__ is absent, return default

jsonpickle.util.is_dictionary(obj)

Helper method for testing if the object is a dictionary.

>>> is_dictionary({'key':'value'})
True
jsonpickle.util.is_dictionary_subclass(obj)

Returns True if obj is a subclass of the dict type. obj must be a subclass and not the actual builtin dict.

>>> class Temp(dict): pass
>>> is_dictionary_subclass(Temp())
True
jsonpickle.util.is_function(obj)

Returns true if passed a function

>>> is_function(lambda x: 1)
True
>>> is_function(locals)
True
>>> def method(): pass
>>> is_function(method)
True
>>> is_function(1)
False
jsonpickle.util.is_installed(module)

Tests to see if module is available on the sys.path

>>> is_installed('sys')
True
>>> is_installed('hopefullythisisnotarealmodule')
False
jsonpickle.util.is_iterator(obj)
jsonpickle.util.is_list(obj)

Helper method to see if the object is a Python list.

>>> is_list([4])
True
jsonpickle.util.is_list_like(obj)
jsonpickle.util.is_module(obj)

Returns True if passed a module

>>> import os
>>> is_module(os)
True
jsonpickle.util.is_module_function(obj)

Return True if obj is a module-global function

>>> import os
>>> is_module_function(os.path.exists)
True
>>> is_module_function(lambda: None)
False
jsonpickle.util.is_noncomplex(obj)

Returns True if obj is a special (weird) class, that is more complex than primitive data types, but is not a full object. Including:

jsonpickle.util.is_object(obj)

Returns True is obj is a reference to an object instance.

>>> is_object(1)
True
>>> is_object(object())
True
>>> is_object(lambda x: 1)
False
jsonpickle.util.is_picklable(name, value)

Return True if an object can be pickled

>>> import os
>>> is_picklable('os', os)
True
>>> def foo(): pass
>>> is_picklable('foo', foo)
True
>>> is_picklable('foo', lambda: None)
False
jsonpickle.util.is_primitive(obj)

Helper method to see if the object is a basic data type. Strings, integers, longs, floats, booleans, and None are considered primitive and will return True when passed into is_primitive()

>>> is_primitive(3)
True
>>> is_primitive([4,4])
False
jsonpickle.util.is_reducible(obj)

Returns false if of a type which have special casing, and should not have their __reduce__ methods used

jsonpickle.util.is_sequence(obj)

Helper method to see if the object is a sequence (list, set, or tuple).

>>> is_sequence([4])
True
jsonpickle.util.is_sequence_subclass(obj)

Returns True if obj is a subclass of list, set or tuple.

obj must be a subclass and not the actual builtin, such as list, set, tuple, etc..

>>> class Temp(list): pass
>>> is_sequence_subclass(Temp())
True
jsonpickle.util.is_set(obj)

Helper method to see if the object is a Python set.

>>> is_set(set())
True
jsonpickle.util.is_tuple(obj)

Helper method to see if the object is a Python tuple.

>>> is_tuple((1,))
True
jsonpickle.util.is_type(obj)

Returns True is obj is a reference to a type.

>>> is_type(1)
False
>>> is_type(object)
True
>>> class Klass: pass
>>> is_type(Klass)
True
jsonpickle.util.itemgetter(obj, getter=<operator.itemgetter object at 0x10f455810>)
jsonpickle.util.translate_module_name(module)

Rename builtin modules to a consistent (Python2) module name

This is used so that references to Python’s builtins module can be loaded in both Python 2 and 3. We remap to the “__builtin__” name and unmap it when importing.

See untranslate_module_name() for the reverse operation.

jsonpickle.util.untranslate_module_name(module)

Rename module names mention in JSON to names that we can import

This reverses the translation applied by translate_module_name() to a module name available to the current version of Python.