README.rst

The jsonconversion package

This python module helps converting arbitrary Python objects into JSON strings and back. It extends the basic features of the JSONEncoder and JSONDecoder classes provided by the native json package. For this purpose, jsonconversion ships with these four classes:

The JSONObject class

Your serializable classes should inherit from this class. Hereby, they must implement the methods from_dict and to_dict. The example further down describes how to do so.

The JSONExtendedEncoder class

This is a class used internally by JSONObjectEncoder. However, it can also be used directly, if you do not need the features of JSONObjectEncoder but want to implement your own encoders.

The class is especially helpful, if you want custom handling of builtins (int, dict, ...) or classes deriving from builtins. This would not be possible if directly inheriting from JSONEncoder. To do so, override the isinstance method and return False for all types you want to handle in the default method.

If you look at the source code of JSONObjectEncoder, you will see how this can be used.

The JSONObjectEncoder class

Encodes Python objects into JSON strings. Supported objects are:

• Python builtins: int, float, str, list, set, dict, tuple
• type objects: isinstance(object, type)
• All classes deriving from JSONObject

Those objects can of course also be nested!

The JSONObjectDecoder class

Decodes JSON strings converted using the JSONObjectEncoder back to Python objects.

The class adds a custom keyword argument to the load[s] method: substitute_modules. This parameter takes a dict in the form {"old.module.MyClass": "new.module.MyClass"}. It can be used if you have serialized JSONObjects who's module path has changed.

Usage

Using jsonconversion is easy. You can find further code examples in the test folder.

Encoding and Decoding

In order to encode Python objects with JSON conversion and to later decode them, you have to import the Python module json. The module provides the methods dump/dumps for encoding and load/loads for decoding:

import json

from jsonconversion.decoder import JSONObjectDecoder
from jsonconversion.encoder import JSONObjectEncoder

var = (1, 2, 3)  # variable to be serialized

# "dumps" converts the variable to a string, "dump" directly writes it to a file
str_var = json.dumps(var, cls=JSONObjectEncoder)
# Equivalently, "loads" converts the object back from a string. "load" from a file
var_2 = json.loads(str_var, cls=JSONObjectDecoder)
assert var == var_2

Deriving from JSONObject

In order to serialize arbitrary, self-written classes, they must derive from JSONObject and implement the two methods from_dict and to_dict:

class MyClass(JSONObject):

    def __init__(self, a, b, c):
        self.a = a
        self.b = b
        self.c = c

    @classmethod
    def from_dict(cls, dict_):
        return cls(dict_['a'], dict_['b'], dict_['c'])

    def to_dict(self):
        return {'a': self.a, 'b': self.b, 'c': self.c}

    def __eq__(self, other):
        return self.a == other.a and self.b == other.b and self.c == other.c

General notes

• jsonconversion stores the class path in the JSON string when serializing a JSONObject. When decoding the object back, it automatically imports the correct module. You only have to ensure that the module is within your PYTHONPATH.
• The to_dict and from_dict methods only need to specify the elements of a class, needed to recreate the object. Derived attributes of a class (like age from year_born) do not need to be serialized.
• If you compare the original object with the object obtained from serialization and deserialization using is, they will differ, as these are objects at different locations in memory. Also a comparison of JSONObject with == will fail, if you do not tell Python how to compare two objects. This is why MyClass overrides the __eq__ method.