# jsonpickle API

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

jsonpickle.encode(value, unpicklable=True, make_refs=True, keys=False, max_depth=None, reset=True, backend=None, warn=False, context=None, max_iter=None, use_decimal=False, numeric_keys=False, use_base85=False, fail_safe=None, indent=None, separators=None, include_properties=False, handle_readonly=False)

  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. It’s recommended to set this parameter to `False` when your code does not rely on two objects having the same `id()` value, and when it is sufficient for those two objects to be equal by `==`, such as when serializing sklearn instances. If you experience (de)serialization being incorrect when you use numpy, pandas, or sklearn handlers, this should be set to `False`. If you want the output to not include the dtype for numpy arrays, add:

          jsonpickle.register(
              numpy.generic, UnpicklableNumpyGenericHandler, base=True
          )

      before your pickling code.

    - 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(). This is typically what you want if you need to support Integer or objects as dictionary keys.

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

    - reset – Custom pickle handlers that use the Pickler.flatten method or jsonpickle.encode function must call encode with reset=False in order to retain object references during pickling. This flag is not typically used outside of a custom handler or __getstate__ implementation.

    - backend – If set to an instance of jsonpickle.backend.JSONBackend, jsonpickle will use that backend for deserialization.

    - warn – If set to True then jsonpickle will warn when it returns None for an object which it cannot pickle (e.g. file descriptors).

    - context – Supply a pre-built Pickler or Unpickler object to the jsonpickle.encode and jsonpickle.decode machinery instead of creating a new instance. The context represents the currently active Pickler and Unpickler objects when custom handlers are invoked by jsonpickle.

    - max_iter – If set to a non-negative integer then jsonpickle will consume at most max_iter items when pickling iterators.

    - use_decimal –

      If set to True jsonpickle will allow Decimal instances to pass-through, with the assumption that the simplejson backend will be used in use_decimal mode. In order to use this mode you will need to configure simplejson:

          jsonpickle.set_encoder_options('simplejson',
                                         use_decimal=True, sort_keys=True)
          jsonpickle.set_decoder_options('simplejson',
                                         use_decimal=True)
          jsonpickle.set_preferred_backend('simplejson')

      NOTE: A side-effect of the above settings is that float values will be converted to Decimal when converting to json.

    - numeric_keys – Only use this option if the backend supports integer dict keys natively. This flag tells jsonpickle to leave numeric keys as-is rather than conforming them to json-friendly strings. Using `keys=True` is the typical solution for integer keys, so only use this if you have a specific use case where you want to allow the backend to handle serialization of numeric dict keys.

    - use_base85 – If possible, use base85 to encode binary data. Base85 bloats binary data by 1/4 as opposed to base64, which expands it by 1/3. This argument is ignored on Python 2 because it doesn’t support it.

    - fail_safe – If set to a function exceptions are ignored when pickling and if a exception happens the function is called and the return value is used as the value for the object that caused the error

    - indent – When indent is a non-negative integer, then JSON array elements and object members will be pretty-printed with that indent level. An indent level of 0 will only insert newlines. `None` is the most compact representation. Since the default item separator is `(', ', ': ')`, the output might include trailing whitespace when `indent` is specified. You can use `separators=(',', ': ')` to avoid this. This value is passed directly to the active JSON backend library and not used by jsonpickle directly.

    - separators – If `separators` is an `(item_separator, dict_separator)` tuple then it will be used instead of the default `(', ', ': ')` separators. `(',', ':')` is the most compact JSON representation. This value is passed directly to the active JSON backend library and not used by jsonpickle directly.

    - include_properties – Include the names and values of class properties in the generated json. Properties are unpickled properly regardless of this setting, this is meant to be used if processing the json outside of Python. Certain types such as sets will not pickle due to not having a native-json equivalent. Defaults to `False`.

    - handle_readonly – Handle objects with readonly methods, such as Django’s SafeString. This basically prevents jsonpickle from raising an exception for such objects. You MUST set `handle_readonly=True` for the decoding if you encode with this flag set to `True`.

      >>> encode('my string') == '"my string"'
      True
      >>> encode(36) == '36'
      True
      >>> encode({'foo': True}) == '{"foo": true}'
      True
      >>> encode({'foo': [1, 2, [3, 4]]}, max_depth=1)
      '{"foo": "[1, 2, [3, 4]]"}'

jsonpickle.decode(string, backend=None, context=None, keys=False, reset=True, safe=True, classes=None, v1_decode=False, on_missing='ignore', handle_readonly=False)

  Convert a JSON string into a Python object.

  Parameters:

    - backend – If set to an instance of jsonpickle.backend.JSONBackend, jsonpickle will use that backend for deserialization.

    - context – Supply a pre-built Pickler or Unpickler object to the jsonpickle.encode and jsonpickle.decode machinery instead of creating a new instance. The context represents the currently active Pickler and Unpickler objects when custom handlers are invoked by jsonpickle.

    - keys – If set to True then jsonpickle will decode non-string dictionary keys into python objects via the jsonpickle protocol.

    - reset – Custom pickle handlers that use the Pickler.flatten method or jsonpickle.encode function must call encode with reset=False in order to retain object references during pickling. This flag is not typically used outside of a custom handler or __getstate__ implementation.

    - safe –

      If set to `False`, use of `eval()` for backwards-compatible (pre-0.7.0) deserialization of repr-serialized objects is enabled. Defaults to `True`. The default value was `False` in jsonpickle v3 and changed to `True` in jsonpickle v4.

      Warning

      `eval()` is used when set to `False` and is not secure against malicious inputs. You should avoid setting `safe=False`.

    - classes – If set to a single class, or a sequence (list, set, tuple) of classes, then the classes will be made available when constructing objects. If set to a dictionary of class names to class objects, the class object will be provided to jsonpickle to deserialize the class name into. This can be used to give jsonpickle access to local classes that are not available through the global module import scope, and the dict method can be used to deserialize encoded objects into a new class.

    - v1_decode – If set to True it enables you to decode objects serialized in jsonpickle v1. Please do not attempt to re-encode the objects in the v1 format! Version 2’s format fixes issue #255, and allows dictionary identity to be preserved through an encode/decode cycle.

    - on_missing – If set to ‘error’, it will raise an error if the class it’s decoding is not found. If set to ‘warn’, it will warn you in said case. If set to a non-awaitable function, it will call said callback function with the class name (a string) as the only parameter. Strings passed to on_missing are lowercased automatically.

    - handle_readonly – If set to True, the Unpickler will handle objects encoded with ‘handle_readonly’ properly. Do not set this flag for objects not encoded with ‘handle_readonly’ set to True.

      >>> decode('"my string"') == 'my string'
      True
      >>> 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` and `json`. The preferred 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:

> - `json`

> - simplejson

Experimental backends:

> - jsonlib

> - yajl via py-yajl

> - ujson

jsonpickle.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) 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(dumps='dumps', loads='loads', loads_exc=ValueError)

  Load a JSON backend by name.

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

  Parameters:

    - dumps – is the name of the backend’s encode method. The method should take an object and return a string. Defaults to ‘dumps’.

    - loads – names the backend’s method for the reverse operation – returning a Python object from a string.

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

    - load – names the backend’s ‘load’ method.

    - dump – names the backend’s ‘dump’ method.

  Rtype bool:

    True on success, False if the backend could not be loaded.

jsonpickle.remove_backend(name)

  Remove all entries for a particular backend.

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

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

  WARNING: If you pass sort_keys=True, and the object to encode contains `__slots__`, and you set `warn` to True, a TypeError will be raised!

jsonpickle.set_decoder_options(name, *args, **kwargs)

  Associate decoder-specific options with a decoder.

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

  For example:

      set_decoder_options('simplejson', encoding='utf8', cls=JSONDecoder)

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

### Customizing JSON output

jsonpickle supports the standard `pickle` __getstate__ and __setstate__ protocol for representing 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.

object._jsonpickle_exclude = set()

  Classes can specify attributes that they want to exclude from being pickled by defining an attribute named _jsonpickle_exclude. This set should contain the names of attributes of that class to exclude from being pickled.

### `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()`.

class jsonpickle.handlers.ArrayHandler(context)

  Flatten and restore array.array objects

  flatten(obj, data)

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

    Parameters:

      - obj (object) – The object to be serialized.

      - data (dict) – A partially filled dictionary which will contain the json-friendly representation of obj once this method has finished.

  restore(data)

    Restore an object of the registered type from the json-friendly representation obj and return it.

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

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

    Parameters:

      - obj (object) – The object to be serialized.

      - data (dict) – A partially filled dictionary which will contain the json-friendly representation of obj once this method has finished.

  classmethod handles(cls)

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

        @MyCustomHandler.handles
        class MyCustomClass:
            def __reduce__(self):
                ...

  restore(obj)

    Restore an object of the registered type from the json-friendly representation obj and return it.

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)

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

    Parameters:

      - obj (object) – The object to be serialized.

      - data (dict) – A partially filled dictionary which will contain the json-friendly representation of obj once this method has finished.

  restore(data)

    Restore an object of the registered type from the json-friendly representation obj and return it.

class jsonpickle.handlers.LockHandler(context)

  Serialize threading.Lock objects

  flatten(obj, data)

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

    Parameters:

      - obj (object) – The object to be serialized.

      - data (dict) – A partially filled dictionary which will contain the json-friendly representation of obj once this method has finished.

  restore(data)

    Restore an object of the registered type from the json-friendly representation obj and return it.

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)

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

    Parameters:

      - obj (object) – The object to be serialized.

      - data (dict) – A partially filled dictionary which will contain the json-friendly representation of obj once this method has finished.

  restore(data)

    Restore an object of the registered type from the json-friendly representation obj and return it.

class jsonpickle.handlers.RegexHandler(context)

  Flatten _sre.SRE_Pattern (compiled regex) objects

  flatten(obj, data)

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

    Parameters:

      - obj (object) – The object to be serialized.

      - data (dict) – A partially filled dictionary which will contain the json-friendly representation of obj once this method has finished.

  restore(data)

    Restore an object of the registered type from the json-friendly representation obj and return it.

class jsonpickle.handlers.Registry
  get(default=None)
    Parameters:

      - cls_or_name – the type or its fully qualified name

      - default – default value, if a matching handler is not found

    Looks up a handler by type reference or its fully qualified name. If a direct match is not found, the search is performed over all handlers registered with base=True.

  register(handler=None, base=False)

    Register the a custom handler for a class

    Parameters:

      - cls – The custom object class to handle

      - handler – The custom handler class (if None, a decorator wrapper is returned)

      - base – Indicates whether the handler should be registered for all subclasses

    This function can be also used as a decorator by omitting the handler argument:

        @jsonpickle.handlers.register(Foo, base=True)
        class FooHandler(jsonpickle.handlers.BaseHandler):
            pass

  unregister(cls)

class jsonpickle.handlers.TextIOHandler(context)

  Serialize file descriptors as None because we cannot roundtrip

  flatten(obj, data)

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

    Parameters:

      - obj (object) – The object to be serialized.

      - data (dict) – A partially filled dictionary which will contain the json-friendly representation of obj once this method has finished.

  restore(data)

    Restore should never get called because flatten() returns None

class jsonpickle.handlers.UUIDHandler(context)

  Serialize uuid.UUID objects

  flatten(obj, data)

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

    Parameters:

      - obj (object) – The object to be serialized.

      - data (dict) – A partially filled dictionary which will contain the json-friendly representation of obj once this method has finished.

  restore(data)

    Restore an object of the registered type from the json-friendly representation obj and return it.

jsonpickle.handlers.get(default=None)
  Parameters:

    - cls_or_name – the type or its fully qualified name

    - default – default value, if a matching handler is not found

  Looks up a handler by type reference or its fully qualified name. If a direct match is not found, the search is performed over all handlers registered with base=True.

jsonpickle.handlers.register(handler=None, base=False)

  Register the a custom handler for a class

  Parameters:

    - cls – The custom object class to handle

    - handler – The custom handler class (if None, a decorator wrapper is returned)

    - base – Indicates whether the handler should be registered for all subclasses

  This function can be also used as a decorator by omitting the handler argument:

      @jsonpickle.handlers.register(Foo, base=True)
      class FooHandler(jsonpickle.handlers.BaseHandler):
          pass

jsonpickle.handlers.unregister(cls)

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

### `jsonpickle.pickler` – Python to JSON-compatible dict

class jsonpickle.pickler.Pickler(unpicklable=True, make_refs=True, max_depth=None, backend=None, keys=False, warn=False, max_iter=None, numeric_keys=False, use_decimal=False, use_base85=False, fail_safe=None, include_properties=False, handle_readonly=False, original_object=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'
        True
        >>> 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'}
        True

  reset()

jsonpickle.pickler.encode(value, unpicklable=True, make_refs=True, keys=False, max_depth=None, reset=True, backend=None, warn=False, context=None, max_iter=None, use_decimal=False, numeric_keys=False, use_base85=False, fail_safe=None, indent=None, separators=None, include_properties=False, handle_readonly=False)

  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. It’s recommended to set this parameter to `False` when your code does not rely on two objects having the same `id()` value, and when it is sufficient for those two objects to be equal by `==`, such as when serializing sklearn instances. If you experience (de)serialization being incorrect when you use numpy, pandas, or sklearn handlers, this should be set to `False`. If you want the output to not include the dtype for numpy arrays, add:

          jsonpickle.register(
              numpy.generic, UnpicklableNumpyGenericHandler, base=True
          )

      before your pickling code.

    - 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(). This is typically what you want if you need to support Integer or objects as dictionary keys.

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

    - reset – Custom pickle handlers that use the Pickler.flatten method or jsonpickle.encode function must call encode with reset=False in order to retain object references during pickling. This flag is not typically used outside of a custom handler or __getstate__ implementation.

    - backend – If set to an instance of jsonpickle.backend.JSONBackend, jsonpickle will use that backend for deserialization.

    - warn – If set to True then jsonpickle will warn when it returns None for an object which it cannot pickle (e.g. file descriptors).

    - context – Supply a pre-built Pickler or Unpickler object to the jsonpickle.encode and jsonpickle.decode machinery instead of creating a new instance. The context represents the currently active Pickler and Unpickler objects when custom handlers are invoked by jsonpickle.

    - max_iter – If set to a non-negative integer then jsonpickle will consume at most max_iter items when pickling iterators.

    - use_decimal –

      If set to True jsonpickle will allow Decimal instances to pass-through, with the assumption that the simplejson backend will be used in use_decimal mode. In order to use this mode you will need to configure simplejson:

          jsonpickle.set_encoder_options('simplejson',
                                         use_decimal=True, sort_keys=True)
          jsonpickle.set_decoder_options('simplejson',
                                         use_decimal=True)
          jsonpickle.set_preferred_backend('simplejson')

      NOTE: A side-effect of the above settings is that float values will be converted to Decimal when converting to json.

    - numeric_keys – Only use this option if the backend supports integer dict keys natively. This flag tells jsonpickle to leave numeric keys as-is rather than conforming them to json-friendly strings. Using `keys=True` is the typical solution for integer keys, so only use this if you have a specific use case where you want to allow the backend to handle serialization of numeric dict keys.

    - use_base85 – If possible, use base85 to encode binary data. Base85 bloats binary data by 1/4 as opposed to base64, which expands it by 1/3. This argument is ignored on Python 2 because it doesn’t support it.

    - fail_safe – If set to a function exceptions are ignored when pickling and if a exception happens the function is called and the return value is used as the value for the object that caused the error

    - indent – When indent is a non-negative integer, then JSON array elements and object members will be pretty-printed with that indent level. An indent level of 0 will only insert newlines. `None` is the most compact representation. Since the default item separator is `(', ', ': ')`, the output might include trailing whitespace when `indent` is specified. You can use `separators=(',', ': ')` to avoid this. This value is passed directly to the active JSON backend library and not used by jsonpickle directly.

    - separators – If `separators` is an `(item_separator, dict_separator)` tuple then it will be used instead of the default `(', ', ': ')` separators. `(',', ':')` is the most compact JSON representation. This value is passed directly to the active JSON backend library and not used by jsonpickle directly.

    - include_properties – Include the names and values of class properties in the generated json. Properties are unpickled properly regardless of this setting, this is meant to be used if processing the json outside of Python. Certain types such as sets will not pickle due to not having a native-json equivalent. Defaults to `False`.

    - handle_readonly – Handle objects with readonly methods, such as Django’s SafeString. This basically prevents jsonpickle from raising an exception for such objects. You MUST set `handle_readonly=True` for the decoding if you encode with this flag set to `True`.

      >>> encode('my string') == '"my string"'
      True
      >>> encode(36) == '36'
      True
      >>> encode({'foo': True}) == '{"foo": true}'
      True
      >>> encode({'foo': [1, 2, [3, 4]]}, max_depth=1)
      '{"foo": "[1, 2, [3, 4]]"}'

### `jsonpickle.unpickler` – JSON-compatible dict to Python

class jsonpickle.unpickler.Unpickler(backend=None, keys=False, safe=True, v1_decode=False, on_missing='ignore', handle_readonly=False)
  register_classes(classes)

    Register one or more classes

    Parameters:

      classes – sequence of classes or a single class to register

  reset()

    Resets the object’s internal state.

  restore(obj, reset=True, classes=None)

    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'
        True
        >>> u.restore({'key': 'value'}) == {'key': 'value'}
        True

jsonpickle.unpickler.decode(string, backend=None, context=None, keys=False, reset=True, safe=True, classes=None, v1_decode=False, on_missing='ignore', handle_readonly=False)

  Convert a JSON string into a Python object.

  Parameters:

    - backend – If set to an instance of jsonpickle.backend.JSONBackend, jsonpickle will use that backend for deserialization.

    - context – Supply a pre-built Pickler or Unpickler object to the jsonpickle.encode and jsonpickle.decode machinery instead of creating a new instance. The context represents the currently active Pickler and Unpickler objects when custom handlers are invoked by jsonpickle.

    - keys – If set to True then jsonpickle will decode non-string dictionary keys into python objects via the jsonpickle protocol.

    - reset – Custom pickle handlers that use the Pickler.flatten method or jsonpickle.encode function must call encode with reset=False in order to retain object references during pickling. This flag is not typically used outside of a custom handler or __getstate__ implementation.

    - safe –

      If set to `False`, use of `eval()` for backwards-compatible (pre-0.7.0) deserialization of repr-serialized objects is enabled. Defaults to `True`. The default value was `False` in jsonpickle v3 and changed to `True` in jsonpickle v4.

      Warning

      `eval()` is used when set to `False` and is not secure against malicious inputs. You should avoid setting `safe=False`.

    - classes – If set to a single class, or a sequence (list, set, tuple) of classes, then the classes will be made available when constructing objects. If set to a dictionary of class names to class objects, the class object will be provided to jsonpickle to deserialize the class name into. This can be used to give jsonpickle access to local classes that are not available through the global module import scope, and the dict method can be used to deserialize encoded objects into a new class.

    - v1_decode – If set to True it enables you to decode objects serialized in jsonpickle v1. Please do not attempt to re-encode the objects in the v1 format! Version 2’s format fixes issue #255, and allows dictionary identity to be preserved through an encode/decode cycle.

    - on_missing – If set to ‘error’, it will raise an error if the class it’s decoding is not found. If set to ‘warn’, it will warn you in said case. If set to a non-awaitable function, it will call said callback function with the class name (a string) as the only parameter. Strings passed to on_missing are lowercased automatically.

    - handle_readonly – If set to True, the Unpickler will handle objects encoded with ‘handle_readonly’ properly. Do not set this flag for objects not encoded with ‘handle_readonly’ set to True.

      >>> decode('"my string"') == 'my string'
      True
      >>> decode('36')
      36

jsonpickle.unpickler.getargs(obj, classes=None)

  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.has_tag_dict(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, classes=None)

  Loads the module and returns the class.

      >>> cls = loadclass('datetime.datetime')
      >>> cls.__name__
      'datetime'

      >>> loadclass('does.not.exist')

      >>> loadclass('builtins.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.

  Warning

  This function is unsafe and uses eval().

      >>> 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, ujson

  simplejson is a fast and popular backend and is tried first. json comes with Python and is tried second.

  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.

  dumps(obj, indent=None, separators=None)

    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.

  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, indent=None, separators=None)

    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(dumps='dumps', loads='loads', loads_exc=ValueError)

    Load a JSON backend by name.

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

    Parameters:

      - dumps – is the name of the backend’s encode method. The method should take an object and return a string. Defaults to ‘dumps’.

      - loads – names the backend’s method for the reverse operation – returning a Python object from a string.

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

      - load – names the backend’s ‘load’ method.

      - dump – names the backend’s ‘dump’ method.

    Rtype bool:

      True on success, False if the backend could not be loaded.

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

  remove_backend(name)

    Remove all entries for a particular backend.

  set_decoder_options(name, *args, **kwargs)

    Associate decoder-specific options with a decoder.

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

    For example:

        set_decoder_options('simplejson', encoding='utf8', cls=JSONDecoder)

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

  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)

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

    WARNING: If you pass sort_keys=True, and the object to encode contains `__slots__`, and you set `warn` to True, a TypeError will be raised!

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

  Decode payload - must be ascii text.

jsonpickle.util.b64encode(data)

  Encode binary data to ascii text in base64. Data must be bytes.

jsonpickle.util.b85decode(payload)

  Decode payload - must be ascii text.

jsonpickle.util.b85encode(data)

  Encode binary data to ascii text in base85. Data must be bytes.

jsonpickle.util.has_method(obj, name)

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'
      True
      >>> importable_name(type(25)) == 'builtins.int'
      True
      >>> importable_name(None.__class__) == 'builtins.NoneType'
      True
      >>> importable_name(False.__class__) == 'builtins.bool'
      True
      >>> importable_name(AttributeError) == 'builtins.AttributeError'
      True

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

  Helper method to see if the object is a bytestring.

      >>> is_bytes(b'foo')
      True

jsonpickle.util.is_collections(obj)

jsonpickle.util.is_cython_function(obj)

  Returns true if the object is a reference to a Cython function

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

  Is the object an enum?

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:

  > - `struct_time`

jsonpickle.util.is_not_class(obj)

  Determines if the object is not a class or a class instance. Used for serializing properties.

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. Unicode 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_readonly(obj, attr, value)

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

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.is_unicode(obj)

  DEPRECATED: Helper method to see if the object is a unicode string

jsonpickle.util.itemgetter(obj, getter=operator.itemgetter(0))

jsonpickle.util.items(obj, exclude=())

  TODO: Replace all calls to this with plain dict.items()

jsonpickle.util.translate_module_name(module)

  Rename builtin modules to a consistent module name.

  Prefer the more modern naming.

  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.

  Map the Python2 exceptions module to builtins because builtins is a superset and contains everything that is available in exceptions, which makes the translation simpler.

  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.