jsonlight 0.0.5

Standard types

This is what you can already do in Python:

from json import loads, dumps
from uuid import UUID, uuid4

obj = uuid4()
assert obj == UUID(loads(dumps(str(obj))))

All standard Python types such as UUID must have an encode/decode method in the default typemap provided by jsonlight, so encoding to JSON should always work. However, the type must be specified on load:

from jsonlight import loads, dumps
from uuid import UUID, uuid4

obj = uuid4()
assert obj == loads(UUID, dumps(obj))

You can see that the main difference with json.loads is that jsonlight.loads requires a type as first argument. This is because jsonlight.loads will first call json.loads to convert the string into a Python object with basic JSON tyes, and then pass that to the type’s __jsonload__ function.

Nested types

You may leverage the __jsondump__ and __jsonload__ methods based on the following conventions:

• __jsondump__: return a representation of self with JSON data types

• __jsonload__: instanciate an object based on the result from __jsondump__

Example:

from jsonlight import load

class YourClass:
    def __init__(self):
        self.now = datetime.now()

    def __jsondump__(self):
        return dict(now=self.now)

    @classmethod
    def __jsonload__(cls, data):
        return cls(load(datetime, data['now'])

As you can see:

• you don’t have to worry about calling __jsondump__ on return values of your own __jsondump__ because jsonlight.dumps will do that recursively,

• you have full control on deserialization just like with __setstate__, but if you call jsonlight.load in there yourself then you don’t have to duplicate deserialization logic on nested objects,

Typemaps

This lib must support all standard Python types, and it already works for things like UUID or Path because they cast fine from and to strings. However, this is not the case for datetimes and there is no JSON standard for datetimes.

Since it is a requirement for jsonlight to support all standard python types, a default typemap is also included, which makes datetimes export to string with .isoformat() and from string with .fromisoformat():

now = datetime.now()
assert now == loads(datetime, dumps(now))

This is the reason why we have typemaps. The typemap in jsonlight maps a Python type to a couple of encoding/decoding functions, so that we have something that works without monkey patching.

To illustrate how to use a specific typemap, let’s decide we want to remove the leading slash of all Path objects dumps and ensure there is one on load, we will define our own typemap:

typemap = {
    Path: (
        lambda value: str(value).lstrip('/'),
        lambda data: Path('/' + data.lstrip('/')),
    ),
}
assert dumps(Path('/foo/bar'), typemap) == '"foo/bar"'
assert loads(Path, '"foo/bar"', typemap)

A couple of possibilities are left to keep in mind:

• typemap.update(jsonlight.typemap) adds the default jsonlight typemap to your own,

• jsonlight.typemap.update(typemap) adds your own typemap on top of the default typemap.