0
# Marshmallow
1

2
An ORM/ODM/framework-agnostic Python library for converting complex datatypes to and from native Python datatypes. Marshmallow provides object serialization and deserialization with comprehensive schema definition, validation, and data transformation capabilities.
3

4
## Package Information
5

6
- **Package Name**: marshmallow
7
- **Language**: Python
8
- **Installation**: `pip install marshmallow`
9

10
## Core Imports
11

12
```python
13
import marshmallow
14
from marshmallow import Schema, fields, ValidationError
15
```
16

17
Common pattern for schema definition:
18

19
```python
20
from marshmallow import Schema, fields
21
from marshmallow import validate
22
```
23

24
## Basic Usage
25

26
```python
27
from datetime import date
28
from marshmallow import Schema, fields
29

30
class ArtistSchema(Schema):
31
    name = fields.Str()
32

33
class AlbumSchema(Schema):
34
    title = fields.Str()
35
    release_date = fields.Date()
36
    artist = fields.Nested(ArtistSchema())
37

38
# Create schema instance
39
schema = AlbumSchema()
40

41
# Serialize (dump) Python objects to JSON-compatible data
42
album = {
43
    "artist": {"name": "David Bowie"}, 
44
    "title": "Hunky Dory", 
45
    "release_date": date(1971, 12, 17)
46
}
47
result = schema.dump(album)
48
# {"artist": {"name": "David Bowie"}, "title": "Hunky Dory", "release_date": "1971-12-17"}
49

50
# Deserialize (load) JSON-compatible data to Python objects
51
json_data = {"artist": {"name": "Pink Floyd"}, "title": "Dark Side of the Moon", "release_date": "1973-03-01"}
52
result = schema.load(json_data)
53

54
# Validate data without loading
55
errors = schema.validate({"title": "Invalid Album"})  # Missing required fields
56
```
57

58
## Architecture
59

60
Marshmallow's design centers around **Schemas** and **Fields**:
61

62
- **Schema**: Defines the structure and rules for serialization/deserialization of complex objects
63
- **Fields**: Handle conversion and validation of individual data elements
64
- **Validation**: Comprehensive validation framework with built-in and custom validators
65
- **Processing Hooks**: Decorators for custom data transformation before/after serialization
66
- **Error Handling**: Structured validation errors with detailed field-level messages
67

68
This architecture enables flexible data transformation pipelines suitable for web APIs, data persistence, configuration management, and integration with frameworks like Flask, Django, and FastAPI.
69

70
## Capabilities
71

72
### Schema Definition and Management
73

74
Core schema functionality for defining object serialization/deserialization rules, including schema configuration, field management, and data processing methods.
75

76
```python { .api }
77
class Schema:
78
    def dump(self, obj, many=None): ...
79
    def dumps(self, obj, many=None): ...
80
    def load(self, json_data, many=None, partial=None, unknown=None): ...
81
    def loads(self, json_str, many=None, partial=None, unknown=None): ...
82
    def validate(self, json_data, many=None, partial=None, unknown=None): ...
83

84
class SchemaOpts:
85
    def __init__(self, meta, **kwargs): ...
86
```
87

88
[Schema Definition](./schema-definition.md)
89

90
### Field Types and Data Conversion
91

92
Comprehensive field types for handling strings, numbers, dates, containers, relationships, and specialized data formats with validation and transformation capabilities.
93

94
```python { .api }
95
class Field:
96
    def __init__(self, *, dump_default=missing, load_default=missing, data_key=None, 
97
                 attribute=None, validate=None, required=False, allow_none=None, 
98
                 load_only=False, dump_only=False, error_messages=None, metadata=None): ...
99

100
# String and Text Fields
101
class String(Field): ...
102
class Email(Field): ...
103
class URL(Field): ...
104
class UUID(Field): ...
105

106
# Numeric Fields  
107
class Integer(Field): ...
108
class Float(Field): ...
109
class Decimal(Field): ...
110

111
# Date/Time Fields
112
class DateTime(Field): ...
113
class Date(Field): ...
114
class Time(Field): ...
115

116
# Container Fields
117
class List(Field): ...
118
class Dict(Field): ...
119
class Nested(Field): ...
120
```
121

122
[Field Types](./field-types.md)
123

124
### Validation Framework
125

126
Built-in validators for common patterns and custom validation support, including string validation, numeric ranges, collection constraints, and schema-level validation.
127

128
```python { .api }
129
class Validator:
130
    def __call__(self, value): ...
131

132
# String Validators
133
class Email(Validator): ...
134
class URL(Validator): ...
135
class Regexp(Validator): ...
136

137
# Numeric Validators
138
class Range(Validator): ...
139

140
# Collection Validators
141
class Length(Validator): ...
142
class OneOf(Validator): ...
143
class ContainsOnly(Validator): ...
144
```
145

146
[Validation](./validation.md)
147

148
### Processing Decorators and Hooks
149

150
Decorators for custom data transformation and validation logic that execute before and after serialization/deserialization operations.
151

152
```python { .api }
153
def pre_dump(pass_collection=False): ...
154
def post_dump(pass_collection=False, pass_original=False): ...
155
def pre_load(pass_collection=False): ...
156
def post_load(pass_collection=False, pass_original=False): ...
157
def validates(*field_names): ...
158
def validates_schema(pass_collection=False, pass_original=False, skip_on_field_errors=True): ...
159
```
160

161
[Decorators and Hooks](./decorators-hooks.md)
162

163
### Error Handling and Utilities
164

165
Exception types for validation errors, utility functions for data manipulation, and helper classes for advanced use cases.
166

167
```python { .api }
168
class ValidationError(Exception):
169
    def __init__(self, message, field_name=None, data=None, valid_data=None, **kwargs): ...
170

171
class MarshmallowError(Exception): ...
172
class RegistryError(Exception): ...
173

174
# Utility Functions
175
def get_value(obj, key, default=missing): ...
176
def set_value(dct, key, value): ...
177
def pluck(dictlist, key): ...
178
```
179

180
[Exceptions and Utilities](./exceptions-utils.md)
181

182
## Constants
183

184
### Unknown Field Handling
185

186
```python { .api }
187
EXCLUDE = "exclude"  # Ignore unknown fields
188
INCLUDE = "include"  # Include unknown fields in output
189
RAISE = "raise"      # Raise ValidationError for unknown fields
190
```
191

192
### Missing Value Sentinel
193

194
```python { .api }
195
missing = <missing>  # Sentinel for missing/undefined values
196
```