Skip to main content

json with rudimentary type encoding/decoding for Python

Project description

Adds support for a couple of new Python magic methods to make Python object oriented JSON encoding and decoding a bit easier, with the following goals in mind:

  • jsonlight.dumps should always work, even if it has to fallback to a string

  • it detects if an object being dumped defines a __jsondump__ method

  • it detects if an object being dumped is of a type defined in the global typemap, or the one that’s being used

  • for complete round-tripping, the type schema is maintained in a __jsonload__ method that you must implement

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__


from jsonlight import load

class YourClass:
    def __init__(self): =

    def __jsondump__(self):
        return dict(

    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,


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

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jsonlight-0.0.5.tar.gz (3.4 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page