# API Reference

## Schema

class `marshmallow.``Schema`(only=(), exclude=(), prefix='', strict=None, many=False, context=None, load_only=(), dump_only=(), partial=False)

  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) – A list or tuple of fields to serialize. If `None`, all fields will be serialized. Nested fields can be represented with dot delimiters.
  - exclude (tuple) – A list or tuple of fields to exclude from the serialized result. Nested fields can be represented with dot delimiters.
  - prefix (str) – Optional prefix that will be prepended to all the serialized field names.
  - strict (bool) – If `True`, raise errors if invalid data are passed in instead of failing silently and storing the errors.
  - 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) – A list or tuple of fields to skip during serialization
  - dump_only (tuple) – A list or tuple of 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.

  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.
    - `strict`: If `True`, raise errors during marshalling rather than
        storing them.
    - `render_module`: Module to use for `loads` and `dumps`. Defaults to
        `json` from the standard library. Defaults to the `json` module in the stdlib.
    - `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
  `OPTIONS_CLASS`

    alias of `SchemaOpts`

  `dump`(obj, many=None, update_fields=True, **kwargs)

    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 tuple of the form (`data`, `errors`)
    Return type: | `MarshalResult`, a `collections.namedtuple`

    New in version 1.0.0.

  `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 tuple of the form (`data`, `errors`)
    Return type: | `MarshalResult`, a `collections.namedtuple`

    New in version 1.0.0.

  `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)

    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.

    Returns: | A tuple of the form (`data`, `errors`)
    Return type: | `UnmarshalResult`, a `collections.namedtuple`

    New in version 1.0.0.

  `loads`(json_data, many=None, *args, **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.

    Returns: | A tuple of the form (`data`, `errors`)
    Return type: | `UnmarshalResult`, a `collections.namedtuple`

    New in version 1.0.0.

  `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)

  class Meta options for the `Schema`. Defines defaults.

class `marshmallow.``MarshalResult`(data, errors)

  Return type of `Schema.dump()` including serialized data and errors

class `marshmallow.``UnmarshalResult`(data, errors)

  Return type of `Schema.load()`, including deserialized data and errors

`marshmallow.``pprint`(obj, *args, **kwargs)

  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, load_from=None, dump_to=None, error=None, validate=None, required=False, allow_none=None, load_only=False, dump_only=False, missing=<marshmallow.missing>, error_messages=None, **metadata)

  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. If `None`, assumes the attribute has the same name as the field.
  - load_from (str) – Additional key to look for when deserializing. Will only be checked if the field’s name is not found on the input dictionary. If checked, it will return this parameter on error.
  - dump_to (str) – Field name to use as a key when serializing.
  - 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.

  `_add_to_schema`(field_name, schema)
    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)

    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)

    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)

    Perform validation on `value`. Raise a `ValidationError` if validation does not succeed.

  `_validate_missing`(value)

    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.', 'type': 'Invalid input type.', '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)

    Deserialize `value`.

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

  `fail`(key, **kwargs)

    A helper method that simply raises a `ValidationError`.

  `get_value`(obj, attr, accessor=None, default=<marshmallow.missing>)

    Return the value for a given key from an object.

  `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)

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

    Parameters:

    - attr (str) – The attibute 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, load_from=None, dump_to=None, error=None, validate=None, required=False, allow_none=None, load_only=False, dump_only=False, missing=<marshmallow.missing>, error_messages=None, **metadata)

  Field that applies no formatting or validation.

class `marshmallow.fields.``Nested`(nested, default=<marshmallow.missing>, exclude=(), only=None, **kwargs)

  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.
  - default – Default value to if attribute is missing or None
  - exclude (tuple) – A list or tuple of fields to exclude.
  - required – Raise an `ValidationError` during deserialization if the field, and any required field values specified in the `nested` schema, are not found in the data. If not a `bool` (e.g. a `str`), the provided value will be used as the message of the `ValidationError` instead of the default message.
  - 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.
  - kwargs – The same keyword arguments that `Field` receives.

  `_validate_missing`(value)

    Validate missing values. Raise a `ValidationError` if `value` should be considered missing.

  `schema`

    The nested Schema object.

    Changed in version 1.0.0: Renamed from `serializer` to `schema`

class `marshmallow.fields.``Dict`(default=<marshmallow.missing>, attribute=None, load_from=None, dump_to=None, error=None, validate=None, required=False, allow_none=None, load_only=False, dump_only=False, missing=<marshmallow.missing>, error_messages=None, **metadata)

  A dict field. Supports dicts and dict-like objects.

  Note

  This field is only appropriate when the structure of nested data is not known. For structured data, use `Nested`.

  New in version 2.1.0.

class `marshmallow.fields.``List`(cls_or_instance, **kwargs)

  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.

  `get_value`(obj, attr, accessor=None)

    Return the value for a given key from an object.

class `marshmallow.fields.``String`(default=<marshmallow.missing>, attribute=None, load_from=None, dump_to=None, error=None, validate=None, required=False, allow_none=None, load_only=False, dump_only=False, missing=<marshmallow.missing>, error_messages=None, **metadata)

  A string field.

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

class `marshmallow.fields.``UUID`(default=<marshmallow.missing>, attribute=None, load_from=None, dump_to=None, error=None, validate=None, required=False, allow_none=None, load_only=False, dump_only=False, missing=<marshmallow.missing>, error_messages=None, **metadata)

  A UUID field.

  `_validated`(value)

    Format the value or raise a `ValidationError` if an error occurs.

class `marshmallow.fields.``Number`(as_string=False, **kwargs)

  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.

  `_format_num`(value)

    Return the number value for value, given this field’s `num_type`.

  `_validated`(value)

    Format the value or raise a `ValidationError` if an error occurs.

  `num_type`

    alias of `float`

  `serialize`(attr, obj, accessor=None)

    Pulls the value for the given key from the object and returns the serialized number representation. Return a string if `self.as_string=True`, othewise return this field’s `num_type`. Receives the same `args` and `kwargs` as `Field`.

class `marshmallow.fields.``Integer`(strict=False, **kwargs)

  An integer field.

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

  `num_type`

    alias of `int`

class `marshmallow.fields.``Decimal`(places=None, rounding=None, allow_nan=False, as_string=False, **kwargs)

  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.

  `num_type`

    alias of `Decimal`

class `marshmallow.fields.``Boolean`(truthy=None, falsy=None, **kwargs)

  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.

  `falsy` = {0, 'OFF', 'f', '0', 'False', 'FALSE', 'Off', 'false', 'off', 'F'}

    Default falsy values.

  `truthy` = {'on', 'true', 1, 'T', 'ON', 'On', 't', '1', 'True', 'TRUE'}

    Default truthy values.

class `marshmallow.fields.``FormattedString`(src_str, *args, **kwargs)

  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'}

class `marshmallow.fields.``Float`(as_string=False, **kwargs)

  A double as IEEE-754 double precision string.

  Parameters:

  - as_string (bool) – If True, format the value as a string.
  - kwargs – The same keyword arguments that `Number` receives.

  `num_type`

    alias of `float`

class `marshmallow.fields.``DateTime`(format=None, **kwargs)

  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.

class `marshmallow.fields.``LocalDateTime`(format=None, **kwargs)

  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, load_from=None, dump_to=None, error=None, validate=None, required=False, allow_none=None, load_only=False, dump_only=False, missing=<marshmallow.missing>, error_messages=None, **metadata)

  ISO8601-formatted time string.

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

  `_deserialize`(value, attr, data)

    Deserialize an ISO8601-formatted time to a `datetime.time` object.

class `marshmallow.fields.``Date`(default=<marshmallow.missing>, attribute=None, load_from=None, dump_to=None, error=None, validate=None, required=False, allow_none=None, load_only=False, dump_only=False, missing=<marshmallow.missing>, error_messages=None, **metadata)

  ISO8601-formatted date string.

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

  `_deserialize`(value, attr, data)

    Deserialize an ISO8601-formatted date string to a `datetime.date` object.

class `marshmallow.fields.``TimeDelta`(precision='seconds', error=None, **kwargs)

  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’ or ‘microseconds’.
  - 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.

class `marshmallow.fields.``Url`(relative=False, schemes=None, **kwargs)

  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 `Url`

class `marshmallow.fields.``Email`(*args, **kwargs)

  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)

  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.

class `marshmallow.fields.``Function`(serialize=None, deserialize=None, func=None, **kwargs)

  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.0: Removed `func` parameter.

`marshmallow.fields.``Str`

  alias of `String`

`marshmallow.fields.``Bool`

  alias of `Boolean`

`marshmallow.fields.``Int`

  alias of `Integer`

class `marshmallow.fields.``Constant`(constant, **kwargs)

  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.

## 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)

  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.

`marshmallow.decorators.``post_load`(fn=None, pass_many=False, pass_original=False)

  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.

`marshmallow.decorators.``pre_dump`(fn=None, pass_many=False)

  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)

  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.``tag_processor`(tag_name, fn, pass_many, **kwargs)

  Tags decorated processor function to be picked up later.

  Note

  Currently ony 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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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'>)

    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)

  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)

  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)

  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)

  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.

class `marshmallow.validate.``Validator`

  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)

  Check that an object is callable, else raise a `ValueError`.

`marshmallow.utils.``decimal_to_fixed`(value, precision)

  Convert a `Decimal` to a fixed-precision number as a string.

`marshmallow.utils.``float_to_decimal`(f)

  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)

  Parse an arbitrary datestring and return a datetime object using dateutils’ parser.

`marshmallow.utils.``from_iso`(datestring, use_dateutil=True)

  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)

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

`marshmallow.utils.``from_rfc`(datestring, use_dateutil=True)

  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)

  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>)

  Helper for pulling a keyed value off various types of objects

`marshmallow.utils.``is_collection`(obj)

  Return True if `obj` is a collection type, e.g list, tuple, queryset.

`marshmallow.utils.``is_generator`(obj)

  Return True if `obj` is a generator

`marshmallow.utils.``is_indexable_but_not_string`(obj)

  Return True if `obj` is indexable but isn’t a string.

`marshmallow.utils.``is_instance_or_subclass`(val, class_)

  Return True if `val` is either a subclass or instance of `class_`.

`marshmallow.utils.``is_iterable_but_not_string`(obj)

  Return True if `obj` is an iterable object that isn’t a string.

`marshmallow.utils.``is_keyed_tuple`(obj)

  Return True if `obj` has keyed tuple behavior, such as namedtuples or SQLAlchemy’s KeyedTuples.

`marshmallow.utils.``isoformat`(dt, localtime=False, *args, **kwargs)

  Return the ISO8601-formatted UTC representation of a datetime object.

`marshmallow.utils.``local_rfcformat`(dt)

  Return the RFC822-formatted representation of a timezone-aware datetime with the UTC offset.

`marshmallow.utils.``pluck`(dictlist, key)

  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)

  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)

  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)

  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)

  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='')

  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)

    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`

  Callable class responsible for deserializing data and storing errors.

  New in version 1.0.0.

  `deserialize`(data, fields_dict, many=False, partial=False, dict_class=<class 'dict'>, index_errors=True, index=None)

    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.
    - 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)

  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)

  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`

  Base class for all marshmallow-related errors.

exception `marshmallow.exceptions.``RegistryError`

  Raised when an invalid operation is performed on the serializer class registry.

exception `marshmallow.exceptions.``ValidationError`(message, field_names=None, fields=None, data=None, valid_data=None, **kwargs)

  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.

  `fields` = None

    List of field objects 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.