~ Any Python objects to/from JSON, easily! ~

Jsons is a library that allows you to serialize your plain old Python objects to readable json (dicts or strings) and deserialize them back. No magic, no special types, no polluting your objects. Just you, Python and clean json.

Features¶

Python 3.5+
Minimal effort to use!
No magic, just you, Python and jsons!
Human readible JSON without pollution!
Easily customizable and extendable!
Type hints for the win!

Installing and using¶

Install with pip or conda:

pip install jsons
or
conda install -c conda-forge jsons

And then you’re ready to go:

import jsons

@dataclass
class Car:
    color: str
    owner: str

dumped = jsons.dump(Car('red', 'Guido'))

The value of dumped:

{'color': 'red', 'owner': 'Guido'}

And to deserialize, just do:

instance = jsons.load(dumped, Car)

Type hints for the win!

FAQ¶

Frequently Asked Questions¶

Do I need to use dataclasses?¶

No, not necessarily. The following example shows a class that jsons can serialize and deserialize without a problem:

class Person:
    def __init__(self, name: str, car: Car):
        self.name = name
        self.car = car

Do I need to use type hints?¶

No, not necessarily, (but it is recommended to do so anyway for readability). Only if your class has an attribute of a custom class type, you need to use a type hint for proper deserialization with jsons. Serialization works always, no matter the presence or absence of type hints.

Here is an example:

class Person:
    def __init__(self, name, birthday, car: Car):
        self.name = name
        self.birthday = birthday
        self.car = car

This class does not require type hints for name and birthday (assuming that they are meant to be of type str and datetime respectively). The Car is a custom class though, so that one needs a type hint if you want deserialization to work.

So in short: only for custom classes and only for deserialization.

How can I improve the performance of jsons?¶

With large data sets, it may take some time for jsons to dump or load. This is caused by several checks and scans that jsons does. You can increase the speed significantly by using “strict mode”: jsons.dump(some_obj, strict=True). Also make sure to provide type hints for your classes’ attributes. This will allow jsons to scan your class only once and use that to get the attributes of every object of that class it encounters.

On top of that, you could see if parallelization gains you anything: jsons.dump(some_obj, strict=True, tasks=4). By default a Process is spawned per task, but you can also choose to use Thread by providing task_type=Thread.

Is it possible to discard private attributes?¶

Yes it is. Use strip_privates for that.

jsons.dump(some_inst, strip_privates=True)

How can I write a custom serializer?¶

First create your serializer function. It requires at least the parameters obj and **kwargs. You may introduce additional parameters to your liking.

Here is an example:

def my_custom_datetime_serializer(obj: datetime,
                                  only_seconds: bool = False,
                                  **kwargs) -> Union[int, float]:
    if only_seconds:
        return int(obj.timestamp())
    return obj.timestamp()

Note: the type hints are not required.

Next, you need to register your serializer function with the type you want to use that serializer function for:

jsons.set_serializer(my_custom_datetime_serializer, datetime)

And you’re set:

>>> my_date = datetime.now(tz=timezone.utc)
>>> jsons.dump(my_date, only_seconds=True)
1552819054

How can I write a custom deserializer?¶

First create your deserializer function. It requires at least the parameters obj, cls and **kwargs. You may introduce additional parameters to your liking.

Here is an example:

def my_custom_datetime_deserializer(obj: Union[int, float],
                                    cls: type = datetime,
                                    **kwargs) -> datetime:
    return datetime.fromtimestamp(ts)

Note: the type hints are not required.

Next, you need to register your deserializer function with the type you want to use that deserializer function for:

jsons.set_deserializer(my_custom_datetime_deserializer, datetime)

And you’re set:

>>> jsons.load(1552819054, datetime)
datetime.datetime(2019, 3, 17, 11, 37, 34)

Why does jsons tolerate additional attributes in my json object compared to the class?¶

The thoughts on this are as follows:

jsons was designed to be very tolerant by default.
jsons is in fact capable of deserializing json data into a class with fewer attributes; all required fields were provided. So it is reasonable that no error should occur.
jsons should be compatible with json schemas and they allow extra attributes by default as well.

You can however turn ‘strict-mode’ on:

jsons.load(some_json, cls=SomeClass, strict=True)

By doing so, any mismatch between the json object and the class results in a DeserializationError.

How can I deserialize without exactly knowing the target class?¶

Sometimes you do not know beforehand of which exact class you have a json instance.

There are two ways to deal with this. The first is to use a Union and define all possible types that you want to deserialize to:

jsons.load(car_json, Union[Audi, Porche, Tesla], strict=True)

The possible classes are examined from left to right and the first successful deserialization is returned.

The second option is to serialize verbose objects:

car_json = jsons.dump(car_inst, verbose=True)

When loading a verbose object, you may omit the expected class:

car_inst = jsons.load(car_json)

Why not just use `dict`?¶

For the following reasons:

The __dict__ attribute only creates a shallow dict of an instance. Any contained object is not serialized to a dict.
The __dict__ does not take @property methods in account.
Not all objects have a __dict__ attribute (e.g. datetime does not).
The serialization process of __dict__ cannot easily be tuned.
There is no means to deserialize with __dict__.

Why not use the standard `json` library?¶

For the following reasons:

It’s quite a hassle to (de)serialize custom types: you need to write a subclass of json.JSONEncoder with specific serialization/deserialization code per custom class.
You will need to provide that subclass of json.JSONEncoder to json.dumps/json.loads every single time.

Aren’t there already libraries for serialization to json?¶

There are.

Here is how jsonpickle serializes a datetime:

>>> jsonpickle.encode(my_date)
'{"py/object": "datetime.datetime", "__reduce__": [{"py/type": "datetime.datetime"}, ["B+MDEBUYLgVu1w=="]]}'

And this is how jsons does it:

>>> jsons.dumps(my_date)
'"2019-03-16T21:24:46.356055+01:00"'

And this is what marshmallow requires your classes to look like:

class AlbumSchema(Schema):
    title = fields.Str()
    release_date = fields.Date()
    artist = fields.Nested(ArtistSchema())

Compare that to jsons:

class AlbumSchema:
    def __init__(self, title: str, release_date: datetime, artist: Artist)
        self.title = title
        self.release_date = release_date
        self.artist = artist

# Or even better, using a dataclass:

@dataclass
class AlbumSchema:
        title: str
        release_date: datetime
        artist: Artist

And this is what a serpy serializer for your custom class looks like:

class FooSerializer(serpy.Serializer):
    """The serializer schema definition."""
    # Use a Field subclass like IntField if you need more validation.
    x = serpy.IntField()
    y = serpy.Field()
    z = serpy.Field()

Compared to that of jsons:

# Not Necessary at all.

So yes. There are already libraries for serializing Python to json. There may be some advantages for each library, so you should do your homework.

My json contains camelcase, how can I transform to the right case?¶

You can have the keys transformed by the serialization or deserialization process by providing a transformer function that takes a string and returns a string.

result = jsons.dump(some_obj, key_transformer=jsons.KEY_TRANSFORMER_CAMELCASE)
# result could be something like: {'thisIsTransformed': 123}

result = jsons.load(some_dict, SomeClass,
                    key_transformer=jsons.KEY_TRANSFORMER_SNAKECASE)
# result could be something like: {'this_is_transformed': 123}

The following casing styles are supported:

KEY_TRANSFORMER_SNAKECASE   # snake_case
KEY_TRANSFORMER_CAMELCASE   # camelCase
KEY_TRANSFORMER_PASCALCASE  # PascalCase
KEY_TRANSFORMER_LISPCASE    # lisp-case

How do the jsons decorators work?¶

Use loaded to automatically apply jsons.load to the parameters and/or the return value.

Here is an example:

from datetime import datetime
from jsons.decorators import loaded


@loaded()
def some_func(x: datetime) -> datetime:
    # x is now of type datetime.
    return '2018-10-07T19:05:00+02:00'

result = some_func('2018-10-07T19:05:00+02:00')
# result is now of type datetime.

In the above case, the type hint could be omitted for the same result: jsons will recognize the timestamp from the string automatically. In case of a custom type, you do need a type hint. The same goes for the return type; it could be omitted in this case as well.

Similarly, you can decorate a function or method with @dumped as is done below:

from datetime import datetime
from jsons.decorators import dumped


class SomeClass:
    @classmethod
    @dumped()
    def some_meth(cls, x):
        # x is now of type str, cls remains untouched.
        return datetime.now()

result = SomeClass.some_meth(datetime.now())
# result is now of type str.

In case of methods, like in the example above, the special self or cls parameters are not touched by the decorators @loaded() or @dumped(). Additionally, you can provide a type hint for any parameter (except self or cls) or the return value. Doing so will make jsons attempt to dump into that particular type, just like with jsons.dump(some_obj, cls=ParticularType).

For more info, see the api doc.

Can I just participate in discussions on the issues?¶

Yes, please do. Your opinion is highly valuated and appreciated.

I have an idea for a new feature, what should I do?¶

Please always check the API first, maybe your feature was already there. :-) Otherwise, open up an issue and describe your desired feature and why one would want this.

You can also open a pull request. It is advised to first open a discussion in an issue though.

I found a bug, what should I do?¶

Please report bugs by opening an issue on the Github page.

My question is not listed here!¶

I’m sorry for that. Please open up an issue on the Github page.

API¶

Main functions¶

dump¶

This is the main serialization function of jsons. It will look for the best fitting serializer function that is registered and use that to turn the given object to a JSON compatible type.

Any parameter of a serializer function, can be set using the keyword arguments of dump. Here is an overview of the standard options:

Parameter	Type	Description
strip_microseconds	`bool`	Microseconds are not included in serialized datetimes.
strip_nulls	`bool`	The resulting JSON will not contain attributes with values that are `null`.
strip_privates	`bool`	Private attributes (starting with `_`) are omitted.
strip_properties	`bool`	Properties (`@property`) are omitted.
use_enum_name	`bool`	When `True`, enums are serialized as their names. Otherwise their values are used.
key_transformer	`Callable[[str], str]`	Transforms the keys of the resulting dict. For example, `jsons.KEY_TRANSFORMER_CAMELCASE` turns all keys in ‘camelCase’.
verbose	`verbose: Union[Verbosity, bool]`	This parameter allows you to specify whether and how meta data should be outputted. If `WITH_CLASS_INFO` or `WITH_EVERYTHING` is used, the output contain typing info. With that info `jsons.load` does not need a `cls` argument.

Here is an example:

>>> @dataclass
... class C:
...     _foo: int
...     bar: int
>>> c = C(1, 2)
>>> jsons.dump(c, strip_privates=True)
{'bar': 2}

For more info, check out the parameters of the serializers.

Function signature:

Function:	`jsons.dump`
Description:	Serialize the given object to a JSON compatible type (e.g. dict, list, string, etc.)
Arguments:	`obj: object`	The object that is to be serialized.
	`cls: Optional[type]`	If given, `obj` will be dumped as if it is of type `type`.
	`fork_inst: Optional[type]`	If given, the serializer functions of this fork of `JsonSerializable` are used.
	`kwargs`	Keyword arguments will be passed on to the serializer functions.
Returns:	`object`	The serialized `obj` as a JSON type.
Example:	>>> some_utcdate = datetime.now(tz=timezone.utc) >>> jsons.dump(some_utcdate) '2019-02-16T20:33:36Z'

load¶

Function:	`jsons.load`
Description:	Deserialize the given object to a Python equivalent type or an instance of type `cls` (if given).
Arguments:	`json_obj: object`	The object that is to be deserialized.
	`cls: Optional[type]`	A matching class of which an instance should be returned.
	`strict: bool`	Determines strict mode (e.g. fail on partly deserialized objects).
	`fork_inst: Optional[type]`	If given, the deserializer functions of this fork of `JsonSerializable` are used.
	`attr_getters: Optional[Dict[str, Callable[[], object]]]`	A dict that may hold callables that return values for certain attributes.
	`kwargs`	Keyword arguments will be passed on to the deserializer functions.
Returns:	`object`	An object of a Python equivalent type or of `cls`.
Example:	>>> jsons.load('2019-02-16T20:33:36Z', datetime) datetime.datetime(2019, 2, 16, 20, 33, 36, tzinfo=datetime.timezone.utc)

dumps¶

Function:	`jsons.dumps`
Description:	Serialize the given object to a string.
Arguments:	`obj: object`	The object that is to be stringified.
	`jdkwargs`	Extra keyword arguments for `json.dumps` (not `jsons.dumps`!)
	`args`	Extra arguments for `jsons.dumps`.
	`kwargs`	Keyword arguments that are passed on through the serialization process.
Returns:	`object`	An object of a Python equivalent type or of `cls`.
Example:	>>> jsons.dumps([1, 2, 3]) '[1, 2, 3]'

loads¶

Function:	`jsons.loads`
Description:	Deserialize a given JSON string to a Python equivalent type or an instance of type `cls` (if given).
Arguments:	`str_: str`	The string containing the JSON that is to be deserialized.
	`cls: Optional[type]`	A matching class of which an instance should be returned.
	`jdkwargs`	Extra keyword arguments for `json.loads` (not `jsons.loads`!).
	`args`	Extra arguments for `jsons.load`.
	`kwargs`	Keyword arguments that are passed on through the deserialization process.
Returns:	`object`	An object of a Python equivalent type or of `cls`.
Example:	>>> jsons.loads('[1, 2, 3]') [1, 2, 3]

dumpb¶

Function:	`jsons.dumpb`
Description:	Serialize the given object to bytes that contain JSON.
Arguments:	`obj: object`	The object that is to be serialized.
	`encoding: str`	The encoding that is used to transform from bytes.
	`jdkwargs`	Extra keyword arguments for `json.dumps` (not `jsons.dumps`!)
	`args`	Extra arguments for `jsons.dumps`.
	`kwargs`	Keyword arguments that are passed on through the serialization process.
Returns:	`bytes`	A serialized `obj` in bytes.
Example:	>>> jsons.dumpb([1, 2, 3]) b'[1, 2, 3]'

loadb¶

Function:	`jsons.loadb`
Description:	Deserialize the given bytes holding JSON to a Python equivalent type or an instance of type `cls` (if given).
Arguments:	`bytes_: bytes`	The bytes containing the JSON that is to be deserialized.
	`cls: Optional[type]`	A matching class of which an instance should be returned.
	`encoding: str`	The encoding that is used to transform from bytes.
	`jdkwargs`	Extra keyword arguments for `json.loads` (not `jsons.loads`!)
	`args`	Extra arguments for `jsons.loads`.
	`kwargs`	Keyword arguments that are passed on through the deserialization process.
Returns:	`object`	An object of a Python equivalent type or of `cls`.
Example:	>>> jsons.loadb(b'[1, 2, 3]') [1, 2, 3]

fork¶

Function:	`jsons.fork`
Description:	Create a “fork instance” that contains its own settings (serializers, deserializers, etc.) separately.
Arguments:	`fork_inst: Type[T]`	If given, the new fork is based on the given fork.
Arguments:	`name: Optional[str]`	The name of the newly created fork.
Returns:	`Type[T]`	A “fork instance” that you can pass to most `jsons` functions (e.g. `dump`).
Example:	>>> fork_inst = jsons.fork() >>> jsons.set_serializer(lambda _, *__: 'Fork!', str, fork_inst=fork_inst) >>> jsons.dump('Any string') 'Any string' >>> jsons.dump('Any string', fork_inst=fork_inst) 'Fork!'

set_serializer¶

Function:	`jsons.set_serializer`
Description:	Set a serializer function for the given type. The callable must accept at least two arguments: the object to serialize and kwargs. It must return an object that has a JSON equivalent type (e.g. dict, list, string, …).
Arguments:	`func: callable`	The serializer function.
	`cls: Union[type, Sequence[type]]`	The type or sequence of types that `func` can serialize.
	`high_prio: bool`	If `True`, then `func` will take precedence over any other serializer function that serializes `cls`.
	`fork_inst`	If given, it registers `func` to this fork of `JsonSerializable`, rather than the global `jsons`.
Returns:	`None`
Example:	>>> jsons.set_serializer(lambda obj, **_: 123, str) >>> jsons.dump('any string') 123

get_serializer¶

Function:	`jsons.get_serializer`
Description:	Return the serializer function that would be used for the given `cls`.
Arguments:	`cls: type`	The type of which the deserializer is requested.
Arguments:	`fork_inst`	If given, it uses this fork of `JsonSerializable`.
Returns:	`callable`	The serializer function.
Example:	>>> jsons.get_serializer(str) <function get_serializer at 0x02F36A50>

set_deserializer¶

Function:	`jsons.set_deserializer`
Description:	Set a deserializer function for the given type. The callable must accept at least three arguments: the object to deserialize, the type to deserialize to and kwargs. It must return a deserialized object of type cls.
Arguments:	`func: callable`	The deserializer function.
	`cls: Union[type, Sequence[type]]`	The type or sequence of types that `func` can deserialize.
	`high_prio: bool`	If `True`, then `func` will take precedence over any other deserializer function that serializes `cls`.
	`fork_inst`	If given, it registers `func` to this fork of `JsonSerializable`, rather than the global `jsons`.
Returns:	`None`
Example:	>>> jsons.set_deserializer(lambda obj, cls, **_: 123, str) >>> jsons.load('any string') 123

get_deserializer¶

Function:	`jsons.get_deserializer`
Description:	Return the deserializer function that would be used for the given `cls`.
Arguments:	`cls: type`	The type of which the deserializer is requested.
Arguments:	`fork_inst`	If given, it uses this fork of `JsonSerializable`.
Returns:	`callable`	The deserializer function.
Example:	>>> jsons.get_deserializer(str) <function get_deserializer at 0x02F36A98>

suppress_warnings¶

Function:	`jsons.set_deserializer`
Description:	Suppress (or stop suppressing) warnings.
Arguments:	`do_suppress: Optional[bool]`	if `True`, warnings will be suppressed from now on.
	`cls: type`	The type that `func` can deserialize.
	`high_prio: bool`	If `True`, then `func` will take precedence over any other deserializer function that serializes `cls`.
	`fork_inst`	If given, it only suppresses (or stops suppressing) warnings of the given fork.
Returns:	`None`
Example:	>>> jsons.suppress_warnings()

set_validator¶

Function:	`jsons.set_validator`
Description:	Set a validator function for the given `cls`. The function should accept an instance of the type it should validate and must return `False` or raise any exception in case of a validation failure.
Arguments:	`func: callable`	The function that takes an instance of type `cls` and returns a bool (`True` if the validation was successful).
	`cls: Union[type, Sequence[type]]`	The type or types that `func` is able to validate.
	`fork_inst`	If given, it registers `func` to this fork of `JsonSerializable`, rather than the global `jsons`.
Returns:	`None`
Example:	>>> jsons.set_validator(lambda x: x >= 0, int) >>> jsons.load(-1) jsons.exceptions.ValidationError: Validation failed.

get_validator¶

Function:	`jsons.get_validator`
Description:	Return the validator function that would be used for the given `cls`.
Arguments:	`cls: type`	The type of which the validator is requested.
Arguments:	`fork_inst`	If given, it uses this fork of `JsonSerializable`.
Returns:	`callable`	The validator function.
Example:	>>> jsons.get_validator(str) <function str_validator at 0x02F36A98>

Classes¶

JsonSerializable¶

This class can be used as a base class for your models.

@dataclass
class Car(JsonSerializable):
    color: str
    owner: str

You can now dump your model using the json property:

car = Car('red', 'Gary')
dumped = car.json  # == jsons.dump(car)

The JSON data can now also be loaded using your model:

loaded = Car.from_json(dumped)  # == jsons.load(dumped, Car)

fork¶

Method:	@classmethod `jsons.JsonSerializable.fork`
Description:	Create a ‘fork’ of `JsonSerializable`: a new `type` with a separate configuration of serializers and deserializers.
Arguments:	`name: Optional[str]`	The name of the new fork (accessable with `__name__`).
Returns:	`type`	A new `type` based on `JsonSerializable`.
Example:	>>> fork = jsons.JsonSerializable.fork() >>> jsons.set_deserializer(lambda obj, _, __: 'Regular!', str) >>> fork.set_deserializer(lambda obj, _, **__: 'Fork!', str) >>> jsons.load('any string') 'Regular!' >>> jsons.load('any string', fork_inst=fork) 'Fork!'

with_dump¶

Method:	@classmethod `jsons.JsonSerializable.with_dump`
Description:	Return a class (`type`) that is based on JsonSerializable with the``dump`` method being automatically provided the given `kwargs`.
Arguments:	`fork: Optional[bool]`	Determines whether a new fork is to be created. See also `JsonSerializable.fork` and `JsonSerializable.with_load`.
Arguments:	`kwargs`	Any keyword arguments that are to be passed on through the serialization process.
Returns:	`type`	Returns the `JsonSerializable` class or its fork (to allow you to stack).
Example:	>>> @dataclass ... class Person(JsonSerializable ... .with_dump(key_transformer=KEY_TRANSFORMER_CAMELCASE) ... .with_load(key_transformer=KEY_TRANSFORMER_SNAKECASE)): ... first_name: str ... last_name: str >>> Person('Johnny', 'Jones').json {'firstName': 'Johnny', 'lastName': 'Jones'}

json¶

Method:	@property `jsons.JsonSerializable.json`
Description:	See `jsons.dump`.
Arguments:	`kwargs`	See `jsons.dump`.
Returns:	`object`	See `jsons.dump`.
Example:	>>> @dataclass ... class Person(jsons.JsonSerializable): ... name: str >>> Person('Johnny').json {"name": "Johnny"}

dump¶

Method:	`jsons.JsonSerializable.dump`
Description:	See `jsons.dump`.
Arguments:	`kwargs`	See `jsons.dump`.
Returns:	`object`	See `jsons.dump`.
Example:	>>> @dataclass ... class Person(jsons.JsonSerializable): ... name: str >>> Person('Johnny').dump() {"name": "Johnny"}

dumps¶

Method:	`jsons.JsonSerializable.dumps`
Description:	See `jsons.dumps`.
Arguments:	`kwargs`	See `jsons.dumps`.
Returns:	`object`	See `jsons.dumps`.
Example:	>>> @dataclass ... class Person(jsons.JsonSerializable): ... name: str >>> Person('Johnny').dumps() '{"name": "Johnny"}'

dumpb¶

Method:	`jsons.JsonSerializable.dumpb`
Description:	See `jsons.dumpb`.
Arguments:	`kwargs`	See `jsons.dumpb`.
Returns:	`object`	See `jsons.dumpb`.
Example:	>>> @dataclass ... class Person(jsons.JsonSerializable): ... name: str >>> Person('Johnny').dumpb() b'{"name": "Johnny"}'

from_json¶

Method:	@classmethod `jsons.JsonSerializable.from_json`
Description:	See `jsons.load`.
Arguments:	`json_obj: object`	See `jsons.load`.
Arguments:	`kwargs`	See `jsons.load`.
Returns:	`object`	See `jsons.load`.
Example:	>>> @dataclass ... class Person(jsons.JsonSerializable): ... name: str >>> Person.from_json({'name': 'Johnny'}) '{"name": "Johnny"}'

load¶

Method:	@classmethod `jsons.JsonSerializable.load`
Description:	See `jsons.load`.
Arguments:	`json_obj: object`	See `jsons.load`.
Arguments:	`kwargs`	See `jsons.load`.
Returns:	`object`	See `jsons.load`.
Example:	>>> @dataclass ... class Person(jsons.JsonSerializable): ... name: str >>> Person.load({'name': 'Johnny'}) '{"name": "Johnny"}'

loads¶

Method:	@classmethod `jsons.JsonSerializable.loads`
Description:	See `jsons.loads`.
Arguments:	`json_obj: object`	See `jsons.loads`.
Arguments:	`kwargs`	See `jsons.loads`.
Returns:	`object`	See `jsons.loads`.
Example:	>>> @dataclass ... class Person(jsons.JsonSerializable): ... name: str >>> Person.loads('{"name": "Johnny"}') '{"name": "Johnny"}'

loadb¶

Method:	@classmethod `jsons.JsonSerializable.loadb`
Description:	See `jsons.loadb`.
Arguments:	`json_obj: object`	See `jsons.loadb`.
Arguments:	`kwargs`	See `jsons.loadb`.
Returns:	`object`	See `jsons.loadb`.
Example:	>>> @dataclass ... class Person(jsons.JsonSerializable): ... name: str >>> Person.loads(b'{"name": "Johnny"}') '{"name": "Johnny"}'

set_serializer¶

Method:	@classmethod `jsons.JsonSerializable.set_serializer`
Description:	See `jsons.set_serializer`.
Arguments:	`func: callable`	See `jsons.set_serializer`.
	`cls_: type`	Note the trailing underscore. See `cls` of `jsons.set_serializer`.
	`high_prio: Optional[bool]`	See `jsons.set_serializer`.
	`fork: Optional[bool]`	If `True`, a fork is created and the serializer is added to that fork.
Returns:	`type`	Returns the `JsonSerializable` class or its fork (to allow you to stack).
Example:	>>> class BaseModel(JsonSerializable ... .set_serializer(lambda obj, cls, **_: obj.upper(), str)): ... pass >>> @dataclass ... class Person(BaseModel): ... name: str >>> Person('Arnold').json {'name': 'ARNOLD'}

set_deserializer¶

Method:	@classmethod `jsons.JsonSerializable.set_deserializer`
Description:	See `jsons.set_deserializer`.
Arguments:	`func: callable`	See `jsons.set_deserializer`.
	`cls_: type`	Note the trailing underscore. See `cls` of `jsons.set_deserializer`.
	`high_prio: Optional[bool]`	See `jsons.set_deserializer`.
	`fork: Optional[bool]`	If `True`, a fork is created and the serializer is added to that fork.
Returns:	`type`	Returns the `JsonSerializable` class or its fork (to allow you to stack).
Example:	>>> class BaseModel(JsonSerializable ... .set_deserializer(lambda obj, cls, **_: obj.upper(), str)): ... pass >>> @dataclass ... class Person(BaseModel): ... name: str >>> Person.from_json({'name': 'Arnold'}) {'name': 'ARNOLD'}

Verbosity¶

An enum that defines the level of verbosity of a serialized object. You can provide an instance of this enum to the dump function.

Example:

@dataclass
class Car:
    color: str
    owner: str


c = Car('red', 'me')

Dump it as follows:

dumped = jsons.dump(c, verbose=Verbosity.WITH_EVERYTHING)

# You can also combine Verbosity instances as follows:
# WITH_CLASS_INFO | WITH_DUMP_TIME

Or the equivalent to WITH_EVERYTHING:

dumped = jsons.dump(c, verbose=True)

This would result in the following value for dumped:

{
  'color': 'red',
  'owner': 'me',
  '-meta': {
    'classes': {
      '/': '__main__.Car'
    },
    'dump_time': '2019-03-15T19:59:37Z'
  }
}

And with this, you can deserialize dumped without having to specify its class:

jsons.load(dumped)

# Instead of: jsons.load(dumped, cls=Car)

The following are members of Verbosity:

Attribute	value	Description
WITH_NOTHING	`0`	No meta data is outputted at all.
WITH_CLASS_INFO	`10`	Just the types of the classes are outputted.
WITH_DUMP_TIME	`20`	The date/time of dumping is outputted
WITH_EVERYTHING	`30`	All meta data is outputted.

from_value¶

Method:	@staticmethod `Verbosity.from_value`
Description:	Get a `Verbosity` instance from a value.
Arguments:	`value: any`	The name of the new fork (accessable with `__name__`).
Returns:	`Verbosity`	A new `type` based on `JsonSerializable`.
Example:	>>> Verbosity.from_value(True) Verbosity.WITH_EVERYTHING >>> Verbosity.from_value(None) Verbosity.WITH_NOTHING

Decorators¶

loaded¶

Decorator:	`jsons.decorators.loaded`
Description:	Call `jsons.load` on all parameters and on the return value of the decorated function/method.
Arguments:	`parameters: bool`	When `True`, parameters will be ‘loaded’.
	`returnvalue: bool`	When `True`, the return value is ‘loaded’ before it is actually returned.
	`fork_inst: JsonSerializable`	If given, this fork of `JsonSerializable` is used to call `load` on.
	`loader: callable`	The load function which must be one of (`load`, `loads`, `loadb`).
	`kwargs`	any keyword arguments that should be passed on to `jsons.load`
Example:	>>> @loaded() ... def func(arg: datetime) -> datetime: ... # arg is now of type datetime. ... return '2018-10-04T21:57:00Z' >>> res = func('2018-10-04T21:57:00Z') >>> type(res).__name__ 'datetime'

dumped¶

Decorator:	`jsons.decorators.dumped`
Description:	Call `jsons.dump` on all parameters and on the return value of the decorated function/method.
Arguments:	`parameters: bool`	When `True`, parameters will be ‘dumped’.
	`returnvalue: bool`	When `True`, the return value is ‘dumped’ before it is actually returned.
	`fork_inst: JsonSerializable`	If given, this fork of `JsonSerializable` is used to call `dump` on.
	`dumper: callable`	The dump function which must be one of (`dump`, `dumps` , `dumpb`).
	`kwargs`	any keyword arguments that should be passed on to `jsons.dump`
Example:	>>> @dumped() ... def func(arg): ... # arg is now of type str ... return datetime.now() >>> res = func(datetime.now()) >>> type(res).__name__ 'str'

Serializers¶

default_datetime_serializer¶

Function:	`jsons.default_datetime_serializer`
Description:	Serialize the given datetime instance to a string. It uses the RFC3339 pattern. If the datetime is a local time, an offset is provided. If datetime is in UTC, the result is suffixed with a ‘Z’.
Arguments:	`obj: datetime`	The datetime instance that is to be serialized.
	`*`
	`strip_microseconds: Optional[bool]`	Determines whether microseconds should be discarded.
	`kwargs`	Not used.
Returns:	`datetime`	`datetime` as an RFC3339 string.
Example:	>>> dt = datetime.now(tz=timezone.utc) >>> default_datetime_serializer(dt) '2019-02-28T20:37:42Z'

default_iterable_serializer¶

Function:	`jsons.default_iterable_serializer`
Description:	Serialize the given `obj` to a list of serialized objects.
Arguments:	`obj: Iterable`	The iterable that is to be serialized.
Arguments:	`kwargs`	Any keyword arguments that are passed through the serialization process.
Returns:	`list`	A list of which all elements are serialized.
Example:	>>> default_iterable_serializer((1, 2, 3)) [1, 2, 3]

default_tuple_serializer¶

Function:*	`jsons.default_tuple_serializer`
Description:	Serialize the given `obj` to a list of serialized objects. If `obj` happens to be a namedtuple, then `default_namedtuple_serializer` is called.
Arguments:	`obj: tuple`	The tuple that is to be serialized.
Arguments:	`kwargs`	Any keyword arguments that are passed through the serialization process.
Returns:	`list`	A list of which all elements are serialized.
Example:	>>> default_tuple_serializer((1, 2, datetime.now(tz=timezone.utc))) [1, 2, '2019-02-19T18:41:47Z']

default_namedtuple_serializer¶

Function:*	`jsons.default_namedtuple_serializer`
Description:	Serialize the given `obj` to a dict of serialized objects.
Arguments:	`obj: tuple`	The tuple that is to be serialized.
Arguments:	`kwargs`	Any keyword arguments that are passed through the serialization process.
Returns:	`dict`	A dict of which all elements are serialized.
Example:	>>> Point = namedtuple('Point', ['x', 'y']) >>> default_namedtuple_serializer(Point(10, 20)) {'x': 10, 'y': 20}

default_dict_serializer¶

Function:	`jsons.default_dict_serializer`
Description:	Serialize the given `obj` to a dict of serialized objects.
Arguments:	`obj: dict`	The object that is to be serialized.
	`cls: Optional[type]`	The type of `obj`. `obj` is dumped as if of that type.
	`*`
	`strict: bool`	if `True` the serialization will raise upon any the failure of any attribute. Otherwise it continues with a warning.
	`strip_nulls: bool`	When `True`, the resulting dict won’t contain ‘null values’.
	`key_transformer: Optional[Callable[[str], str]]`	A function that will be applied to all keys in the resulting dict.
	`kwargs`	Any keyword arguments that are passed through the serialization process.
Returns:	`dict`	A dict of which all elements are serialized.
Example:	>>> default_dict_serializer({'x': datetime.now()}) {'x': '2019-02-23T13:46:10.650772+01:00'}

default_enum_serializer¶

Function:	`jsons.default_enum_serializer`
Description:	Serialize the given `obj` to a string. By default, the name of the enum element is returned.
Arguments:	`obj: EnumMeta`	The object that is to be serialized.
	`*`
	`use_enum_name: bool`	When `True`, the name of the enum type is used, otherwise the value is used.
	`key_transformer: Optional[Callable[[str], str]]`	A function that will be applied to all keys in the resulting dict.
Returns:	`str`	A serialized `obj` in string format.
Example:	>>> class Color(Enum): ... RED = 1 ... BLUE = 2 >>> jsons.default_enum_serializer(Color.RED) 'RED'

default_primitive_serializer¶

Function:	`jsons.default_primitive_serializer`
Description:	Serialize the given primitive. This function is just a placeholder; it simply returns its parameter.
Arguments:	`obj: object`	The primitive object.
Returns:	`object`	`obj`.
Example:	>>> jsons.default_primitive_serializer(42) 42

default_object_serializer¶

Function:	`jsons.default_object_serializer`
Description:	Serialize the given `obj` to a dict. All values within `obj` are serialized as well.
Arguments:	`obj: object`	The object that is to be serialized.
	`*`
	`key_transformer: Optional[Callable[[str], str]]`	A function that will be applied to all keys in the resulting dict.
	`strip_nulls: bool`	If `True` the resulting dict will not contain null values.
	`strip_privates: bool`	If `True` the resulting dict will not contain private attributes (i.e. attributes that start with an underscore).
	`strip_properties: bool`	If `True` the resulting dict will not contain values from @properties.
	`strip_class_variables: bool`	If `True` the resulting dict will not contain attributes that belong to the class of `obj`.
	``strip_attr: Union[str, MutableSequence[str], Tuple[str]]``	If given, the attribute(s) with the given name(s) will be omitted from the resulting dict.
	`verbose: Union[Verbosity, bool]`	When set, the output will contain meta data (e.g. data on the types).
	`kwargs`	Any keyword arguments that may be given to the serialization process.
Returns:	`object`	`obj`.
Example:	>>> class Person: ... def __init__(self, name: str, friends: Optional[List['Person']] = None): ... self.name = name ... self.friends = friends >>> p = Person('Harry', [Person('John')]) >>> jsons.default_object_serializer(p) {'friends': [{'friends': None, 'name': 'John'}], 'name': 'Harry'}

Deserializers¶

default_datetime_deserializer¶

Function:	`jsons.default_datetime_deserializer`
Description:	Deserialize a string with an RFC3339 pattern to a datetime instance.
Arguments:	`obj: str`	The object that is to be serialized.
	`cls: type`	Not used.
	`kwargs`	Not used.
Returns:	`object`	`datetime`.
Example:	>>> jsons.default_datetime_deserializer('2019-02-23T22:28:00Z') datetime.datetime(2019, 2, 23, 22, 28, tzinfo=datetime.timezone.utc)

default_list_deserializer¶

Function:	`jsons.default_list_deserializer`
Description:	Deserialize a list by deserializing all items of that list.
Arguments:	`obj: list`	The list that needs deserializing.
	`cls: type`	Not used.
	`kwargs`	Not used.
Returns:	`list`	A deserialized list instance.
Example:	>>> jsons.default_list_deserializer(['2019-02-23T22:28:00Z']) [datetime.datetime(2019, 2, 23, 22, 28, tzinfo=datetime.timezone.utc)]

default_tuple_deserializer¶

Function:	`jsons.default_tuple_deserializer`
Description:	Deserialize a (JSON) list into a tuple by deserializing all items of that list.
Arguments:	`obj: list`	The tuple that needs deserializing
	`cls: type`	The type, optionally with a generic (e.g. Tuple[str, int]).
	`kwargs`	Any keyword arguments that are passed through the deserialization process.
Returns:	`tuple`	A deserialized tuple instance.
Example:	>>> jsons.default_tuple_deserializer(('2019-02-23T22:28:00Z',), Tuple[datetime]) (datetime.datetime(2019, 2, 23, 22, 28, tzinfo=datetime.timezone.utc),)

default_namedtuple_deserializer¶

Function:	`jsons.default_namedtuple_deserializer`
Description:	Deserialize a (JSON) dict or list into a named tuple by deserializing all items of that list/dict. This deserializer is called by the `default_tuple_deserializer` when it notices that a named tuple (rather than a tuple) is involved.
Arguments:	`obj: Union[list, dict]`	The tuple that needs deserializing.
	`cls: type`	The NamedTuple class.
	`kwargs`	Any keyword arguments that are passed through the deserialization process.
Returns:	`datetime`	A deserialized named tuple (i.e. an instance of a class).
Example:	>>> class NT(NamedTuple): ... a: int ... b: str = 'I am default' >>> jsons.load({'a': 42}, NT) NT(a=42, b='I am default')

default_union_deserializer¶

Function:	`jsons.default_union_deserializer`
Description:	Deserialize an object to any matching type of the given union. The first successful deserialization is returned.
Arguments:	`obj: object`	The object that needs deserializing.
	`cls: Union`	The Union type with a generic (e.g. Union[str, int]).
	`kwargs`	Any keyword arguments that are passed through the deserialization process.
Returns:	`object`	An object of the first type of the Union that could be deserialized successfully.
Example:	>>> jsons.default_union_deserializer('2019-02-23T22:28:00Z', Union[List[datetime], datetime]) datetime.datetime(2019, 2, 23, 22, 28, tzinfo=datetime.timezone.utc)

default_iterable_deserializer¶

Function:	`jsons.default_iterable_deserializer`
Description:	Deserialize a (JSON) list into an `Iterable` by deserializing all items of that list. The given obj is assumed to be homogeneous; if the list has a generic type (e.g. Set[datetime]) then it is assumed that all elements can be deserialized to that type.
Arguments:	`obj: list`	The list that needs deserializing to an `Iterable`.
	`cls: type`	The type, optionally with a generic (e.g. `Deque[str]`).
	`kwargs`	Any keyword arguments that are passed through the deserialization process.
Returns:	`Iterable`	A deserialized `Iterable` (e.g. `set`) instance.
Example:	>>> default_iterable_deserializer([1, 2, 3], deque) deque([1, 2, 3])

default_dict_deserializer¶

Function:	`jsons.default_dict_deserializer`
Description:	Deserialize a (JSON) object (a dict) and all its content to a Python dict.
Arguments:	`obj: dict`	The dict that needs to be deserialized.
	`cls: type`	The type of the dict, optionally with a generic type (e.g. Dict[str, datetime]).
	`*`
	key_transformer: Optional[Callable[[str], str]]	A function that transforms the keys to a different style (e.g. PascalCase).
	`kwargs`	Any keyword arguments that are passed through the deserialization process.
Returns:	`dict`	A deserialized dict instance.
Example:	>>> jsons.default_dict_deserializer({'a': '2019-02-24T17:43:00Z'}, Dict[str, datetime]) {'a': datetime.datetime(2019, 2, 24, 17, 43, tzinfo=datetime.timezone.utc)}

default_mapping_deserializer¶

Function:	`jsons.default_mapping_deserializer`
Description:	Deserialize a (JSON) object (a dict) and all its content to a `Mapping` (e.g. `OrderedDict`).
Arguments:	`obj: dict`	The dict that needs to be deserialized.
	`cls: type`	The type of the `Mapping` (e.g. `OrderedDict`).
	`kwargs`	Any keyword arguments that are passed through the deserialization process.
Returns:	`Mapping`	A deserialized `Mapping` instance.
Example:	>>> default_mapping_deserializer({'a': 'A', 'b': 'B'}, OrderedDict) OrderedDict([('a', 'A'), ('b', 'B')])

default_enum_deserializer¶

Function:	`jsons.default_enum_deserializer`
Description:	Deserialize an enum value to an enum instance. The serialized value can be either the name or the key of an enum entry. If `use_enum_name` is set to `True`, then the value must be the key of the enum entry. If `use_enum_name` is set to `False`, the value must be the value of the enum entry. By default, this deserializer tries both.
Arguments:	`obj: str`	The serialized enum.
	`cls: EnumMeta`	The enum class.
	`*`
	use_enum_name: bool	Determines whether the name (`True`) or the value (`False`) of an enum element should be used.
	`kwargs`	Not used.
Returns:	`dict`	The corresponding enum element instance.
Example:	>>> class Color(Enum): ... RED = 1 ... BLUE = 2 >>> jsons.default_enum_deserializer('RED', cls=Color) Color.RED

default_string_deserializer¶

Function:	`jsons.default_string_deserializer`
Description:	Deserialize a string. If the given `obj` can be parsed to a date, a``datetime`` instance is returned.
Arguments:	`obj: str`	The string that is be deserialized.
	`cls: Optional[type]`	Not used.
	`kwargs`	Any keyword arguments that may be passed on to other deserializers.
Returns:	`object`	The deserialized string.
Example:	>>> jsons.default_string_deserializer('2019-02-24T21:33:00Z') 2019-02-24 21:33:00+00:00

default_nonetype_deserializer¶

Function:	`jsons.default_nonetype_deserializer`
Description:	Deserialize the given `None`. This function is just a placeholder; it simply returns its parameter.
Arguments:	`obj: object`	The `None` object.
	`cls: Optional[type]`	Not used.
	`kwargs`	Not used.
Returns:	`object`	`obj`.
Example:	>>> jsons.default_nonetype_deserializer(None) None

default_primitive_deserializer¶

Function:	`jsons.default_primitive_deserializer`
Description:	Deserialize the given primitive. This function is just a placeholder; it simply returns its parameter.
Arguments:	`obj: object`	The primitive object.
	`cls: Optional[type]`	Not used.
	`kwargs`	Not used.
Returns:	`object`	`obj`.
Example:	>>> jsons.default_primitive_deserializer(42) 42

default_object_deserializer¶

Function:	`jsons.default_object_deserializer`
Description:	Deserialize `obj` into an instance of type `cls`. If `obj` contains keys with a certain case style (e.g. camelCase) that do not match the style of `cls` (e.g. snake_case), a key_transformer should be used (e.g.KEY_TRANSFORMER_SNAKECASE).
Arguments:	`obj: dict`	The object that is be deserialized.
	`cls: type`	The type to which `obj` should be deserialized.
	`*`
	`key_transformer: Optional[Callable[[str], str]]`	A function that transforms the keys in order to match the attribute names of `cls`.
	`strict: bool`	When `True` deserializes in strict mode.
	`kwargs`	Any keyword arguments that may be passed to the deserializers.
Returns:	`object`	An instance of type `cls`.
Example:	>>> class Person: ... def __init__(self, name: str, friends: Optional[List['Person']] = None): ... self.name = name ... self.friends = friends >>> json_obj = {'friends': [{'friends': None, 'name': 'John'}], 'name': 'Harry'} >>> jsons.default_object_deserializer(json_obj, Person) <__main__.Person object at 0x02F84390>

Features¶

Installing and using¶

FAQ¶

Frequently Asked Questions¶

Do I need to use dataclasses?¶

Do I need to use type hints?¶

How can I improve the performance of jsons?¶

Is it possible to discard private attributes?¶

How can I write a custom serializer?¶

How can I write a custom deserializer?¶

Why does jsons tolerate additional attributes in my json object compared to the class?¶

How can I deserialize without exactly knowing the target class?¶

Why not just use __dict__?¶

Why not use the standard json library?¶

Aren’t there already libraries for serialization to json?¶

My json contains camelcase, how can I transform to the right case?¶

How do the jsons decorators work?¶

Can I just participate in discussions on the issues?¶

I have an idea for a new feature, what should I do?¶

I found a bug, what should I do?¶

My question is not listed here!¶

API¶

API¶

Main functions¶

dump¶

load¶

dumps¶

loads¶

dumpb¶

loadb¶

fork¶

set_serializer¶

get_serializer¶

set_deserializer¶

get_deserializer¶

suppress_warnings¶

set_validator¶

get_validator¶

Classes¶

JsonSerializable¶

fork¶

with_dump¶

json¶

dump¶

dumps¶

dumpb¶

from_json¶

load¶

loads¶

loadb¶

set_serializer¶

set_deserializer¶

Verbosity¶

from_value¶

Decorators¶

loaded¶

dumped¶

Serializers¶

default_datetime_serializer¶

default_iterable_serializer¶

default_tuple_serializer¶

default_namedtuple_serializer¶

default_dict_serializer¶

default_enum_serializer¶

default_primitive_serializer¶

default_object_serializer¶

Deserializers¶

default_datetime_deserializer¶

default_list_deserializer¶

default_tuple_deserializer¶

default_namedtuple_deserializer¶

default_union_deserializer¶

default_iterable_deserializer¶

default_dict_deserializer¶

default_mapping_deserializer¶

default_enum_deserializer¶

default_string_deserializer¶

default_nonetype_deserializer¶

default_primitive_deserializer¶

default_object_deserializer¶

Why not just use `dict`?¶

Why not use the standard `json` library?¶