__init__

Works with Python3.5+

JSON (de)serialization (jsons) from and to dicts and plain old Python objects.

Works with dataclasses (Python3.7+).

Example:

>>> from dataclasses import dataclass
>>> @dataclass
... class Car:
...     color: str
>>> @dataclass
... class Person:
...     car: Car
...     name: str
>>> c = Car('Red')
>>> p = Person(c, 'John')
>>> dumped = dump(p)
>>> dumped['name']
'John'
>>> dumped['car']['color']
'Red'
>>> p_reloaded = load(dumped, Person)
>>> p_reloaded.name
'John'
>>> p_reloaded.car.color
'Red'

Deserialization will work with older Python classes (Python3.5+) given that type hints are present for custom types (i.e. any type that is not set at the bottom of this module). Serialization will work with no type hints at all.

Example

>>> class Car:
...     def __init__(self, color):
...         self.color = color
>>> class Person:
...     def __init__(self, car: Car, name):
...         self.car = car
...         self.name = name
>>> c = Car('Red')
>>> p = Person(c, 'John')
>>> dumped = dump(p)
>>> dumped['name']
'John'
>>> dumped['car']['color']
'Red'
>>> p_reloaded = load(dumped, Person)
>>> p_reloaded.name
'John'
>>> p_reloaded.car.color
'Red'

Alternatively, you can make use of the JsonSerializable class.

Example

>>> class Car(JsonSerializable):
...     def __init__(self, color):
...         self.color = color
>>> class Person(JsonSerializable):
...     def __init__(self, car: Car, name):
...         self.car = car
...         self.name = name
>>> c = Car('Red')
>>> p = Person(c, 'John')
>>> dumped = p.json
>>> dumped['name']
'John'
>>> dumped['car']['color']
'Red'
>>> p_reloaded = Person.from_json(dumped)
>>> p_reloaded.name
'John'
>>> p_reloaded.car.color
'Red'

Package Contents

Classes

Functions

dumps(obj, *args, **kwargs)

Extend json.dumps, allowing any Python instance to be dumped to a string. Any extra (keyword) arguments are passed on to json.dumps.

Parameters:
  • obj – the object that is to be dumped to a string.
  • args – extra arguments for json.dumps.
  • kwargs – extra keyword arguments for json.dumps. They are also

passed on to the serializer function. :return: obj as a str.

loads(str_, cls=None, *args, **kwargs)

Extend json.loads, allowing a string to be loaded into a dict or a Python instance of type cls. Any extra (keyword) arguments are passed on to json.loads.

Parameters:
  • str – the string that is to be loaded.
  • cls – a matching class of which an instance should be returned.
  • args – extra arguments for json.dumps.
  • kwargs – extra keyword arguments for json.dumps. They are also

passed on to the deserializer function. :return: an instance of type cls or a dict if no cls is given.

set_serializer(func, cls, high_prio=True)

Set a serializer function for the given type. You may override the default behavior of jsons.load by setting a custom serializer.

Parameters:
  • func – the serializer function.
  • cls – the type this serializer can handle.
  • high_prio – determines the order in which is looked for the callable.
Returns:

None.

set_deserializer(func, cls, high_prio=True)

Set a deserializer function for the given type. You may override the default behavior of jsons.dump by setting a custom deserializer.

Parameters:
  • func – the deserializer function.
  • cls – the type this serializer can handle.
  • high_prio – determines the order in which is looked for the callable.
Returns:

None.

class JsonSerializable

This class offers an alternative to using the jsons.load and jsons.dump methods. An instance of a class that inherits from JsonSerializable has the json property, which value is equivalent to calling jsons.dump on that instance. Furthermore, you can call from_json on that class, which is equivalent to calling json.load with that class as an argument.

with_dump(**kwargs)

Return a class (type) that is based on JsonSerializable with the dump method being automatically provided the given kwargs.

Example:

>>> custom_serializable = JsonSerializable\
        .with_dump(key_transformer=KEY_TRANSFORMER_CAMELCASE)
>>> class Person(custom_serializable):
...     def __init__(self, my_name):
...         self.my_name = my_name
>>> p = Person('John')
>>> p.json
{'myName': 'John'}
Parameters:kwargs – the keyword args that are automatically provided to the

dump method. :return: a class with customized behavior.

with_load(**kwargs)

Return a class (type) that is based on JsonSerializable with the load method being automatically provided the given kwargs.

Example:

>>> custom_serializable = JsonSerializable\
        .with_load(key_transformer=KEY_TRANSFORMER_SNAKECASE)
>>> class Person(custom_serializable):
...     def __init__(self, my_name):
...         self.my_name = my_name
>>> p_json = {'myName': 'John'}
>>> p = Person.from_json(p_json)
>>> p.my_name
'John'
Parameters:kwargs – the keyword args that are automatically provided to the

load method. :return: a class with customized behavior.

json()

See jsons.dump. :return: this instance in a JSON representation (dict).

from_json(json_obj, **kwargs)

See jsons.load. :param json_obj: a JSON representation of an instance of the inheriting class :param kwargs: the keyword args are passed on to the deserializer function. :return: an instance of the inheriting class.

dump(**kwargs)

See jsons.dump. :param kwargs: the keyword args are passed on to the serializer function. :return: this instance in a JSON representation (dict).

load(json_obj, **kwargs)

See jsons.load. :param kwargs: the keyword args are passed on to the serializer function. :return: this instance in a JSON representation (dict).