dataclass-wizard 0.10.1

Marshal dataclasses to/from JSON. Use field properties with initial values. Construct a dataclass schema with JSON input.

This library provides a set of simple, yet elegant wizarding tools for interacting with the Python dataclasses module.

Full documentation is at:

• https://dataclass-wizard.readthedocs.io

Features

Here are the supported features that dataclass-wizard currently provides:

• JSON (de)serialization: marshal dataclasses to/from JSON and Python dict objects.

• Field properties: support for using properties with default values in dataclass instances.

• JSON to Dataclass generation: construct a dataclass schema with a JSON file or string input.

Usage

Using the built-in JSON marshalling support for dataclasses:

from dataclasses import dataclass, field
from typing import Optional, List, Tuple

from dataclass_wizard import JSONWizard


@dataclass
class MyClass(JSONWizard):
    my_str: Optional[str]
    is_active_tuple: Tuple[bool, ...]
    list_of_int: List[int] = field(default_factory=list)


string = """
{
  "my_str": 20,
  "ListOfInt": ["1", "2", 3],
  "isActiveTuple": ["true", "false", 1, false]
}
"""

# De-serialize the JSON string into a `MyClass` object.
c = MyClass.from_json(string)

print(repr(c))
# prints:
#   MyClass(my_str='20', is_active_tuple=(True, False, True, False), list_of_int=[1, 2, 3])

print(c.to_json())
# prints:
#   {"myStr": "20", "isActiveTuple": [true, false, true, false], "listOfInt": [1, 2, 3]}

# True
assert c == c.from_dict(c.to_dict())

… and with the property_wizard, which provides support for field properties with default values in dataclasses:

from dataclasses import dataclass, field
from typing import Union
from typing_extensions import Annotated

from dataclass_wizard import property_wizard


@dataclass
class Vehicle(metaclass=property_wizard):
    # Note: The example below uses the default value from the `field` extra in
    # the `Annotated` definition; if `wheels` were annotated as a `Union` type,
    # it would default to 0, because `int` appears as the first type argument.
    #
    # Any right-hand value assigned to `wheels` is ignored as it is simply
    # re-declared by the property; here it is simply omitted for brevity.
    wheels: Annotated[Union[int, str], field(default=4)]

    # This is a shorthand version of the above; here an IDE suggests
    # `_wheels` as a keyword argument to the constructor method, though
    # it will actually be named as `wheels`.
    # _wheels: Union[int, str] = 4

    @property
    def wheels(self) -> int:
        return self._wheels

    @wheels.setter
    def wheels(self, wheels: Union[int, str]):
        self._wheels = int(wheels)


if __name__ == '__main__':
    v = Vehicle()
    print(v)
    # prints:
    #   Vehicle(wheels=4)

    v = Vehicle(wheels=3)
    print(v)

    v = Vehicle('6')
    print(v)

    assert v.wheels == 6, 'The constructor should use our setter method'

    # Confirm that we go through our setter method
    v.wheels = '123'
    assert v.wheels == 123

… or generate a dataclass schema for JSON input, via the wiz-cli tool:

$ echo '{"myFloat": "1.23", "created_at": "2021-11-17"}' | wiz gs - my_file

# Contents of my_file.py
from dataclasses import dataclass
from datetime import date
from typing import Union

from dataclass_wizard import JSONWizard


@dataclass
class Data(JSONWizard):
    """
    Data dataclass

    """
    my_float: Union[float, str]
    created_at: date

Installing Dataclass Wizard and Supported Versions

The Dataclass Wizard library is available on PyPI:

$ python -m pip install dataclass-wizard

The dataclass-wizard library officially supports Python 3.6 or higher.

JSON Marshalling

JSONSerializable (aliased to JSONWizard) is a Mixin class which provides the following helper methods that are useful for serializing (and loading) a dataclass instance to/from JSON, as defined by the AbstractJSONWizard interface.

Method	Example	Description
from_json	item = Product.from_json(string)	Converts a JSON string to an instance of the dataclass, or a list of the dataclass instances.
from_list	list_of_item = Product.from_list(l)	Converts a Python list object to a list of the dataclass instances.
from_dict	item = Product.from_dict(d)	Converts a Python dict object to an instance of the dataclass.
to_dict	d = item.to_dict()	Converts the dataclass instance to a Python dict object that is JSON serializable.
to_json	string = item.to_json()	Converts the dataclass instance to a JSON string representation.

Additionally, it adds a default __str__ method to subclasses, which will pretty print the JSON representation of an object; this is quite useful for debugging purposes. Whenever you invoke print(obj) or str(obj), for example, it’ll call this method which will format the dataclass object as a prettified JSON string. If you prefer a __str__ method to not be added, you can pass in str=False when extending from the Mixin class as mentioned here.

Note that the __repr__ method, which is implemented by the dataclass decorator, is also available. To invoke the Python object representation of the dataclass instance, you can instead use repr(obj) or f'{obj!r}'.

To mark a dataclass as being JSON serializable (and de-serializable), simply sub-class from JSONSerializable as shown below. You can also extend from the aliased name JSONWizard, if you prefer to use that instead.

Check out a more complete example of using the JSONSerializable Mixin class.

Custom Key Mappings

If you ever find the need to add a custom mapping of a JSON key to a dataclass field (or vice versa), the helper function json_field - which can be considered an alias to dataclasses.field() – is one approach that can resolve this.

Example below:

from dataclasses import dataclass

from dataclass_wizard import JSONSerializable, json_field


@dataclass
class MyClass(JSONSerializable):

    my_str: str = json_field('myString1', all=True)


# De-serialize a dictionary object with the newly mapped JSON key.
d = {'myString1': 'Testing'}
c = MyClass.from_dict(d)

print(repr(c))
# prints:
#   MyClass(my_str='Testing')

# Assert we get the same dictionary object when serializing the instance.
assert c.to_dict() == d

Extending from Meta

Need to change how date and datetime objects are serialized to JSON? Or prefer that field names appear in snake case when a dataclass instance is serialized?

The inner Meta class allows easy configuration of such settings, as shown below; and as a nice bonus, IDEs should be able to assist with code completion along the way.

from dataclasses import dataclass
from datetime import date

from dataclass_wizard import JSONWizard
from dataclass_wizard.enums import DateTimeTo


@dataclass
class MyClass(JSONWizard):

    class _(JSONWizard.Meta):
        marshal_date_time_as = DateTimeTo.TIMESTAMP
        key_transform_with_dump = 'SNAKE'

    my_str: str
    my_date: date


data = {'my_str': 'test', 'myDATE': '2010-12-30'}

c = MyClass.from_dict(data)

print(repr(c))
# prints:
#   MyClass(my_str='test', my_date=datetime.date(2010, 12, 30))

string = c.to_json()
print(string)
# prints:
#   {"my_str": "test", "my_date": 1293685200}

Field Properties

The Python dataclasses library has some key limitations with how it currently handles properties and default values.

The dataclass-wizard package natively provides support for using field properties with default values in dataclasses. The main use case here is to assign an initial value to the field property, if one is not explicitly passed in via the constructor method.

To use it, simply import the property_wizard helper function, and add it as a metaclass on any dataclass where you would benefit from using field properties with default values. The metaclass also pairs well with the JSONSerializable mixin class.

For more examples and important how-to’s on properties with default values, refer to the Using Field Properties section in the documentation.

Credits

This package was created with Cookiecutter and the rnag/cookiecutter-pypackage project template.