Top-level API¶
Classes:
Base schema class with which to define schemas. |
|
Defines defaults for |
Exceptions:
Raised when validation fails on a field or schema. |
Functions:
Register a method to invoke after serializing an object. |
|
Register a method to invoke after deserializing an object. |
|
Register a method to invoke before serializing an object. |
|
Register a method to invoke before deserializing an object. |
|
Register a field validator. |
|
Register a schema-level validator. |
- class marshmallow.Schema(*, only=None, exclude=(), many=None, load_only=(), dump_only=(), partial=None, unknown=None)[source]¶
Base schema class with which to define schemas.
Example usage:
import datetime as dt from dataclasses import dataclass from marshmallow import Schema, fields @dataclass class Album: title: str release_date: dt.date class AlbumSchema(Schema): title = fields.Str() release_date = fields.Date() album = Album("Beggars Banquet", dt.date(1968, 12, 6)) schema = AlbumSchema() data = schema.dump(album) data # {'release_date': '1968-12-06', 'title': 'Beggars Banquet'}
- Parameters:
only (types.StrSequenceOrSet | None) – 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 (types.StrSequenceOrSet) – Blacklist of the declared fields to exclude when instantiating the Schema. If a field appears in both
only
andexclude
, it is not used. Nested fields can be represented with dot delimiters.many (bool | None) – Should be set to
True
ifobj
is a collection so that the object will be serialized to a list.load_only (types.StrSequenceOrSet) – Fields to skip during serialization (write-only fields)
dump_only (types.StrSequenceOrSet) – Fields to skip during deserialization (read-only fields)
partial (bool | types.StrSequenceOrSet | None) – Whether to ignore missing fields and not require any fields declared. Propagates down to
Nested
fields as well. If its value is an iterable, only missing fields listed in that iterable will be ignored. Use dot delimiters to specify nested fields.unknown (types.UnknownOption | None) – Whether to exclude, include, or raise an error for unknown fields in the data. Use
EXCLUDE
,INCLUDE
orRAISE
.
Changed in version 3.0.0: Remove
prefix
parameter.Changed in version 4.0.0: Remove
context
parameter.- class Meta[source]¶
Options object for a Schema.
Example usage:
from marshmallow import Schema class MySchema(Schema): class Meta: fields = ("id", "email", "date_created") exclude = ("password", "secret_attribute")
A note on type checking
Type checkers will only check the attributes of the
Meta
class if you explicitly subclassmarshmallow.Schema.Meta
.from marshmallow import Schema class MySchema(Schema): # Not checked by type checkers class Meta: additional = True class MySchema2(Schema): # Type checkers will check attributes class Meta(Schema.Opts): additional = True # Incompatible types in assignment
Removed in version 3.0.0b7: Remove
strict
.Added in version 3.0.0b12: Add
unknown
.Changed in version 3.0.0b17: Rename
dateformat
todatetimeformat
.Added in version 3.9.0: Add
timeformat
.Changed in version 3.26.0: Deprecate
ordered
. Field order is preserved by default.Removed in version 4.0.0: Remove
ordered
.- additional: ClassVar[tuple[str, ...] | list[str]]¶
Fields to include in addition to the explicitly declared fields.
additional
andfields
are mutually-exclusive options.
- exclude: ClassVar[tuple[str, ...] | list[str]]¶
Fields to exclude in the serialized result. Nested fields can be represented with dot delimiters.
- include: ClassVar[dict[str, Field]]¶
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.
- index_errors: ClassVar[bool]¶
If
True
, errors dictionaries will include the index of invalid items in a collection.
- dump(obj, *, many=None)[source]¶
Serialize an object to native Python data types according to this Schema’s fields.
- Parameters:
- Returns:
Serialized data
Changed in version 3.0.0b7: This method returns the serialized data rather than a
(data, errors)
duple. AValidationError
is raised ifobj
is invalid.Changed in version 3.0.0rc9: Validation no longer occurs upon serialization.
- dumps(obj, *args, many=None, **kwargs)[source]¶
Same as
dump()
, except return a JSON-encoded string.- Parameters:
- Returns:
A
json
string
Changed in version 3.0.0b7: This method returns the serialized data rather than a
(data, errors)
duple. AValidationError
is raised ifobj
is invalid.
- classmethod from_dict(fields, *, name='GeneratedSchema')[source]¶
Generate a
Schema
class given a dictionary of fields.from marshmallow import Schema, fields PersonSchema = Schema.from_dict({"name": fields.Str()}) print(PersonSchema().load({"name": "David"})) # => {'name': 'David'}
Generated schemas are not added to the class registry and therefore cannot be referred to by name in
Nested
fields.- Parameters:
- Return type:
Added in version 3.0.0.
- get_attribute(obj, attr, default)[source]¶
Defines how to pull values from an object to serialize.
Changed in version 3.0.0a1: Changed position of
obj
andattr
.
- handle_error(error, data, *, many, **kwargs)[source]¶
Custom error handler function for the schema.
- Parameters:
error (ValidationError) – The
ValidationError
raised during (de)serialization.data (Any) – The original input data.
many (bool) – Value of
many
on dump or load.partial – Value of
partial
on load.
Changed in version 3.0.0rc9: Receives
many
andpartial
(on deserialization) as keyword arguments.
- load(data, *, many=None, partial=None, unknown=None)[source]¶
Deserialize a data structure to an object defined by this Schema’s fields.
- Parameters:
data (Mapping[str, Any] | Sequence[Mapping[str, Any]]) – The data to deserialize.
many (bool | None) – Whether to deserialize
data
as a collection. IfNone
, the value forself.many
is used.partial (bool | Sequence[str] | AbstractSet[str] | None) – Whether to ignore missing fields and not require any fields declared. Propagates down to
Nested
fields as well. If its value is an iterable, only missing fields listed in that iterable will be ignored. Use dot delimiters to specify nested fields.unknown (Literal['exclude', 'include', 'raise'] | None) – Whether to exclude, include, or raise an error for unknown fields in the data. Use
EXCLUDE
,INCLUDE
orRAISE
. IfNone
, the value forself.unknown
is used.
- Returns:
Deserialized data
Changed in version 3.0.0b7: This method returns the deserialized data rather than a
(data, errors)
duple. AValidationError
is raised if invalid data are passed.
- loads(s, /, *, many=None, partial=None, unknown=None, **kwargs)[source]¶
Same as
load()
, except it usesmarshmallow.Schema.Meta.render_module
to deserialize the passed string before passing data toload()
.- Parameters:
s (str | bytes | bytearray) – A string of the data to deserialize.
many (bool | None) – Whether to deserialize
obj
as a collection. IfNone
, the value forself.many
is used.partial (bool | Sequence[str] | AbstractSet[str] | None) – Whether to ignore missing fields and not require any fields declared. Propagates down to
Nested
fields as well. If its value is an iterable, only missing fields listed in that iterable will be ignored. Use dot delimiters to specify nested fields.unknown (Literal['exclude', 'include', 'raise'] | None) – Whether to exclude, include, or raise an error for unknown fields in the data. Use
EXCLUDE
,INCLUDE
orRAISE
. IfNone
, the value forself.unknown
is used.
- Returns:
Deserialized data
Changed in version 3.0.0b7: This method returns the deserialized data rather than a
(data, errors)
duple. AValidationError
is raised if invalid data are passed.Changed in version 4.0.0: Rename
json_module
parameter tos
.
- on_bind_field(field_name, field_obj)[source]¶
Hook to modify a field when it is bound to the
Schema
.No-op by default.
- set_class¶
alias of
OrderedSet
- validate(data, *, many=None, partial=None)[source]¶
Validate
data
against the schema, returning a dictionary of validation errors.- Parameters:
data (Mapping[str, Any] | Sequence[Mapping[str, Any]]) – The data to validate.
many (bool | None) – Whether to validate
data
as a collection. IfNone
, the value forself.many
is used.partial (bool | Sequence[str] | AbstractSet[str] | None) – Whether to ignore missing fields and not require any fields declared. Propagates down to
Nested
fields as well. If its value is an iterable, only missing fields listed in that iterable will be ignored. Use dot delimiters to specify nested fields.
- Returns:
A dictionary of validation errors.
- Return type:
- class marshmallow.SchemaOpts(meta)[source]¶
Defines defaults for
marshmallow.Schema.Meta
.- Parameters:
meta (type)
- exception marshmallow.ValidationError(message, field_name='_schema', data=None, valid_data=None, **kwargs)[source]¶
Raised when validation fails on a field or schema.
Validators and custom fields should raise this exception.
- Parameters:
message (str | list | dict) – An error message, list of error messages, or dict of error messages. If a dict, the keys are subitems and the values are error messages.
field_name (str) – Field name to store the error on. If
None
, the error is stored as schema-level error.data (Mapping[str, Any] | Iterable[Mapping[str, Any]] | None) – Raw input data.
valid_data (list[Any] | dict[str, Any] | None) – Valid (de)serialized data.
- marshmallow.post_dump(fn=None, *, pass_collection=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 it receives a single object at a time, transparently handling the
many
argument passed to theSchema
’sdump()
call. Ifpass_collection=True
, the raw data (which may be a collection) is passed.If
pass_original=True
, the original data (before serializing) will be passed as an additional argument to the method.Changed in version 3.0.0:
many
is always passed as a keyword arguments to the decorated method.Changed in version 4.0.0:
pass_many
is renamed topass_collection
.Changed in version 4.0.0:
pass_collection
andpass_original
are keyword-only arguments.
- marshmallow.post_load(fn=None, *, pass_collection=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 it receives a single object at a time, transparently handling the
many
argument passed to theSchema
’sload()
call. Ifpass_collection=True
, the raw data (which may be a collection) is passed.If
pass_original=True
, the original data (before deserializing) will be passed as an additional argument to the method.Changed in version 3.0.0:
partial
andmany
are always passed as keyword arguments to the decorated method.Changed in version 4.0.0:
pass_many
is renamed topass_collection
.Changed in version 4.0.0:
pass_collection
andpass_original
are keyword-only arguments.Changed in version 4.0.0:
unknown
is passed as a keyword argument to the decorated method.
- marshmallow.pre_dump(fn=None, *, pass_collection=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 it receives a single object at a time, transparently handling the
many
argument passed to theSchema
’sdump()
call. Ifpass_collection=True
, the raw data (which may be a collection) is passed.Changed in version 3.0.0:
many
is always passed as a keyword arguments to the decorated method.Changed in version 4.0.0:
pass_many
is renamed topass_collection
.Changed in version 4.0.0:
pass_collection
is a keyword-only argument.
- marshmallow.pre_load(fn=None, *, pass_collection=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 it receives a single object at a time, transparently handling the
many
argument passed to theSchema
’sload()
call. Ifpass_collection=True
, the raw data (which may be a collection) is passed.Changed in version 3.0.0:
partial
andmany
are always passed as keyword arguments to the decorated method.Changed in version 4.0.0:
pass_many
is renamed topass_collection
.Changed in version 4.0.0:
pass_collection
is a keyword-only argument.Changed in version 4.0.0:
unknown
is passed as a keyword argument to the decorated method.
- marshmallow.validates_schema(fn=None, *, pass_collection=False, pass_original=False, skip_on_field_errors=True)[source]¶
Register a schema-level validator.
By default it receives a single object at a time, transparently handling the
many
argument passed to theSchema
’svalidate()
call. Ifpass_collection=True
, the raw data (which may be a collection) 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 toTrue
.Changed in version 3.0.0:
partial
andmany
are always passed as keyword arguments to the decorated method.Changed in version 4.0.0:
unknown
is passed as a keyword argument to the decorated method.Changed in version 4.0.0:
pass_many
is renamed topass_collection
.Changed in version 4.0.0:
pass_collection
,pass_original
, andskip_on_field_errors
are keyword-only arguments.
- marshmallow.missing¶
Singleton value that indicates that a field’s value is missing from input dict passed to
Schema.load
. If the field’s value is not required, itsdefault
value is used.
Constants for unknown
¶
See also
- marshmallow.EXCLUDE¶
Indicates that fields that are not explicitly declared on a schema should be excluded from the deserialized result.
- marshmallow.INCLUDE¶
Indicates that fields that are not explicitly declared on a schema should be included from the deserialized result.
- marshmallow.RAISE¶
Indicates that fields that are not explicitly declared on a schema should result in an error.