Serialization

On this page

Overview
Custom Classes
Serializing Custom Classes
Deserializing Custom Classes
Binary Data

Overview

In this guide, you can learn how to use PyMongo to perform serialization.

Serialization is the process of mapping a Python object to a BSON document for storage in MongoDB. PyMongo automatically converts basic Python types into BSON when you insert a document into a collection. Similarly, when you retrieve a document from a collection, PyMongo automatically converts the returned BSON back into the corresponding Python types.

You can use PyMongo to serialize and deserialize the following Python types:

str
int
float
bool
datetime.datetime
list
dict
None

For a complete list of Python-to-BSON mappings, see the bson API documentation.

Custom Classes

To serialize and deserialize custom Python classes, you must implement custom logic to handle the conversion. The following sections show how to serialize and deserialize custom classes.

Serializing Custom Classes

To serialize a custom class, you must convert the class to a dictionary. The following example serializes a custom class by using the vars() method, and then inserts the serialized object into a collection:

class Restaurant:
    def __init__(self, name, cuisine):
        self.name = name
        self.cuisine = cuisine
restaurant = Restaurant("Example Cafe", "Coffee")
restaurant_dict = vars(restaurant)
collection.insert_one(restaurant_dict)

The preceding example serializes the Restaurant object into the following dictionary:

{'name': 'Example Cafe', 'cuisine': 'Coffee'}

To learn more about inserting documents into a collection, see the Insert Documents guide.

Deserializing Custom Classes

To deserialize a custom class, you must convert the dictionary back into an instance of the class. The following example retrieves a document from a collection, and then converts it back into a Restaurant object from the preceding example:

def deserialize_restaurant(doc):
    return Restaurant(name=doc["name"], cuisine=doc["cuisine"])
restaurant_doc = collection.find_one({"name": "Example Cafe"})
restaurant = deserialize_restaurant(restaurant_doc)

To learn more about retrieving documents from a collection, see the Retrieve Data guide.

Binary Data

In all versions of Python, PyMongo encodes instances of the bytes class as binary data with subtype 0, the default subtype for binary data. In Python 3, PyMongo decodes these values to instances of the bytes class. In Python 2, the driver decodes them to instances of the Binary class with subtype 0.

The following code examples show how PyMongo decodes instances of the bytes class. Select the Python 2 or Python 3 tab to view the corresponding code.

from pymongo import MongoClient
client = MongoClient()
client.test.test.insert_one({'binary': b'this is a byte string'})
doc = client.test.test.find_one()
print(doc)

{u'_id': ObjectId('67afb78298f604a28f0247b4'), u'binary': Binary('this is a byte string', 0)}

from pymongo import MongoClient
client = MongoClient()
client.test.test.insert_one({'binary': b'this is a byte string'})
doc = client.test.test.find_one()
print(doc)

{'_id': ObjectId('67afb78298f604a28f0247b4'), 'binary': b'this is a byte string'}

Back

Monitoring

Third-Party Tools