Python library to convert dataclasses into marshmallow schemas.
Project description
marshmallow-dataclass
Automatic generation of marshmallow schemas from dataclasses.
from dataclasses import dataclass, field from typing import List, Optional import marshmallow_dataclass import marshmallow.validate @dataclass class Building: # 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=list) city_schema = marshmallow_dataclass.class_schema(City)() city = city_schema.load( {"name": "Paris", "buildings": [{"name": "Eiffel Tower", "height": 324}]} ) # => City(name='Paris', buildings=[Building(height=324.0, name='Eiffel Tower')]) city_dict = city_schema.dump(city) # => {'name': 'Paris', 'buildings': [{'name': 'Eiffel Tower', 'height': 324.0}]}
Why
Using schemas in Python often means having both a class to represent your data and a class to represent its schema, which results in duplicated code that could fall out of sync. As of Python 3.6, types can be defined for class members, which allows libraries to generate schemas automatically.
Therefore, you can document your APIs in a way that allows you to statically check that the code matches the documentation.
Installation
This package is hosted on PyPI.
pip3 install marshmallow-dataclass
You may optionally install the following extras:
enum
: for translating python enums to marshmallow-enum.union
: for translating pythonUnion
types to union fields.
pip3 install "marshmallow-dataclass[enum,union]"
marshmallow 2 support
marshmallow-dataclass
no longer supports marshmallow 2.
Install marshmallow_dataclass<6.0
if you need marshmallow 2 compatibility.
Usage
Use the class_schema
function to generate a marshmallow Schema
class from a dataclass
.
from dataclasses import dataclass from datetime import date import marshmallow_dataclass @dataclass class Person: name: str birth: date PersonSchema = marshmallow_dataclass.class_schema(Person)
The type of your fields must be either basic
types supported by marshmallow
(such as float
, str
, bytes
, datetime
, ...), or other dataclasses.
Customizing generated fields
To pass arguments to the generated marshmallow fields (e.g., validate
, load_only
, dump_only
, etc.),
pass them to the metadata
argument of the
field
function.
from dataclasses import dataclass, field import marshmallow_dataclass import marshmallow.validate @dataclass class Person: name: str = field(metadata=dict(load_only=True)) height: float = field(metadata=dict(validate=marshmallow.validate.Range(min=0))) PersonSchema = marshmallow_dataclass.class_schema(Person)
@dataclass
shortcut
marshmallow_dataclass
provides a @dataclass
decorator that behaves like the standard library's
@dataclasses.dataclass
and adds a Schema
attribute with the generated marshmallow
Schema.
# Use marshmallow_dataclass's @dataclass shortcut from marshmallow_dataclass import dataclass @dataclass class Point: x: float y: float Point.Schema().dump(Point(4, 2)) # => {'x': 4, 'y': 2}
Note: Since the .Schema
property is added dynamically, it can confuse type checkers.
To avoid that, you can declare Schema
as a ClassVar
.
from typing import ClassVar, Type from marshmallow_dataclass import dataclass from marshmallow import Schema @dataclass class Point: x: float y: float Schema: ClassVar[Type[Schema]] = Schema
Customizing the base Schema
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 specifying a custom mapping between your classes and marshmallow fields,
or renaming fields on serialization.
Custom mapping between classes and fields
class BaseSchema(marshmallow.Schema): TYPE_MAPPING = {CustomType: CustomField, List: CustomListField} class Sample: my_custom: CustomType my_custom_list: List[int] SampleSchema = marshmallow_dataclass.class_schema(Sample, base_schema=BaseSchema) # SampleSchema now serializes my_custom using the CustomField marshmallow field # and serializes my_custom_list using the CustomListField marshmallow field
Renaming fields on serialization
import marshmallow import marshmallow_dataclass class UppercaseSchema(marshmallow.Schema): """A Schema that marshals data with uppercased keys.""" def on_bind_field(self, field_name, field_obj): field_obj.data_key = (field_obj.data_key or field_name).upper() class Sample: my_text: str my_int: int SampleSchema = marshmallow_dataclass.class_schema(Sample, base_schema=UppercaseSchema) SampleSchema().dump(Sample(my_text="warm words", my_int=1)) # -> {"MY_TEXT": "warm words", "MY_INT": 1}
You can also pass base_schema
to marshmallow_dataclass.dataclass
.
@marshmallow_dataclass.dataclass(base_schema=UppercaseSchema) class Sample: my_text: str my_int: int
See marshmallow's documentation about extending Schema
.
Custom NewType declarations
This library exports a NewType
function to create types that generate customized marshmallow fields.
Keyword arguments to NewType
are passed to the marshmallow field constructor.
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 pass a marshmallow field to NewType
.
import marshmallow from marshmallow_dataclass import NewType Email = NewType("Email", str, field=marshmallow.fields.Email)
For convenience, some custom types are provided:
from marshmallow_dataclass.typing import Email, Url
Note: if you are using mypy
, you will notice that mypy
throws an error if a variable defined with
NewType
is used in a type annotation. To resolve this, add the marshmallow_dataclass.mypy
plugin
to your mypy
configuration, e.g.:
[mypy] plugins = marshmallow_dataclass.mypy # ...
Meta
options
Meta
options are set the same way as a marshmallow Schema
.
from marshmallow_dataclass import dataclass @dataclass class Point: x: float y: float class Meta: ordered = True
Documentation
The project documentation is hosted on GitHub Pages: https://lovasoa.github.io/marshmallow_dataclass/
Usage warning
This library depends on python's standard typing library, which is provisional.
Contributing
To install this project and make changes to it locally, follow the instructions in CONTRIBUTING.md
.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Filename, size | File type | Python version | Upload date | Hashes |
---|---|---|---|---|
Filename, size marshmallow_dataclass-8.3.1-py3-none-any.whl (13.9 kB) | File type Wheel | Python version py3 | Upload date | Hashes View |
Filename, size marshmallow_dataclass-8.3.1.tar.gz (16.2 kB) | File type Source | Python version None | Upload date | Hashes View |
Hashes for marshmallow_dataclass-8.3.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4d07a0829882c99343d0be216e808d6075b2d6cd94211c9f345df9aaed7d4b20 |
|
MD5 | f5cf9a919a2c9d128c2f9bef323d3b7a |
|
BLAKE2-256 | 917edb1cfb1b78fd58f63ba887ff9c515d0f21c1f68db37d5469fca94413be95 |
Hashes for marshmallow_dataclass-8.3.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 835e6aef758f9b107ab9623d37e0ebbd6e586fb8f4172281a47dd90a69ceda38 |
|
MD5 | f574c4bf26789a6caba9a3e7bf9031e7 |
|
BLAKE2-256 | 8fb6c5a7a69ce645fed30034259ff4a0df463527314b94f57399f57329bf7b69 |