marshmallow-dataclass

8.7.1 · active · verified Thu Apr 09

marshmallow-dataclass is a Python library that enables the seamless conversion of standard Python dataclasses into Marshmallow schemas. This simplifies data serialization, deserialization, and validation by automatically generating schemas based on dataclass definitions. As of version 8.7.1, it provides robust type hint support and integrates well with existing Marshmallow workflows. Releases are generally driven by new features, bug fixes, or compatibility updates with Marshmallow.

Warnings

breaking Version 8.0.0 removed `union_field` and moved `dataclass_json`. It also bumped the minimum Python version requirement to 3.8+.
Fix: Use `marshmallow.fields.Union` directly instead of `union_field`. Import `dataclass_json` from `marshmallow_dataclass.decorators` if you still need it (though it's generally discouraged in favor of `class_schema`). Ensure your environment uses Python 3.8 or newer.
breaking Version 6.0.0 changed the signature of the `class_schema` function and discouraged the older `NewType` pattern for schema generation.
Fix: Always pass the dataclass directly to `class_schema(MyDataclass)` instead of `NewType('MySchema', MyDataclass)`. Review specific changes to `class_schema` parameters if you were using advanced configurations.
gotcha Marshmallow `post_load` and `pre_load` methods must be defined on the *generated Marshmallow Schema*, not directly within the dataclass.
Fix: Define `post_load` or `pre_load` methods as part of the `UserSchema` class (if you're inheriting and extending it) or by dynamically adding them after schema generation if needed. Do not try to add these directly to your `dataclass` definition.
gotcha Dataclass `Optional` types (`Optional[str]`) automatically map to Marshmallow fields with `allow_none=True`. If `None` is not desired for an optional field, you must explicitly set `allow_none=False` via metadata.
Fix: For an optional field that should *not* allow `None` during deserialization (e.g., if it must be missing or a valid value, but not `None`), explicitly set `field(metadata={'allow_none': False})`.

Install

pip install marshmallow-dataclass Install stable version

Imports

class_schema

from marshmallow_dataclass import class_schema

dataclass_json
```
from marshmallow_dataclass.decorators import dataclass_json
```
The `dataclass_json` decorator was moved from the root module to `marshmallow_dataclass.decorators` in v8.0.0.

Quickstart

This quickstart demonstrates how to define a dataclass, generate a Marshmallow schema using `class_schema`, and then use the generated schema to load (deserialize) data into a dataclass instance and dump (serialize) a dataclass instance back to a dictionary. It also shows how to use Marshmallow metadata fields like `required`, `load_only`, and `dump_only` within the dataclass `field` definition.

from dataclasses import dataclass, field
from datetime import datetime
from marshmallow_dataclass import class_schema

@dataclass
class User:
    id: int = field(metadata={'required': True})
    name: str
    email: str = field(metadata={'load_only': True})
    created_at: datetime = field(default_factory=datetime.now, metadata={'dump_only': True})

# Generate a Marshmallow schema from the dataclass
UserSchema = class_schema(User)

# Instantiate the schema
user_schema = UserSchema()

# Example data
user_data = {
    'id': 1,
    'name': 'Alice',
    'email': 'alice@example.com'
}

# Deserialize (load) data into a dataclass instance
try:
    user_obj = user_schema.load(user_data)
    print(f"Loaded User: {user_obj.name} (ID: {user_obj.id})")
    # 'email' is load_only, so not in user_obj after load by default if not passed in constructor
    print(f"User email (load_only): {user_data.get('email')}")
except Exception as e:
    print(f"Error loading data: {e}")

# Serialize (dump) a dataclass instance to a dictionary
dumped_data = user_schema.dump(user_obj)
print(f"Dumped data: {dumped_data}")
# 'email' is load_only, 'created_at' is dump_only
assert 'email' not in dumped_data
assert 'created_at' in dumped_data
assert dumped_data['id'] == 1

view raw JSON →