Dataclasses JSON

This library provides a simple API for encoding and decoding dataclasses to and from JSON.

It's very easy to get started.

README / Documentation website. Features a navigation bar and search functionality, and should mirror this README exactly -- take a look!

Quickstart

pip install dataclasses-json

from dataclasses import dataclass
from dataclasses_json import dataclass_json


@dataclass_json
@dataclass
class Person:
    name: str


person = Person(name='lidatong')
person.to_json()  # '{"name": "lidatong"}' <- this is a string
person.to_dict()  # {'name': 'lidatong'} <- this is a dict
Person.from_json('{"name": "lidatong"}')  # Person(1)
Person.from_dict({'name': 'lidatong'})  # Person(1)

# You can also apply _schema validation_ using an alternative API
# This can be useful for "typed" Python code

Person.from_json('{"name": 42}')  # This is ok. 42 is not a `str`, but
                                  # dataclass creation does not validate types
Person.schema().loads('{"name": 42}')  # Error! Raises `ValidationError`

What if you want to work with camelCase JSON?

# same imports as above, with the additional `LetterCase` import
from dataclasses import dataclass
from dataclasses_json import dataclass_json, LetterCase

@dataclass_json(letter_case=LetterCase.CAMEL)  # now all fields are encoded/decoded from camelCase
@dataclass
class ConfiguredSimpleExample:
    int_field: int

ConfiguredSimpleExample(1).to_json()  # {"intField": 1}
ConfiguredSimpleExample.from_json('{"intField": 1}')  # ConfiguredSimpleExample(1)

Supported types

It's recursive (see caveats below), so you can easily work with nested dataclasses. In addition to the supported types in the py to JSON table, this library supports the following:

any arbitrary Collection type is supported. Mapping types are encoded as JSON objects and str types as JSON strings. Any other Collection types are encoded into JSON arrays, but decoded into the original collection types.
datetime objects. datetime objects are encoded to float (JSON number) using timestamp. As specified in the datetime docs, if your datetime object is naive, it will assume your system local timezone when calling .timestamp(). JSON numbers corresponding to a datetime field in your dataclass are decoded into a datetime-aware object, with tzinfo set to your system local timezone. Thus, if you encode a datetime-naive object, you will decode into a datetime-aware object. This is important, because encoding and decoding won't strictly be inverses. See this section if you want to override this default behavior (for example, if you want to use ISO).
UUID objects. They are encoded as str (JSON string).
Decimal objects. They are also encoded as str.

The latest release is compatible with both Python 3.7 and Python 3.6 (with the dataclasses backport).

Usage

Approach 1: Class decorator

from dataclasses import dataclass
from dataclasses_json import dataclass_json

@dataclass_json
@dataclass
class Person:
    name: str

lidatong = Person('lidatong')

# Encoding to JSON
lidatong.to_json()  # '{"name": "lidatong"}'

# Decoding from JSON
Person.from_json('{"name": "lidatong"}')  # Person(name='lidatong')

Note that the @dataclass_json decorator must be stacked above the @dataclass decorator (order matters!)

Approach 2: Inherit from a mixin

from dataclasses import dataclass
from dataclasses_json import DataClassJsonMixin

@dataclass
class Person(DataClassJsonMixin):
    name: str

lidatong = Person('lidatong')

# A different example from Approach 1 above, but usage is the exact same
assert Person.from_json(lidatong.to_json()) == lidatong

Pick whichever approach suits your taste. Note that there is better support for the mixin approach when using static analysis tools (e.g. linting, typing), but the differences in implementation will be invisible in runtime usage.

How do I...

Use my dataclass with JSON arrays or objects?

from dataclasses import dataclass
from dataclasses_json import dataclass_json

@dataclass_json
@dataclass
class Person:
    name: str

Encode into a JSON array containing instances of my Data Class

people_json = [Person('lidatong')]
Person.schema().dumps(people_json, many=True)  # '[{"name": "lidatong"}]'

Decode a JSON array containing instances of my Data Class

people_json = '[{"name": "lidatong"}]'
Person.schema().loads(people_json, many=True)  # [Person(name='lidatong')]

Encode as part of a larger JSON object containing my Data Class (e.g. an HTTP request/response)

import json

response_dict = {
    'response': {
        'person': Person('lidatong').to_dict()
    }
}

response_json = json.dumps(response_dict)

In this case, we do two steps. First, we encode the dataclass into a python dictionary rather than a JSON string, using .to_dict.

Second, we leverage the built-in json.dumps to serialize our dataclass into a JSON string.

Decode as part of a larger JSON object containing my Data Class (e.g. an HTTP response)

import json

response_dict = json.loads('{"response": {"person": {"name": "lidatong"}}}')

person_dict = response_dict['response']

person = Person.from_dict(person_dict)

In a similar vein to encoding above, we leverage the built-in json module.

First, call json.loads to read the entire JSON object into a dictionary. We then access the key of the value containing the encoded dict of our Person that we want to decode (response_dict['response']).

Second, we load in the dictionary using Person.from_dict.

Encode or decode into Python lists/dictionaries rather than JSON?

This can be by calling .schema() and then using the corresponding encoder/decoder methods, ie. .load(...)/.dump(...).

Encode into a single Python dictionary

person = Person('lidatong')
person.to_dict()  # {'name': 'lidatong'}

Encode into a list of Python dictionaries

people = [Person('lidatong')]
Person.schema().dump(people, many=True)  # [{'name': 'lidatong'}]

Decode a dictionary into a single dataclass instance

person_dict = {'name': 'lidatong'}
Person.from_dict(person_dict)  # Person(name='lidatong')

Decode a list of dictionaries into a list of dataclass instances

people_dicts = [{"name": "lidatong"}]
Person.schema().load(people_dicts, many=True)  # [Person(name='lidatong')]

Encode or decode from camelCase (or kebab-case)?

JSON letter case by convention is camelCase, in Python members are by convention snake_case.

You can configure it to encode/decode from other casing schemes at both the class level and the field level.

from dataclasses import dataclass, field

from dataclasses_json import LetterCase, config, dataclass_json


# changing casing at the class level
@dataclass_json(letter_case=LetterCase.CAMEL)
@dataclass
class Person:
    given_name: str
    family_name: str
    
Person('Alice', 'Liddell').to_json()  # '{"givenName": "Alice"}'
Person.from_json('{"givenName": "Alice", "familyName": "Liddell"}')  # Person('Alice', 'Liddell')

# at the field level
@dataclass_json
@dataclass
class Person:
    given_name: str = field(metadata=config(letter_case=LetterCase.CAMEL))
    family_name: str
    
Person('Alice', 'Liddell').to_json()  # '{"givenName": "Alice"}'
# notice how the `family_name` field is still snake_case, because it wasn't configured above
Person.from_json('{"givenName": "Alice", "family_name": "Liddell"}')  # Person('Alice', 'Liddell')

This library assumes your field follows the Python convention of snake_case naming. If your field is not snake_case to begin with and you attempt to parameterize LetterCase, the behavior of encoding/decoding is undefined (most likely it will result in subtle bugs).

Encode or decode using a different name

from dataclasses import dataclass, field

from dataclasses_json import config, dataclass_json

@dataclass_json
@dataclass
class Person:
    given_name: str = field(metadata=config(field_name="overriddenGivenName"))

Person(given_name="Alice")  # Person('Alice')
Person.from_json('{"overriddenGivenName": "Alice"}')  # Person('Alice')
Person('Alice').to_json()  # {"overriddenGivenName": "Alice"}

Handle missing or optional field values when decoding?

By default, any fields in your dataclass that use default or default_factory will have the values filled with the provided default, if the corresponding field is missing from the JSON you're decoding.

Decode JSON with missing field

@dataclass_json
@dataclass
class Student:
    id: int
    name: str = 'student'

Student.from_json('{"id": 1}')  # Student(id=1, name='student')

Notice from_json filled the field name with the specified default 'student' when it was missing from the JSON.

Sometimes you have fields that are typed as Optional, but you don't necessarily want to assign a default. In that case, you can use the infer_missing kwarg to make from_json infer the missing field value as None.

**Decode

dataclasses-json

Description