Contents

• jsonpickle – High Level API
• Low Level API
  • jsonpickle.pickler – Python to JSON
  • jsonpickle.unpickler – JSON to Python
  • jsonpickle.util – Helper functions

jsonpickle – High Level API

jsonpickle.encode(value, unpicklable=True, max_depth=None, **kwargs)

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

The keyword argument ‘unpicklable’ defaults to True. If set to False, the output will not contain the information necessary to turn the JSON data back into Python objects.

The keyword argument ‘max_depth’ defaults to None. 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.

>>> 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)

Converts the JSON string into a Python object.

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

Low Level API

Typically this low level functionality is not needed by clients.

jsonpickle.pickler – Python to JSON

class jsonpickle.pickler.Pickler(unpicklable=True, max_depth=None)

Converts a Python object to a JSON representation.

Setting unpicklable to False removes the ability to regenerate the objects into object types beyond what the standard simplejson library supports.

Setting max_depth to a negative number means there is no limit to the depth jsonpickle should recurse into an object. Setting it to zero or higher places a hard limit on how deep jsonpickle recurses into objects, dictionaries, etc.

>>> p = Pickler()
>>> p.flatten('hello world')
'hello world'

flatten(obj)

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(u'hello world')
u'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'}

jsonpickle.unpickler – JSON to Python

class jsonpickle.unpickler.Unpickler

restore(obj)

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.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.

>>> loadclass('jsonpickle.tests.classes.Thing')
<class 'jsonpickle.tests.classes.Thing'>

>>> loadclass('example.module.does.not.exist.Missing')

>>> loadclass('jsonpickle.tests.classes.MissingThing')

jsonpickle.unpickler.loadrepr(reprstr)

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

>>> from jsonpickle import tags
>>> loadrepr('jsonpickle.tests.classes/jsonpickle.tests.classes.Thing("json")')
jsonpickle.tests.classes.Thing("json")

jsonpickle.util – Helper functions

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

jsonpickle.util.is_collection(obj)

Helper method to see if the object is a Python collection (list, set, or tuple). >>> is_collection([4]) True

jsonpickle.util.is_collection_subclass(obj)

Returns True if obj is a subclass of a collection type, such as list set, tuple, etc.. obj must be a subclass and not the actual builtin, such as list, set, tuple, etc..

>>> class Temp(list): pass
>>> is_collection_subclass(Temp())
True

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_list(obj)

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

>>> is_list([4])
True

jsonpickle.util.is_module(obj)

Returns True if passed a module

>>> import os
>>> is_module(os)
True

jsonpickle.util.is_noncomplex(obj)

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

• struct_time

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 cannot be pickled

>>> import os
>>> is_picklable('os', os)
True

>>> def foo(): pass
>>> is_picklable('foo', foo)
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_repr(obj)

Returns True if the obj must be encoded and decoded using the repr() function. Including:

• datetime
• date
• time
• timedelta

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