manmime/marshmallow_dataclass

Automatic generation of marshmallow schemas from dataclasses.

marshmallow_dataclass

Automatic generation of marshmallow schemas from dataclasses.

Specifying a schema to which your data should conform is very useful, both for (de)serialization and for documentation. However, using schemas in python often means having both a class to represent your data and a class to represent its schema, which means duplicated code that could fall out of sync. With the new features of python 3.6, types can be defined for class members, and that allows libraries like this one to generate schemas automatically.

An use case would be to document APIs (with flasgger, for instance) in a way that allows you to statically check that the code matches the documentation.

How to use

You simply import marshmallow_dataclass.dataclass instead of dataclasses.dataclass. It adds a Schema property to the generated class, containing a marshmallow Schema class.

If you need to specify custom properties on your marshmallow fields (such as attribute, error, validate, required, dump_only, error_messages, description ...) you can add them using the metadata argument of the field function.

from dataclasses import field
from marshmallow_dataclass import dataclass # Importing from marshmallow_dataclass instead of dataclasses
import marshmallow.validate
from typing import List, Optional

@dataclass
class Building:
  # The field metadata is used to instantiate the marshmallow field
  height: float = field(metadata={'validate': marshmallow.validate.Range(min=0)})
  name: str = field(default="anonymous")


@dataclass
class City:
  name: Optional[str]
  buildings: List[Building] = field(default_factory=lambda: [])

# City.Schema contains a marshmallow schema class
city = City.Schema().load({
    "name": "Paris",
    "buildings": [
        {"name": "Eiffel Tower", "height":324}
    ]
})

# Serializing city as a json string
city_json = City.Schema().dumps(city)

The previous syntax is very convenient, as the only change you have to apply to your existing code is update the dataclass import.

However, as the .Schema property is added dynamically, it can confuse type checkers. If you want to avoid that, you can also use the standard dataclass decorator, and generate the schema manually using class_schema :

from dataclasses import dataclass
from datetime import datetime
import marshmallow_dataclass

@dataclass
class Person:
    name: str
    birth: datetime

PersonSchema = marshmallow_dataclass.class_schema(Person)

You can also declare the schema as a ClassVar:

from marshmallow_dataclass import dataclass
from marshmallow import Schema
from typing import ClassVar, Type

@dataclass
class Point:
  x:float
  y:float
  Schema: ClassVar[Type[Schema]] = Schema

Custom base Schema class

It is also possible to derive all schemas from your own base Schema class (see marshmallow's documentation about extending Schema). This allows you to implement custom (de)serialization behavior, for instance renaming fields:

import marshmallow
import marshmallow_dataclass

class BaseSchema(marshmallow.Schema):
    def on_bind_field(self, field_name, field_obj):
        field_obj.data_key = (field_obj.data_key or field_name).upper()


@marshmallow_dataclass.dataclass(base_schema=BaseSchema)
class Sample:
    my_text: str
    my_int: int

Sample.Schema().dump(Sample(my_text="warm words", my_int=1))
# -> {"MY_TEXT": "warm words", "MY_INT": 1}

Custom NewType declarations

This feature is currently only available in the latest pre-release, 6.1.0rc1. Please try it, and open an issue if you have some feedback to give about it.

This library exports a NewType function to create new python types with a custom (de)serialization logic.

All the additional keyword arguments to NewType are passed to the marshmallow field initializer:

import marshmallow.validate
from marshmallow_dataclass import NewType

IPv4 = NewType('IPv4', str, validate=marshmallow.validate.Regexp(r'^([0-9]{1,3}\\.){3}[0-9]{1,3}$'))

You can also set a predefined marshmallow field for your new type:

import marshmallow
from marshmallow_dataclass import NewType

Email = NewType('Email', str, field=marshmallow.fields.Email)

This feature allows you to implement a custom serialization and deserialization logic using custom marshmallow fields.

Using marshmallow's Meta

You can specify the Meta just as you would in a marshmallow Schema:

from marshmallow_dataclass import dataclass

@dataclass
class Point:
  x:float
  y:float
  class Meta:
    ordered = True

Installation

This package is hosted on pypi. You can install it with a simple :

pip3 install marshmallow-dataclass

This package also has the following optional features:

• enum, for translating python enums to marshmallow-enum.
• union, for translating python Union types into marshmallow-union fields.

You can install these features with:

pip3 install marshmallow-dataclass[enum,union]

For marshmallow 2

marshmallow-dataclass does not support the old marshmallow 2 anymore. You can install a version before 6.0 if you want marshmallow 2 support.

Documentation

The project documentation is hosted on github pages:

• documentation.

Usage warning

This library depends on python's standard typing library, which is provisional.