API Reference¶

Schema¶

class marshmallow.Schema(only=None, exclude=(), prefix='', many=False, context=None, load_only=(), dump_only=(), partial=False, unknown=None)[source]¶

Base schema class with which to define custom schemas.

Example usage:

import datetime as dt
from marshmallow import Schema, fields

class Album(object):
    def __init__(self, title, release_date):
        self.title = title
        self.release_date = release_date

class AlbumSchema(Schema):
    title = fields.Str()
    release_date = fields.Date()

# Or, equivalently
class AlbumSchema2(Schema):
    class Meta:
        fields = ("title", "release_date")

album = Album("Beggars Banquet", dt.date(1968, 12, 6))
schema = AlbumSchema()
data, errors = schema.dump(album)
data  # {'release_date': '1968-12-06', 'title': 'Beggars Banquet'}

Parameters:

only (tuple|list) – Whitelist of the declared fields to select when instantiating the Schema. If None, all fields are used. Nested fields can be represented with dot delimiters.
exclude (tuple|list) – Blacklist of the declared fields to exclude when instantiating the Schema. If a field appears in both only and exclude, it is not used. Nested fields can be represented with dot delimiters.
prefix (str) – Optional prefix that will be prepended to all the serialized field names.
many (bool) – Should be set to True if obj is a collection so that the object will be serialized to a list.
context (dict) – Optional context passed to fields.Method and fields.Function fields.
load_only (tuple|list) – Fields to skip during serialization (write-only fields)
dump_only (tuple|list) – Fields to skip during deserialization (read-only fields)
partial (bool|tuple) – Whether to ignore missing fields. If its value is an iterable, only missing fields listed in that iterable will be ignored.
unknown – Whether to exclude, include, or raise an error for unknown fields in the data. Use EXCLUDE, INCLUDE or RAISE.

Changed in version 2.0.0: __validators__, __preprocessors__, and __data_handlers__ are removed in favor of marshmallow.decorators.validates_schema, marshmallow.decorators.pre_load and marshmallow.decorators.post_dump. __accessor__ and __error_handler__ are deprecated. Implement the handle_error and get_attribute methods instead.

class Meta¶

Options object for a Schema.

Example usage:

class Meta:
    fields = ("id", "email", "date_created")
    exclude = ("password", "secret_attribute")

Available options:

fields: Tuple or list of fields to include in the serialized result.
additional: Tuple or list of fields to include in addition to the

explicitly declared fields. additional and fields are mutually-exclusive options.
include: Dictionary of additional fields to include in the schema. It is

usually better to define fields as class variables, but you may need to use this option, e.g., if your fields are Python keywords. May be an OrderedDict.
exclude: Tuple or list of fields to exclude in the serialized result.

Nested fields can be represented with dot delimiters.
dateformat: Date format for all DateTime fields that do not have their

date format explicitly specified.
render_module: Module to use for loads and dumps. Defaults to

json from the standard library.
ordered: If True, order serialization output according to the

order in which fields were declared. Output of Schema.dump will be a collections.OrderedDict.
index_errors: If True, errors dictionaries will include the index

of invalid items in a collection.
load_only: Tuple or list of fields to exclude from serialized results.
dump_only: Tuple or list of fields to exclude from deserialization
unknown: Whether to exclude, include, or raise an error for unknown

fields in the data. Use EXCLUDE, INCLUDE or RAISE.

OPTIONS_CLASS¶: alias of SchemaOpts

dump(obj, many=None, update_fields=True)¶

Serialize an object to native Python data types according to this Schema’s fields.

Parameters:	obj – The object to serialize. many (bool) – Whether to serialize `obj` as a collection. If `None`, the value for `self.many` is used. update_fields (bool) – Whether to update the schema’s field classes. Typically set to `True`, but may be `False` when serializing a homogenous collection. This parameter is used by `fields.Nested` to avoid multiple updates.
Returns:	A dict of serialized data
Return type:	dict

New in version 1.0.0.

Changed in version 3.0.0b7: This method returns the serialized data rather than a (data, errors) duple. A ValidationError is raised if obj is invalid.

dumps(obj, many=None, update_fields=True, *args, **kwargs)¶

Same as dump(), except return a JSON-encoded string.

Parameters:	obj – The object to serialize. many (bool) – Whether to serialize `obj` as a collection. If `None`, the value for `self.many` is used. update_fields (bool) – Whether to update the schema’s field classes. Typically set to `True`, but may be `False` when serializing a homogenous collection. This parameter is used by `fields.Nested` to avoid multiple updates.
Returns:	A `json` string
Return type:	str

New in version 1.0.0.

Changed in version 3.0.0b7: This method returns the serialized data rather than a (data, errors) duple. A ValidationError is raised if obj is invalid.

get_attribute(obj, attr, default)¶: Defines how to pull values from an object to serialize.

New in version 2.0.0.

Changed in version 3.0.0a1: Changed position of obj and attr.

handle_error(error, data)¶

Custom error handler function for the schema.

Parameters:	error (ValidationError) – The `ValidationError` raised during (de)serialization. data – The original input data.

New in version 2.0.0.

load(data, many=None, partial=None, unknown=None)¶

Deserialize a data structure to an object defined by this Schema’s fields and make_object().

Parameters:	data (dict) – The data to deserialize. many (bool) – Whether to deserialize `data` as a collection. If `None`, the value for `self.many` is used. partial (bool\|tuple) – Whether to ignore missing fields. If `None`, the value for `self.partial` is used. If its value is an iterable, only missing fields listed in that iterable will be ignored. unknown – Whether to exclude, include, or raise an error for unknown fields in the data. Use `EXCLUDE`, `INCLUDE` or `RAISE`. If `None`, the value for `self.unknown` is used.
Returns:	A dict of deserialized data
Return type:	dict

New in version 1.0.0.

Changed in version 3.0.0b7: This method returns the deserialized data rather than a (data, errors) duple. A ValidationError is raised if invalid data are passed.

loads(json_data, many=None, partial=None, unknown=None, **kwargs)¶

Same as load(), except it takes a JSON string as input.

Parameters:	json_data (str) – A JSON string of the data to deserialize. many (bool) – Whether to deserialize `obj` as a collection. If `None`, the value for `self.many` is used. partial (bool\|tuple) – Whether to ignore missing fields. If `None`, the value for `self.partial` is used. If its value is an iterable, only missing fields listed in that iterable will be ignored. unknown – Whether to exclude, include, or raise an error for unknown fields in the data. Use `EXCLUDE`, `INCLUDE` or `RAISE`. If `None`, the value for `self.unknown` is used.
Returns:	A dict of deserialized data
Return type:	dict

New in version 1.0.0.

Changed in version 3.0.0b7: This method returns the deserialized data rather than a (data, errors) duple. A ValidationError is raised if invalid data are passed.

on_bind_field(field_name, field_obj)¶: Hook to modify a field when it is bound to the Schema. No-op by default.

validate(data, many=None, partial=None)¶

Validate data against the schema, returning a dictionary of validation errors.

Parameters:	data (dict) – The data to validate. many (bool) – Whether to validate `data` as a collection. If `None`, the value for `self.many` is used. partial (bool\|tuple) – Whether to ignore missing fields. If `None`, the value for `self.partial` is used. If its value is an iterable, only missing fields listed in that iterable will be ignored.
Returns:	A dictionary of validation errors.
Return type:	dict

New in version 1.1.0.

class marshmallow.SchemaOpts(meta, ordered=False)[source]¶: class Meta options for the Schema. Defines defaults.

marshmallow.pprint(obj, *args, **kwargs)[source]¶: Pretty-printing function that can pretty-print OrderedDicts like regular dictionaries. Useful for printing the output of marshmallow.Schema.dump().

Fields¶

Field classes for various types of data.

class marshmallow.fields.Field(default=<marshmallow.missing>, attribute=None, data_key=None, error=None, validate=None, required=False, allow_none=None, load_only=False, dump_only=False, missing=<marshmallow.missing>, error_messages=None, **metadata)[source]¶

Basic field from which other fields should extend. It applies no formatting by default, and should only be used in cases where data does not need to be formatted before being serialized or deserialized. On error, the name of the field will be returned.

Parameters:

default – If set, this value will be used during serialization if the input value is missing. If not set, the field will be excluded from the serialized output if the input value is missing. May be a value or a callable.
attribute (str) – The name of the attribute to get the value from when serializing. If None, assumes the attribute has the same name as the field.
data_key (str) – The name of the key to get the value from when deserializing. If None, assumes the key has the same name as the field.
validate (callable) – Validator or collection of validators that are called during deserialization. Validator takes a field’s input value as its only parameter and returns a boolean. If it returns False, an ValidationError is raised.
required – Raise a ValidationError if the field value is not supplied during deserialization.
allow_none – Set this to True if None should be considered a valid value during validation/deserialization. If missing=None and allow_none is unset, will default to True. Otherwise, the default is False.
load_only (bool) – If True skip this field during serialization, otherwise its value will be present in the serialized data.
dump_only (bool) – If True skip this field during deserialization, otherwise its value will be present in the deserialized object. In the context of an HTTP API, this effectively marks the field as “read-only”.
missing – Default deserialization value for the field if the field is not found in the input data. May be a value or a callable.
error_messages (dict) – Overrides for Field.default_error_messages.
metadata – Extra arguments to be stored as metadata.

Changed in version 2.0.0: Removed error parameter. Use error_messages instead.

Changed in version 2.0.0: Added allow_none parameter, which makes validation/deserialization of None consistent across fields.

Changed in version 2.0.0: Added load_only and dump_only parameters, which allow field skipping during the (de)serialization process.

Changed in version 2.0.0: Added missing parameter, which indicates the value for a field if the field is not found during deserialization.

Changed in version 2.0.0: default value is only used if explicitly set. Otherwise, missing values inputs are excluded from serialized output.

Changed in version 3.0.0b8: Add data_key parameter for the specifying the key in the input and output data. This parameter replaced both load_from and dump_to.

_add_to_schema(field_name, schema)[source]¶

Update field with values from its parent schema. Called by: __set_field_attrs.

Parameters:	field_name (str) – Field name set in schema. schema (Schema) – Parent schema.

_deserialize(value, attr, data)[source]¶

Deserialize value. Concrete Field classes should implement this method.

Parameters:	value – The value to be deserialized. attr (str) – The attribute/key in `data` to be deserialized. data (dict) – The raw input data passed to the `Schema.load`.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The deserialized value.

Changed in version 2.0.0: Added attr and data parameters.

_serialize(value, attr, obj)[source]¶

Serializes value to a basic Python datatype. Noop by default. Concrete Field classes should implement this method.

Example:

class TitleCase(Field):
    def _serialize(self, value, attr, obj):
        if not value:
            return ''
        return unicode(value).title()

Parameters:	value – The value to be serialized. attr (str) – The attribute or key on the object to be serialized. obj (object) – The object the value was pulled from.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The serialized value

_validate(value)[source]¶: Perform validation on value. Raise a ValidationError if validation does not succeed.

_validate_missing(value)[source]¶: Validate missing values. Raise a ValidationError if value should be considered missing.

context¶: The context dictionary for the parent Schema.

default_error_messages = {'null': 'Field may not be null.', 'required': 'Missing data for required field.', 'validator_failed': 'Invalid value.'}¶: Default error messages for various kinds of errors. The keys in this dictionary are passed to Field.fail. The values are error messages passed to marshmallow.ValidationError.

deserialize(value, attr=None, data=None)[source]¶

Deserialize value.

Raises:	ValidationError – If an invalid value is passed or if a required value is missing.

fail(key, **kwargs)[source]¶: A helper method that simply raises a ValidationError.

get_value(obj, attr, accessor=None, default=<marshmallow.missing>)[source]¶

Return the value for a given key from an object.

Parameters:	obj (object) – The object to get the value from attr (str) – The attribute/key in `obj` to get the value from. accessor (callable) – A callable used to retrieve the value of `attr` from the object `obj`. Defaults to `marshmallow.utils.get_value`.

root¶: Reference to the Schema that this field belongs to even if it is buried in a List. Return None for unbound fields.

serialize(attr, obj, accessor=None)[source]¶

Pulls the value for the given key from the object, applies the field’s formatting and returns the result.

Parameters:	attr (str) – The attribute or key to get from the object. obj (str) – The object to pull the key from. accessor (callable) – Function used to pull values from `obj`.
Raises:	ValidationError – In case of formatting problem

class marshmallow.fields.Raw(default=<marshmallow.missing>, attribute=None, data_key=None, error=None, validate=None, required=False, allow_none=None, load_only=False, dump_only=False, missing=<marshmallow.missing>, error_messages=None, **metadata)[source]¶: Field that applies no formatting or validation.

class marshmallow.fields.Nested(nested, default=<marshmallow.missing>, exclude=(), only=None, **kwargs)[source]¶

Allows you to nest a Schema inside a field.

Examples:

user = fields.Nested(UserSchema)
user2 = fields.Nested('UserSchema')  # Equivalent to above
collaborators = fields.Nested(UserSchema, many=True, only=('id',))
parent = fields.Nested('self')

When passing a Schema instance as the first argument, the instance’s exclude, only, and many attributes will be respected.

Therefore, when passing the exclude, only, or many arguments to fields.Nested, you should pass a Schema class (not an instance) as the first argument.

# Yes
author = fields.Nested(UserSchema, only=('id', 'name'))

# No
author = fields.Nested(UserSchema(), only=('id', 'name'))

Parameters:

nested (Schema) – The Schema class or class name (string) to nest, or "self" to nest the Schema within itself.
exclude (tuple) – A list or tuple of fields to exclude.
only – A tuple or string of the field(s) to marshal. If None, all fields will be marshalled. If a field name (string) is given, only a single value will be returned as output instead of a dictionary. This parameter takes precedence over exclude.
many (bool) – Whether the field is a collection of objects.
unknown – Whether to exclude, include, or raise an error for unknown fields in the data. Use EXCLUDE, INCLUDE or RAISE.
kwargs – The same keyword arguments that Field receives.

_deserialize(value, attr, data)[source]¶

Deserialize value. Concrete Field classes should implement this method.

Parameters:	value – The value to be deserialized. attr (str) – The attribute/key in `data` to be deserialized. data (dict) – The raw input data passed to the `Schema.load`.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The deserialized value.

Changed in version 2.0.0: Added attr and data parameters.

_serialize(nested_obj, attr, obj)[source]¶

Serializes value to a basic Python datatype. Noop by default. Concrete Field classes should implement this method.

Example:

class TitleCase(Field):
    def _serialize(self, value, attr, obj):
        if not value:
            return ''
        return unicode(value).title()

Parameters:	value – The value to be serialized. attr (str) – The attribute or key on the object to be serialized. obj (object) – The object the value was pulled from.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The serialized value

schema¶: The nested Schema object.

Changed in version 1.0.0: Renamed from serializer to schema

class marshmallow.fields.Dict(values=None, keys=None, **kwargs)[source]¶

A dict field. Supports dicts and dict-like objects. Optionally composed with another Field class or instance.

Example:

numbers = fields.Dict(values=fields.Float(), keys=fields.Str())

Parameters:	values (Field) – A field class or instance for dict values. keys (Field) – A field class or instance for dict keys. kwargs – The same keyword arguments that `Field` receives.

Note

When the structure of nested data is not known, you may omit the values and keys arguments to prevent content validation.

New in version 2.1.0.

_add_to_schema(field_name, schema)[source]¶

Update field with values from its parent schema. Called by: __set_field_attrs.

Parameters:	field_name (str) – Field name set in schema. schema (Schema) – Parent schema.

_deserialize(value, attr, data)[source]¶

Deserialize value. Concrete Field classes should implement this method.

Parameters:	value – The value to be deserialized. attr (str) – The attribute/key in `data` to be deserialized. data (dict) – The raw input data passed to the `Schema.load`.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The deserialized value.

Changed in version 2.0.0: Added attr and data parameters.

_serialize(value, attr, obj)[source]¶

Serializes value to a basic Python datatype. Noop by default. Concrete Field classes should implement this method.

Example:

class TitleCase(Field):
    def _serialize(self, value, attr, obj):
        if not value:
            return ''
        return unicode(value).title()

Parameters:	value – The value to be serialized. attr (str) – The attribute or key on the object to be serialized. obj (object) – The object the value was pulled from.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The serialized value

class marshmallow.fields.List(cls_or_instance, **kwargs)[source]¶

A list field, composed with another Field class or instance.

Example:

numbers = fields.List(fields.Float())

Parameters:	cls_or_instance (Field) – A field class or instance. default (bool) – Default value for serialization. kwargs – The same keyword arguments that `Field` receives.

Changed in version 2.0.0: The allow_none parameter now applies to deserialization and has the same semantics as the other fields.

_add_to_schema(field_name, schema)[source]¶

Update field with values from its parent schema. Called by: __set_field_attrs.

Parameters:	field_name (str) – Field name set in schema. schema (Schema) – Parent schema.

_deserialize(value, attr, data)[source]¶

Deserialize value. Concrete Field classes should implement this method.

Parameters:	value – The value to be deserialized. attr (str) – The attribute/key in `data` to be deserialized. data (dict) – The raw input data passed to the `Schema.load`.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The deserialized value.

Changed in version 2.0.0: Added attr and data parameters.

_serialize(value, attr, obj)[source]¶

Serializes value to a basic Python datatype. Noop by default. Concrete Field classes should implement this method.

Example:

class TitleCase(Field):
    def _serialize(self, value, attr, obj):
        if not value:
            return ''
        return unicode(value).title()

Parameters:	value – The value to be serialized. attr (str) – The attribute or key on the object to be serialized. obj (object) – The object the value was pulled from.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The serialized value

get_value(obj, attr, accessor=None)[source]¶: Return the value for a given key from an object.

class marshmallow.fields.String(default=<marshmallow.missing>, attribute=None, data_key=None, error=None, validate=None, required=False, allow_none=None, load_only=False, dump_only=False, missing=<marshmallow.missing>, error_messages=None, **metadata)[source]¶

A string field.

Parameters:	kwargs – The same keyword arguments that `Field` receives.

_deserialize(value, attr, data)[source]¶

Deserialize value. Concrete Field classes should implement this method.

Parameters:	value – The value to be deserialized. attr (str) – The attribute/key in `data` to be deserialized. data (dict) – The raw input data passed to the `Schema.load`.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The deserialized value.

Changed in version 2.0.0: Added attr and data parameters.

_serialize(value, attr, obj)[source]¶

Serializes value to a basic Python datatype. Noop by default. Concrete Field classes should implement this method.

Example:

class TitleCase(Field):
    def _serialize(self, value, attr, obj):
        if not value:
            return ''
        return unicode(value).title()

Parameters:	value – The value to be serialized. attr (str) – The attribute or key on the object to be serialized. obj (object) – The object the value was pulled from.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The serialized value

class marshmallow.fields.UUID(default=<marshmallow.missing>, attribute=None, data_key=None, error=None, validate=None, required=False, allow_none=None, load_only=False, dump_only=False, missing=<marshmallow.missing>, error_messages=None, **metadata)[source]¶

A UUID field.

_deserialize(value, attr, data)[source]¶

Deserialize value. Concrete Field classes should implement this method.

Parameters:	value – The value to be deserialized. attr (str) – The attribute/key in `data` to be deserialized. data (dict) – The raw input data passed to the `Schema.load`.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The deserialized value.

Changed in version 2.0.0: Added attr and data parameters.

_serialize(value, attr, obj)[source]¶

Serializes value to a basic Python datatype. Noop by default. Concrete Field classes should implement this method.

Example:

class TitleCase(Field):
    def _serialize(self, value, attr, obj):
        if not value:
            return ''
        return unicode(value).title()

Parameters:	value – The value to be serialized. attr (str) – The attribute or key on the object to be serialized. obj (object) – The object the value was pulled from.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The serialized value

_validated(value)[source]¶: Format the value or raise a ValidationError if an error occurs.

class marshmallow.fields.Number(as_string=False, **kwargs)[source]¶

Base class for number fields.

Parameters:	as_string (bool) – If True, format the serialized value as a string. kwargs – The same keyword arguments that `Field` receives.

_deserialize(value, attr, data)[source]¶

Deserialize value. Concrete Field classes should implement this method.

Parameters:	value – The value to be deserialized. attr (str) – The attribute/key in `data` to be deserialized. data (dict) – The raw input data passed to the `Schema.load`.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The deserialized value.

Changed in version 2.0.0: Added attr and data parameters.

_format_num(value)[source]¶: Return the number value for value, given this field’s num_type.

_serialize(value, attr, obj)[source]¶: Return a string if self.as_string=True, otherwise return this field’s num_type.

_validated(value)[source]¶: Format the value or raise a ValidationError if an error occurs.

num_type¶: alias of builtins.float

class marshmallow.fields.Integer(strict=False, **kwargs)[source]¶

An integer field.

Parameters:	kwargs – The same keyword arguments that `Number` receives.

_format_num(value)[source]¶: Return the number value for value, given this field’s num_type.

num_type¶: alias of builtins.int

class marshmallow.fields.Decimal(places=None, rounding=None, allow_nan=False, as_string=False, **kwargs)[source]¶

A field that (de)serializes to the Python decimal.Decimal type. It’s safe to use when dealing with money values, percentages, ratios or other numbers where precision is critical.

Warning

This field serializes to a decimal.Decimal object by default. If you need to render your data as JSON, keep in mind that the json module from the standard library does not encode decimal.Decimal. Therefore, you must use a JSON library that can handle decimals, such as simplejson, or serialize to a string by passing as_string=True.

Warning

If a JSON float value is passed to this field for deserialization it will first be cast to its corresponding string value before being deserialized to a decimal.Decimal object. The default __str__ implementation of the built-in Python float type may apply a destructive transformation upon its input data and therefore cannot be relied upon to preserve precision. To avoid this, you can instead pass a JSON string to be deserialized directly.

Parameters:

places (int) – How many decimal places to quantize the value. If None, does not quantize the value.
rounding – How to round the value during quantize, for example decimal.ROUND_UP. If None, uses the rounding value from the current thread’s context.
allow_nan (bool) – If True, NaN, Infinity and -Infinity are allowed, even though they are illegal according to the JSON specification.
as_string (bool) – If True, serialize to a string instead of a Python decimal.Decimal type.
kwargs – The same keyword arguments that Number receives.

New in version 1.2.0.

_format_num(value)[source]¶: Return the number value for value, given this field’s num_type.

_validated(value)[source]¶: Format the value or raise a ValidationError if an error occurs.

num_type¶: alias of decimal.Decimal

class marshmallow.fields.Boolean(truthy=None, falsy=None, **kwargs)[source]¶

A boolean field.

Parameters:	truthy (set) – Values that will (de)serialize to `True`. If an empty set, any non-falsy value will deserialize to `True`. If `None`, `marshmallow.fields.Boolean.truthy` will be used. falsy (set) – Values that will (de)serialize to `False`. If `None`, `marshmallow.fields.Boolean.falsy` will be used. kwargs – The same keyword arguments that `Field` receives.

_deserialize(value, attr, data)[source]¶

Deserialize value. Concrete Field classes should implement this method.

Parameters:	value – The value to be deserialized. attr (str) – The attribute/key in `data` to be deserialized. data (dict) – The raw input data passed to the `Schema.load`.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The deserialized value.

Changed in version 2.0.0: Added attr and data parameters.

_serialize(value, attr, obj)[source]¶

Serializes value to a basic Python datatype. Noop by default. Concrete Field classes should implement this method.

Example:

class TitleCase(Field):
    def _serialize(self, value, attr, obj):
        if not value:
            return ''
        return unicode(value).title()

Parameters:	value – The value to be serialized. attr (str) – The attribute or key on the object to be serialized. obj (object) – The object the value was pulled from.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The serialized value

falsy = {0, 'OFF', 'F', 'off', 'Off', 'false', 'False', '0', 'f', 'FALSE'}¶: Default falsy values.

truthy = {1, 'True', 'true', 'On', 'on', '1', 't', 'ON', 'T', 'TRUE'}¶: Default truthy values.

class marshmallow.fields.FormattedString(src_str, *args, **kwargs)[source]¶

Interpolate other values from the object into this field. The syntax for the source string is the same as the string str.format method from the python stdlib.

class UserSchema(Schema):
    name = fields.String()
    greeting = fields.FormattedString('Hello {name}')

ser = UserSchema()
res = ser.dump(user)
res.data  # => {'name': 'Monty', 'greeting': 'Hello Monty'}

_serialize(value, attr, obj)[source]¶

Serializes value to a basic Python datatype. Noop by default. Concrete Field classes should implement this method.

Example:

class TitleCase(Field):
    def _serialize(self, value, attr, obj):
        if not value:
            return ''
        return unicode(value).title()

Parameters:	value – The value to be serialized. attr (str) – The attribute or key on the object to be serialized. obj (object) – The object the value was pulled from.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The serialized value

class marshmallow.fields.Float(allow_nan=False, as_string=False, **kwargs)[source]¶

A double as IEEE-754 double precision string.

Parameters:	allow_nan (bool) – If `True`, `NaN`, `Infinity` and `-Infinity` are allowed, even though they are illegal according to the JSON specification. as_string (bool) – If True, format the value as a string. kwargs – The same keyword arguments that `Number` receives.

_format_num(value)[source]¶: Return the number value for value, given this field’s num_type.

num_type¶: alias of builtins.float

class marshmallow.fields.DateTime(format=None, **kwargs)[source]¶

A formatted datetime string in UTC.

Example: '2014-12-22T03:12:58.019077+00:00'

Timezone-naive datetime objects are converted to UTC (+00:00) by Schema.dump. Schema.load returns datetime objects that are timezone-aware.

Parameters:	format (str) – Either `"rfc"` (for RFC822), `"iso"` (for ISO8601), or a date format string. If `None`, defaults to “iso”. kwargs – The same keyword arguments that `Field` receives.

_add_to_schema(field_name, schema)[source]¶

Update field with values from its parent schema. Called by: __set_field_attrs.

Parameters:	field_name (str) – Field name set in schema. schema (Schema) – Parent schema.

_deserialize(value, attr, data)[source]¶

Deserialize value. Concrete Field classes should implement this method.

Parameters:	value – The value to be deserialized. attr (str) – The attribute/key in `data` to be deserialized. data (dict) – The raw input data passed to the `Schema.load`.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The deserialized value.

Changed in version 2.0.0: Added attr and data parameters.

_serialize(value, attr, obj)[source]¶

Serializes value to a basic Python datatype. Noop by default. Concrete Field classes should implement this method.

Example:

class TitleCase(Field):
    def _serialize(self, value, attr, obj):
        if not value:
            return ''
        return unicode(value).title()

Parameters:	value – The value to be serialized. attr (str) – The attribute or key on the object to be serialized. obj (object) – The object the value was pulled from.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The serialized value

class marshmallow.fields.LocalDateTime(format=None, **kwargs)[source]¶

A formatted datetime string in localized time, relative to UTC.

ex. "Sun, 10 Nov 2013 08:23:45 -0600"

Takes the same arguments as DateTime.

class marshmallow.fields.Time(default=<marshmallow.missing>, attribute=None, data_key=None, error=None, validate=None, required=False, allow_none=None, load_only=False, dump_only=False, missing=<marshmallow.missing>, error_messages=None, **metadata)[source]¶

ISO8601-formatted time string.

Parameters:	kwargs – The same keyword arguments that `Field` receives.

_deserialize(value, attr, data)[source]¶: Deserialize an ISO8601-formatted time to a datetime.time object.

_serialize(value, attr, obj)[source]¶

Serializes value to a basic Python datatype. Noop by default. Concrete Field classes should implement this method.

Example:

class TitleCase(Field):
    def _serialize(self, value, attr, obj):
        if not value:
            return ''
        return unicode(value).title()

Parameters:	value – The value to be serialized. attr (str) – The attribute or key on the object to be serialized. obj (object) – The object the value was pulled from.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The serialized value

class marshmallow.fields.Date(default=<marshmallow.missing>, attribute=None, data_key=None, error=None, validate=None, required=False, allow_none=None, load_only=False, dump_only=False, missing=<marshmallow.missing>, error_messages=None, **metadata)[source]¶

ISO8601-formatted date string.

Parameters:	kwargs – The same keyword arguments that `Field` receives.

_deserialize(value, attr, data)[source]¶: Deserialize an ISO8601-formatted date string to a datetime.date object.

_serialize(value, attr, obj)[source]¶

Serializes value to a basic Python datatype. Noop by default. Concrete Field classes should implement this method.

Example:

class TitleCase(Field):
    def _serialize(self, value, attr, obj):
        if not value:
            return ''
        return unicode(value).title()

Parameters:	value – The value to be serialized. attr (str) – The attribute or key on the object to be serialized. obj (object) – The object the value was pulled from.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The serialized value

class marshmallow.fields.TimeDelta(precision='seconds', error=None, **kwargs)[source]¶

A field that (de)serializes a datetime.timedelta object to an integer and vice versa. The integer can represent the number of days, seconds or microseconds.

Parameters:	precision (str) – Influences how the integer is interpreted during (de)serialization. Must be ‘days’, ‘seconds’, ‘microseconds’, ‘milliseconds’, ‘minutes’, ‘hours’ or ‘weeks’. error (str) – Error message stored upon validation failure. kwargs – The same keyword arguments that `Field` receives.

Changed in version 2.0.0: Always serializes to an integer value to avoid rounding errors. Add precision parameter.

_deserialize(value, attr, data)[source]¶

Deserialize value. Concrete Field classes should implement this method.

Parameters:	value – The value to be deserialized. attr (str) – The attribute/key in `data` to be deserialized. data (dict) – The raw input data passed to the `Schema.load`.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The deserialized value.

Changed in version 2.0.0: Added attr and data parameters.

_serialize(value, attr, obj)[source]¶

Serializes value to a basic Python datatype. Noop by default. Concrete Field classes should implement this method.

Example:

class TitleCase(Field):
    def _serialize(self, value, attr, obj):
        if not value:
            return ''
        return unicode(value).title()

Parameters:	value – The value to be serialized. attr (str) – The attribute or key on the object to be serialized. obj (object) – The object the value was pulled from.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The serialized value

class marshmallow.fields.Url(relative=False, schemes=None, require_tld=True, **kwargs)[source]¶

A validated URL field. Validation occurs during both serialization and deserialization.

Parameters:	default – Default value for the field if the attribute is not set. attribute (str) – The name of the attribute to get the value from. If `None`, assumes the attribute has the same name as the field. relative (bool) – Allow relative URLs. kwargs – The same keyword arguments that `String` receives.

marshmallow.fields.URL¶: alias of marshmallow.fields.Url

class marshmallow.fields.Email(*args, **kwargs)[source]¶

A validated email field. Validation occurs during both serialization and deserialization.

Parameters:	args – The same positional arguments that `String` receives. kwargs – The same keyword arguments that `String` receives.

class marshmallow.fields.Method(serialize=None, deserialize=None, **kwargs)[source]¶

A field that takes the value returned by a Schema method.

Parameters:	serialize (str) – The name of the Schema method from which to retrieve the value. The method must take an argument `obj` (in addition to self) that is the object to be serialized. deserialize (str) – Optional name of the Schema method for deserializing a value The method must take a single argument `value`, which is the value to deserialize.

Changed in version 2.0.0: Removed optional context parameter on methods. Use self.context instead.

Changed in version 2.3.0: Deprecated method_name parameter in favor of serialize and allow serialize to not be passed at all.

Changed in version 3.0.0: Removed method_name parameter.

_deserialize(value, attr, data)[source]¶

Deserialize value. Concrete Field classes should implement this method.

Parameters:	value – The value to be deserialized. attr (str) – The attribute/key in `data` to be deserialized. data (dict) – The raw input data passed to the `Schema.load`.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The deserialized value.

Changed in version 2.0.0: Added attr and data parameters.

_serialize(value, attr, obj)[source]¶

Serializes value to a basic Python datatype. Noop by default. Concrete Field classes should implement this method.

Example:

class TitleCase(Field):
    def _serialize(self, value, attr, obj):
        if not value:
            return ''
        return unicode(value).title()

Parameters:	value – The value to be serialized. attr (str) – The attribute or key on the object to be serialized. obj (object) – The object the value was pulled from.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The serialized value

class marshmallow.fields.Function(serialize=None, deserialize=None, func=None, **kwargs)[source]¶

A field that takes the value returned by a function.

Parameters:

serialize (callable) – A callable from which to retrieve the value. The function must take a single argument obj which is the object to be serialized. It can also optionally take a context argument, which is a dictionary of context variables passed to the serializer. If no callable is provided then the `load_only` flag will be set to True.
deserialize (callable) – A callable from which to retrieve the value. The function must take a single argument value which is the value to be deserialized. It can also optionally take a context argument, which is a dictionary of context variables passed to the deserializer. If no callable is provided then `value` will be passed through unchanged.

Changed in version 2.3.0: Deprecated func parameter in favor of serialize.

Changed in version 3.0.0a1: Removed func parameter.

_deserialize(value, attr, data)[source]¶

Deserialize value. Concrete Field classes should implement this method.

Parameters:	value – The value to be deserialized. attr (str) – The attribute/key in `data` to be deserialized. data (dict) – The raw input data passed to the `Schema.load`.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The deserialized value.

Changed in version 2.0.0: Added attr and data parameters.

_serialize(value, attr, obj)[source]¶

Serializes value to a basic Python datatype. Noop by default. Concrete Field classes should implement this method.

Example:

class TitleCase(Field):
    def _serialize(self, value, attr, obj):
        if not value:
            return ''
        return unicode(value).title()

Parameters:	value – The value to be serialized. attr (str) – The attribute or key on the object to be serialized. obj (object) – The object the value was pulled from.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The serialized value

marshmallow.fields.Str¶: alias of marshmallow.fields.String

marshmallow.fields.Bool¶: alias of marshmallow.fields.Boolean

marshmallow.fields.Int¶: alias of marshmallow.fields.Integer

class marshmallow.fields.Constant(constant, **kwargs)[source]¶

A field that (de)serializes to a preset constant. If you only want the constant added for serialization or deserialization, you should use dump_only=True or load_only=True respectively.

Parameters:	constant – The constant to return for the field attribute.

New in version 2.0.0.

_deserialize(value, *args, **kwargs)[source]¶

Deserialize value. Concrete Field classes should implement this method.

Parameters:	value – The value to be deserialized. attr (str) – The attribute/key in `data` to be deserialized. data (dict) – The raw input data passed to the `Schema.load`.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The deserialized value.

Changed in version 2.0.0: Added attr and data parameters.

_serialize(value, *args, **kwargs)[source]¶

Serializes value to a basic Python datatype. Noop by default. Concrete Field classes should implement this method.

Example:

class TitleCase(Field):
    def _serialize(self, value, attr, obj):
        if not value:
            return ''
        return unicode(value).title()

Parameters:	value – The value to be serialized. attr (str) – The attribute or key on the object to be serialized. obj (object) – The object the value was pulled from.
Raises:	ValidationError – In case of formatting or validation failure.
Returns:	The serialized value

Decorators¶

Decorators for registering schema pre-processing and post-processing methods. These should be imported from the top-level marshmallow module.

Example:

from marshmallow import (
    Schema, pre_load, pre_dump, post_load, validates_schema,
    validates, fields, ValidationError
)

class UserSchema(Schema):

    email = fields.Str(required=True)
    age = fields.Integer(required=True)

    @post_load
    def lowerstrip_email(self, item):
        item['email'] = item['email'].lower().strip()
        return item

    @pre_load(pass_many=True)
    def remove_envelope(self, data, many):
        namespace = 'results' if many else 'result'
        return data[namespace]

    @post_dump(pass_many=True)
    def add_envelope(self, data, many):
        namespace = 'results' if many else 'result'
        return {namespace: data}

    @validates_schema
    def validate_email(self, data):
        if len(data['email']) < 3:
            raise ValidationError('Email must be more than 3 characters', 'email')

    @validates('age')
    def validate_age(self, data):
        if data < 14:
            raise ValidationError('Too young!')

Note

These decorators only work with instance methods. Class and static methods are not supported.

Warning

The invocation order of decorated methods of the same type is not guaranteed. If you need to guarantee order of different processing steps, you should put them in the same processing method.

marshmallow.decorators.post_dump(fn=None, pass_many=False, pass_original=False)[source]¶

Register a method to invoke after serializing an object. The method receives the serialized object and returns the processed object.

By default, receives a single object at a time, transparently handling the many argument passed to the Schema. If pass_many=True, the raw data (which may be a collection) and the value for many is passed.

If pass_original=True, the original data (before serializing) will be passed as an additional argument to the method.

marshmallow.decorators.post_load(fn=None, pass_many=False, pass_original=False)[source]¶

Register a method to invoke after deserializing an object. The method receives the deserialized data and returns the processed data.

By default, receives a single datum at a time, transparently handling the many argument passed to the Schema. If pass_many=True, the raw data (which may be a collection) and the value for many is passed.

If pass_original=True, the original data (before deserializing) will be passed as an additional argument to the method.

marshmallow.decorators.pre_dump(fn=None, pass_many=False)[source]¶

Register a method to invoke before serializing an object. The method receives the object to be serialized and returns the processed object.

By default, receives a single object at a time, regardless of whether many=True is passed to the Schema. If pass_many=True, the raw data (which may be a collection) and the value for many is passed.

marshmallow.decorators.pre_load(fn=None, pass_many=False)[source]¶

Register a method to invoke before deserializing an object. The method receives the data to be deserialized and returns the processed data.

By default, receives a single datum at a time, transparently handling the many argument passed to the Schema. If pass_many=True, the raw data (which may be a collection) and the value for many is passed.

marshmallow.decorators.set_hook(fn, key, **kwargs)[source]¶

Mark decorated function as a hook to be picked up later.

Note

Currently only works with functions and instance methods. Class and static methods are not supported.

Returns:	Decorated function if supplied, else this decorator with its args bound.

marshmallow.decorators.validates(field_name)[source]¶

Register a field validator.

Parameters:	field_name (str) – Name of the field that the method validates.

marshmallow.decorators.validates_schema(fn=None, pass_many=False, pass_original=False, skip_on_field_errors=True)[source]¶

Register a schema-level validator.

By default, receives a single object at a time, regardless of whether many=True is passed to the Schema. If pass_many=True, the raw data (which may be a collection) and the value for many is passed.

If pass_original=True, the original data (before unmarshalling) will be passed as an additional argument to the method.

If skip_on_field_errors=True, this validation method will be skipped whenever validation errors have been detected when validating fields.

Changed in version 3.0.0b1: skip_on_field_errors defaults to True.

Validators¶

Validation classes for various types of data.

class marshmallow.validate.ContainsOnly(choices, labels=None, error=None)[source]¶

Validator which succeeds if value is a sequence and each element in the sequence is also in the sequence passed as choices. Empty input is considered valid.

Parameters:	choices (iterable) – Same as `OneOf`. labels (iterable) – Same as `OneOf`. error (str) – Same as `OneOf`.

Changed in version 3.0.0b2: Duplicate values are considered valid.

Changed in version 3.0.0b2: Empty input is considered valid. Use validate.Length(min=1) to validate against empty inputs.

class marshmallow.validate.Email(error=None)[source]¶

Validate an email address.

Parameters:	error (str) – Error message to raise in case of a validation error. Can be interpolated with `{input}`.

class marshmallow.validate.Equal(comparable, error=None)[source]¶

Validator which succeeds if the value passed to it is equal to comparable.

Parameters:	comparable – The object to compare to. error (str) – Error message to raise in case of a validation error. Can be interpolated with `{input}` and `{other}`.

class marshmallow.validate.Length(min=None, max=None, error=None, equal=None)[source]¶

Validator which succeeds if the value passed to it has a length between a minimum and maximum. Uses len(), so it can work for strings, lists, or anything with length.

Parameters:

min (int) – The minimum length. If not provided, minimum length will not be checked.
max (int) – The maximum length. If not provided, maximum length will not be checked.
equal (int) – The exact length. If provided, maximum and minimum length will not be checked.
error (str) – Error message to raise in case of a validation error. Can be interpolated with {input}, {min} and {max}.

class marshmallow.validate.NoneOf(iterable, error=None)[source]¶

Validator which fails if value is a member of iterable.

Parameters:	iterable (iterable) – A sequence of invalid values. error (str) – Error message to raise in case of a validation error. Can be interpolated using `{input}` and `{values}`.

class marshmallow.validate.OneOf(choices, labels=None, error=None)[source]¶

Validator which succeeds if value is a member of choices.

Parameters:	choices (iterable) – A sequence of valid values. labels (iterable) – Optional sequence of labels to pair with the choices. error (str) – Error message to raise in case of a validation error. Can be interpolated with `{input}`, `{choices}` and `{labels}`.

options(valuegetter=<class 'str'>)[source]¶

Return a generator over the (value, label) pairs, where value is a string associated with each choice. This convenience method is useful to populate, for instance, a form select field.

Parameters:	valuegetter – Can be a callable or a string. In the former case, it must be a one-argument callable which returns the value of a choice. In the latter case, the string specifies the name of an attribute of the choice objects. Defaults to `str()` or `unicode()`.

class marshmallow.validate.Predicate(method, error=None, **kwargs)[source]¶

Call the specified method of the value object. The validator succeeds if the invoked method returns an object that evaluates to True in a Boolean context. Any additional keyword argument will be passed to the method.

Parameters:	method (str) – The name of the method to invoke. error (str) – Error message to raise in case of a validation error. Can be interpolated with `{input}` and `{method}`. kwargs – Additional keyword arguments to pass to the method.

class marshmallow.validate.Range(min=None, max=None, error=None)[source]¶

Validator which succeeds if the value it is passed is greater or equal to min and less than or equal to max. If min is not specified, or is specified as None, no lower bound exists. If max is not specified, or is specified as None, no upper bound exists.

Parameters:	min – The minimum value (lower bound). If not provided, minimum value will not be checked. max – The maximum value (upper bound). If not provided, maximum value will not be checked. error (str) – Error message to raise in case of a validation error. Can be interpolated with `{input}`, `{min}` and `{max}`.

class marshmallow.validate.Regexp(regex, flags=0, error=None)[source]¶

Validate value against the provided regex.

Parameters:	regex – The regular expression string to use. Can also be a compiled regular expression pattern. flags – The regexp flags to use, for example re.IGNORECASE. Ignored if `regex` is not a string. error (str) – Error message to raise in case of a validation error. Can be interpolated with `{input}` and `{regex}`.

class marshmallow.validate.URL(relative=False, error=None, schemes=None, require_tld=True)[source]¶

Validate a URL.

Parameters:	relative (bool) – Whether to allow relative URLs. error (str) – Error message to raise in case of a validation error. Can be interpolated with `{input}`. schemes (set) – Valid schemes. By default, `http`, `https`, `ftp`, and `ftps` are allowed. require_tld (bool) – Whether to reject non-FQDN hostnames

class marshmallow.validate.Validator[source]¶: Base abstract class for validators.

Note

This class does not provide any behavior. It is only used to add a useful __repr__ implementation for validators.

Utility Functions¶

Utility methods for marshmallow.

marshmallow.utils.callable_or_raise(obj)[source]¶: Check that an object is callable, else raise a ValueError.

marshmallow.utils.decimal_to_fixed(value, precision)[source]¶: Convert a Decimal to a fixed-precision number as a string.

marshmallow.utils.float_to_decimal(f)[source]¶: Convert a floating point number to a Decimal with no loss of information. See: http://docs.python.org/release/2.6.7/library/decimal.html#decimal-faq

marshmallow.utils.from_datestring(datestring)[source]¶: Parse an arbitrary datestring and return a datetime object using dateutils’ parser.

marshmallow.utils.from_iso_datetime(datestring, use_dateutil=True)[source]¶

Parse an ISO8601-formatted datetime string and return a datetime object.

Use dateutil’s parser if possible and return a timezone-aware datetime.

marshmallow.utils.from_iso_time(timestring, use_dateutil=True)[source]¶: Parse an ISO8601-formatted datetime string and return a datetime.time object.

marshmallow.utils.from_rfc(datestring, use_dateutil=True)[source]¶

Parse a RFC822-formatted datetime string and return a datetime object.

Use dateutil’s parser if possible.

https://stackoverflow.com/questions/885015/how-to-parse-a-rfc-2822-date-time-into-a-python-datetime

marshmallow.utils.get_func_args(func)[source]¶: Given a callable, return a tuple of argument names. Handles functools.partial objects and class-based callables.

Changed in version 3.0.0a1: Do not return bound arguments, eg. self.

marshmallow.utils.get_value(obj, key, default=<marshmallow.missing>)[source]¶: Helper for pulling a keyed value off various types of objects. Fields use this method by default to access attributes of the source object. For object x and attribute i, this method first tries to access x[i], and then falls back to x.i if an exception is raised.

Warning

If an object x does not raise an exception when x[i] does not exist, get_value will never check the value x.i. Consider overriding marshmallow.fields.Field.get_value in this case.

marshmallow.utils.is_collection(obj)[source]¶: Return True if obj is a collection type, e.g list, tuple, queryset.

marshmallow.utils.is_generator(obj)[source]¶: Return True if obj is a generator

marshmallow.utils.is_indexable_but_not_string(obj)[source]¶: Return True if obj is indexable but isn’t a string.

marshmallow.utils.is_instance_or_subclass(val, class_)[source]¶: Return True if val is either a subclass or instance of class_.

marshmallow.utils.is_iterable_but_not_string(obj)[source]¶: Return True if obj is an iterable object that isn’t a string.

marshmallow.utils.is_keyed_tuple(obj)[source]¶: Return True if obj has keyed tuple behavior, such as namedtuples or SQLAlchemy’s KeyedTuples.

marshmallow.utils.isoformat(dt, localtime=False, *args, **kwargs)[source]¶: Return the ISO8601-formatted UTC representation of a datetime object.

marshmallow.utils.local_rfcformat(dt)[source]¶: Return the RFC822-formatted representation of a timezone-aware datetime with the UTC offset.

marshmallow.utils.pluck(dictlist, key)[source]¶

Extracts a list of dictionary values from a list of dictionaries.

>>> dlist = [{'id': 1, 'name': 'foo'}, {'id': 2, 'name': 'bar'}]
>>> pluck(dlist, 'id')
[1, 2]

marshmallow.utils.pprint(obj, *args, **kwargs)[source]¶: Pretty-printing function that can pretty-print OrderedDicts like regular dictionaries. Useful for printing the output of marshmallow.Schema.dump().

marshmallow.utils.rfcformat(dt, localtime=False)[source]¶

Return the RFC822-formatted representation of a datetime object.

Parameters:	dt (datetime) – The datetime. localtime (bool) – If `True`, return the date relative to the local timezone instead of UTC, displaying the proper offset, e.g. “Sun, 10 Nov 2013 08:23:45 -0600”

marshmallow.utils.set_value(dct, key, value)[source]¶

Set a value in a dict. If key contains a ‘.’, it is assumed be a path (i.e. dot-delimited string) to the value’s location.

>>> d = {}
>>> set_value(d, 'foo.bar', 42)
>>> d
{'foo': {'bar': 42}}

marshmallow.utils.to_marshallable_type(obj, field_names=None)[source]¶: Helper for converting an object to a dictionary only if it is not dictionary already or an indexable object nor a simple type

Marshalling¶

Utility classes and values used for marshalling and unmarshalling objects to and from primitive types.

Warning

This module is treated as private API. Users should not need to use this module directly.

class marshmallow.marshalling.Marshaller(prefix='')[source]¶

Callable class responsible for serializing data and storing errors.

Parameters:	prefix (str) – Optional prefix that will be prepended to all the serialized field names.

serialize(obj, fields_dict, many=False, accessor=None, dict_class=<class 'dict'>, index_errors=True, index=None)[source]¶

Takes raw data (a dict, list, or other object) and a dict of fields to output and serializes the data based on those fields.

Parameters:

obj – The actual object(s) from which the fields are taken from
fields_dict (dict) – Mapping of field names to Field objects.
many (bool) – Set to True if data should be serialized as a collection.
accessor (callable) – Function to use for getting values from obj.
dict_class (type) – Dictionary class used to construct the output.
index_errors (bool) – Whether to store the index of invalid items in self.errors when many=True.
index (int) – Index of the item being serialized (for storing errors) if serializing a collection, otherwise None.

Returns:

A dictionary of the marshalled data

Changed in version 1.0.0: Renamed from marshal.

class marshmallow.marshalling.Unmarshaller[source]¶

Callable class responsible for deserializing data and storing errors.

New in version 1.0.0.

deserialize(data, fields_dict, many=False, partial=False, unknown='raise', dict_class=<class 'dict'>, index_errors=True, index=None)[source]¶

Deserialize data based on the schema defined by fields_dict.

Parameters:

data (dict) – The data to deserialize.
fields_dict (dict) – Mapping of field names to Field objects.
many (bool) – Set to True if data should be deserialized as a collection.
partial (bool|tuple) – Whether to ignore missing fields. If its value is an iterable, only missing fields listed in that iterable will be ignored.
unknown – Whether to exclude, include, or raise an error for unknown fields in the data. Use EXCLUDE, INCLUDE or RAISE.
dict_class (type) – Dictionary class used to construct the output.
index_errors (bool) – Whether to store the index of invalid items in self.errors when many=True.
index (int) – Index of the item being serialized (for storing errors) if serializing a collection, otherwise None.

Returns:

A dictionary of the deserialized data.

Class Registry¶

A registry of Schema classes. This allows for string lookup of schemas, which may be used with class:fields.Nested.

Warning

This module is treated as private API. Users should not need to use this module directly.

marshmallow.class_registry.get_class(classname, all=False)[source]¶

Retrieve a class from the registry.

Raises:	marshmallow.exceptions.RegistryError if the class cannot be found or if there are multiple entries for the given class name.

marshmallow.class_registry.register(classname, cls)[source]¶

Add a class to the registry of serializer classes. When a class is registered, an entry for both its classname and its full, module-qualified path are added to the registry.

Example:

class MyClass:
    pass

register('MyClass', MyClass)
# Registry:
# {
#   'MyClass': [path.to.MyClass],
#   'path.to.MyClass': [path.to.MyClass],
# }

Exceptions¶

Exception classes for marshmallow-related errors.

exception marshmallow.exceptions.MarshmallowError[source]¶: Base class for all marshmallow-related errors.

exception marshmallow.exceptions.RegistryError[source]¶: Raised when an invalid operation is performed on the serializer class registry.

exception marshmallow.exceptions.StringNotCollectionError[source]¶: Raised when a string is passed while a list of strings is expected.

exception marshmallow.exceptions.ValidationError(message, field_names=None, data=None, valid_data=None, **kwargs)[source]¶

Raised when validation fails on a field. Validators and custom fields should raise this exception.

Parameters:	message – An error message, list of error messages, or dict of error messages. field_names (list) – Field names to store the error on. If `None`, the error is stored in its default location. fields (list) – `Field` objects to which the error applies.

data = None¶: The raw input data.

field_names = None¶: List of field_names which failed validation.

messages = None¶: String, list, or dictionary of error messages. If a dict, the keys will be field names and the values will be lists of messages.

valid_data = None¶: The valid, (de)serialized data.

API Reference¶

Schema¶

Fields¶

Decorators¶

Validators¶

Utility Functions¶

Marshalling¶

Class Registry¶

Exceptions¶

Useful Links

Table Of Contents

Related Topics