Table of Contents
Introduction to Python Marshmallow
Python marshmallow is an object-relational mapping library that is used to convert objects to and from Python data types. It is often used alongside SQLAlchemy, an ORM that maps database schemas to Python objects. Marshmallow is often used to deserialize Python dicts to SQLAlchemy models and vice versa. In this tutorial, we will learn about the Python marshmallow library in detail.
We will learn about marshmallow schema, form validation, and marshmallow meta through various examples. Moreover, we will learn how we create a schema, serializing and deserializing objects by solving different examples. In a nutshell, this tutorial will contain all the necessary sections and examples that you need to know in order to start working with the Python marshmallow library.
Getting started with Python Marshmallow
As we already discussed that the Python marshmallow library is used to convert different data types to Python objects. Before using this library, make sure that you have installed the library on your system because this is not a Python built-in module. We can install this library using the pip command as shown below:
pip install marshmallow
Once we have successfully installed the library, we can check the version of the library that has been installed on our system by using __version__. See the example below:
# importing Python marshmallow library
import marshmallow
# printing the version
print('marshmallow ',marshmallow.__version__)Output:
marshmallow 3.14.1
In my case, the version of the marshmallow library is 3.14.1. You can have the updated version if you are installing this library after some time. Now let us explore this module in more detail.
Python marshmallow and schema
The main component of Marshmallow is a Schema. A schema defines the rules that guide deserialization, called a load, and serialization called dump. Python serialization is the act of converting a Python object into a byte stream and deserialization is the process of decoding the data that is in JSON format into a native data type. we will import the schema from the marshmallow library using from and import keywords as shown below:
from marshmallow import schema
The benefit of using from keyword is that it will only import that specific component of the module rather than the whole module.
Example-1 Creating schema using Python marshmallow
Now let us see how we can create a schema using Python marshmallow. For that, we have to first, import schema and fields from the marshmallow library. See the Python program below:
# importing schema and fields from Python marshmallow
from marshmallow import Schema, fields
# creating python class
class CreatingSchema(Schema):
# first name as required input
firstName = fields.Str(required = True)
# last name and age as not required inputs
lastName = fields.Str()
email = fields.Email()This is the schema that we have created in a python programming language. We have made some variables mandatory by specifying the required argument to be True. This program will run without any error if you have installed the libraries correctly.
Another very simple way to create a schema is using dictionary. See the python example below:
CreatingSchema = Schema.from_dict(
{"firstname": fields.Str(), "lastname": fields.Str(), "email" : fields.Email()}
)
This is another way to create the schema in Python using a dictionary.
Example-2 Deserializing Object in Python marshmallow
Now let us deserialize the program that is given above. As we already discussed that deserializing is also known as load in Python. See the following example of deserializing python objects.
# importing schema and fields from Python marshmallow
from marshmallow import Schema, fields
# creating python class
class CreatingSchema(Schema):
# first name as required input
firstName = fields.Str(required = True)
# last name and age as not required inputs
lastName = fields.Str()
email = fields.Email()
# creating information
info = {
'first_name' : 'Bashir',
'last_name' : 'Alam',
'email' : 'baashir@gmail.com'
}
# deserializing in Python
user_info = CreatingSchema().load(info)Notice that we have called the method toward the end of the given program which is deserializing the python program.
Example-3 Serializing the object in Python marshmallow
Serializing is very much similar to deserializing. All we need to do is to replace the load method with the dump method. See the Python program below:
# importing schema and fields from Python marshmallow
from marshmallow import Schema, fields
# creating python class
class CreatingSchema(Schema):
# first name as required input
firstName = fields.Str(required = True)
# last name and age as not required inputs
lastName = fields.Str()
email = fields.Email()
# creating information
info = {
'first_name' : 'Bashir',
'last_name' : 'Alam',
'email' : 'baashir@gmail.com'
}
# serializing in Python
user_info = CreatingSchema().dump(info)Notice we have used the dump method this time, which is serializing the object.
Python marshmallow and fields validation
In the above sections, we have seen that each schema contains fields that define the fields to load or dump. Fields are defined using the fields module. The are many data types that define the field. Some of which are listed below:
MappingDictListTuple,String,Integer,Decimal,Boolean,Time,Str,Bool,Int,
Where Str, Bool, and Int are aliases for Strings, booleans, and integers respectively. We have seen in the examples above that we define fields by specifying their types. For example, as shown below:
email = fields.Email()
So here, Email is the type of the fields that we have specified. Another important thing about these fields is that they can take optional arguments as well which are listed below:
default: value used in serialization when the value is missing.missing: value used in deserialization when value is missing.data_key: used when the field name differs.validate: used for a validator.required: specify whether the field is required in the deserialization.allow_none: specify whether None is a valid value during deserialization. It defaults to True when missing is set to None else False.load_only: if True it will skip the field during serialization.dump_only: if True it will skip the field at deserialization.error_messages: a dictionary allowing to override the error message on error.
Now see one more example of a schema below which takes some of the above values.
class CreatingSchema(Schema):
firstName = fields.Str(required = True)
lastName = fields.Str(data_key = 'lname')
email = fields.Email()The schema shown above contains three fields, one with required and one with data key value(having a different key on the raw data).
Syntax of Field validation in Python marshmallow
Another important part of the fields is the validation. It can be specified through the validate argument, taking a single value or an array of validations. The following is the simple syntax of python field validation.
# importing schema and fields from Python marshmallow
from marshmallow import Schema, fields, validate
class CreatingSchema(Schema):
firstname = fields.Str(validate=validate.Length(min=1))One thing to notice here is that validation only occurs at deserialization and not at serialization. If the validation fails, then a validation error is thrown by the program. The default validators supported are given in the following list.
ContainsOnly: validates that the value is a subset of the values from the validation,Email: validates that the value is an email,Equal: validates by comparing the value with the validation value,Length: validates the length of the value usinglen(),NoneOf: validates that the value is a sequence and that it is mutually exclusive from the validation value,OneOf: validates that the value is one of the values from the validation,Predicate: validates by calling the method specified in the value of the validation,Range: validates against a range,Regexp: validates with a regular expression,URL: validates that the value is a URL.
Passing our own validation
It is also possible to pass our own validation function directly in validate. See the following Python program where we have added our own validation.
# # importing schema and fields from Python marshmallow
from marshmallow import Schema, fields, ValidationError
# creating python class
class CreatingSchema(Schema):
# first name as required input
firstName = fields.Str(required = True)
# last name and age as not required inputs
lastName = fields.Str()
email = fields.Email()
# try block to catach error
try:
result = CreatingSchema().load({"name": "John", "email": "foo"})
# except block
except ValidationError as err:
# print the error
print(err.messages) Output:
{'firstName': ['Missing data for required field.'], 'email': ['Not a valid email address.'], 'name': ['Unknown field.']}
Notice that there was an error in the try block that is why the except block was executed.
Python marshmallow and the meta class
So far we have seen how configuration could be set at schema creation or on the fields themselves. In order to share the application of configuration, like omitting a password field, Marshmallow provides a Meta class. The following are different options that are available in this class.
fields: list of fields to include in the serialized result, can be used to remove the need to explicitly define each field.additional: list of fields to include in addition to the explicitly defined fields.exlude: list of fields to exclude from the schema, will throwunknown fieldvalidation error at deserialization and will omit at serialization.dateformatanddatetimeformat: defines the format of the date and the DateTime.ordered: preserve the order of the schema definition.load_only: specify fields to exclude during serialization, similar to schema args.dump_only: specify fields to exclude during deserialization, similar to schema args.unknown: the behavior to take on unknown fields (EXCLUDE,INCLUDE,RAISE).
Usually, the metaclass is used to handle errors that encounter a key with no matching <span class="pre">Field</span> in the schema while during the execution of the load method.
Summary
The Python marshmallow is a library that is used to convert Python objects to and from data types. In this tutorial, we learned about the Python marshmallow library in detail. We learned how we can create a schema, serialize and deserialize objects by taking various examples. At the same time, we also covered the field validation and the options of meta class as well. In a nutshell, this tutorial contains all the necessary details that you need to know in order to start working with the Python marshmallow library.
Further Reading
Python marshmallow documentation
Why marshmallow?
Python try and except
