DOCSP-46701: Serialization

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,123 @@
+.. _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-short+} 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 a document 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:
+
+- ``str``
+- ``int``
+- ``float``
+- ``bool``
+- ``datetime.datetime``
+- ``list``
+- ``dict``
+- ``None``
+
+For a complete list of {+language+}-to-BSON mappings, see the `bson <{+api-root+}bson/index.html>`__
+API documentation.
+
+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.
+
+Serializing Ordered Documents
+-----------------------------
+
+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. This behavior can cause issues when {+driver-short+} compares subdocuments
+to each other, since {+driver-short+} only considers subdocuments to be equal if their fields
+are in identical order.
+
+To preserve the order of keys when serializing and deserializing BSON,
+use the `SON <{+api-root+}bson/son.html>`__ class. You must also configure your collection
+to use SON for serialization and deserialization by specifying ``document_class=SON``
+to the ``with_options()`` method of a collection.
+
+The following example retrieves a document
+that has a ``location`` field value of ``{"street": "Cafe St", "zipcode": "10003"}`` from
+the ``restaurants`` collection:
+
+.. code-block:: python
+
+   from bson import CodecOptions, SON
+
+   opts = CodecOptions(document_class=SON)
+   collection = db.get_collection("restaurants")
+   son_collection = collection.with_options(codec_options=opts)
+   doc = son_collection.find_one({"location": SON([("street", "Cafe St"), ("zipcode", "10003")])})
+
+For more information about subdocument matching, see the
+:manual:`Query on Embedded/Nested Documents </tutorial/query-embedded-documents/>`
+guide in the {+mdb-server+} documentation.