DOCSP-46701-serialization

Author: mcmorisi

source/index.txt

@@ -24,6 +24,7 @@ MongoDB {+driver-short+} Documentation
    Data Formats </data-formats>
    Logging </logging>
    Monitoring </monitoring>
+   Serialization </serialization>
    Third-Party Tools </tools>
    FAQ </faq>
    Troubleshooting </troubleshooting>
@@ -100,6 +101,22 @@ Specialized Data Formats
 Learn how to work with specialized data formats and custom types in the
 :ref:`pymongo-data-formats` section.
 
+Logging
+-------
+
+Learn how to configure logging in the :ref:`pymongo-logging` section.
+
+Monitoring
+----------
+
+Learn how to monitor changes to your application in the :ref:`pymongo-monitoring` section.
+
+Serialization
+-------------
+
+Learn how {+driver-short+} serializes and deserializes data in the
+:ref:`pymongo-serialization` section.
+
 Third-Party Tools
 -----------------
 

source/serialization.txt

@@ -0,0 +1,99 @@
+.. _pymongo-serialization:
+
+=============
+Serialization
+=============
+
+.. facet::
+   :name: genre
+   :values: reference
+ 
+.. meta::
+   :keywords: class, map, deserialize
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to use {+driver-long+} to perform
+serialization.
+
+Serialization is the process of mapping a {+language+} object to a BSON
+document for storage in MongoDB. {+driver-short+} automatically converts basic {+language+}
+types into BSON when you insert them into a collection. Similarly, when you retrieve a
+document from a collection, {+driver-short+} automatically converts the returned BSON
+back into the corresponding {+language+} types.
+
+The following list shows some {+language+} types that {+driver-short+} can serialize
+and deserialize:
+
+- Strings (``str``)
+- Integers (``int``)
+- Floats (``float``)
+- Booleans (``bool``)
+- Datetimes (``datetime.datetime``)
+- Lists (``list``)
+- Dictionaries (``dict``)
+- None (``None``)
+
+For a complete list of {+language+}-to-BSON mappings, see the `bson {+api-root+}bson/index.html`__
+API documentation.
+
+.. note:
+
+   Because the key-value pairs in {+language+} dictionaries are unordered, the order of
+   fields in serialized BSON documents can differ from the order of fields in the original
+   dictionary. To preserve the order of keys when serializing and deserializing BSON,
+   use the `SON <{+api-root+}bson/son.html>`__ class.
+
+Custom Classes
+--------------
+
+To serialize and deserialize custom {+language+} 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, then inserts the
+serialized object into a collection:
+
+.. code-block:: python
+
+   class Restaurant:
+       def __init__(self, name, cuisine):
+           self.name = name
+           self.cuisine = cuisine
+
+   restaurant = Guitar("Example Cafe", "Coffee")
+   restaurant_dict = vars(restaurant)
+
+   collection.insert_one(restaurant_dict)
+
+To learn more about inserting documents into a collection, see the :ref:`pymongo-write-insert`
+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, then converts
+it back into a ``Restaurant`` object from the preceding example:
+
+.. code-block:: python
+
+   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 :ref:`pymongo-retrieve`
+guide.