NS technical feedback

Author: mcmorisi

source/serialization.txt

@@ -48,7 +48,8 @@ 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
+to handle the conversion. {+driver-short+} cannot serialize custom classes otherwise. The
+following sections show how to serialize and deserialize
 custom classes.
 
 Serializing Custom Classes
@@ -90,34 +91,3 @@ it back into a ``Restaurant`` object from the preceding example:
 
 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 original
-dictionary. This behavior can cause issues when {+driver-short+} compares subdocuments
-to each other, because {+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.

source/troubleshooting.txt

@@ -110,149 +110,6 @@ frameworks.
    if __name__ == "__main__":
        app.run()
 
-Query Works in the Shell But Not in {+driver-short+}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-After the ``_id`` field, which is always first, the key-value pairs in a BSON document can
-be in any order. The ``mongo`` shell preserves key order when reading and writing
-data, as shown by the fields "b" and "a" in the following code example:
-
-.. code-block:: javascript
-
-   // mongo shell
-   db.collection.insertOne( { "_id" : 1, "subdocument" : { "b" : 1, "a" : 1 } } )
-   // Returns: WriteResult({ "nInserted" : 1 })
-   
-   db.collection.findOne()
-   // Returns: { "_id" : 1, "subdocument" : { "b" : 1, "a" : 1 } }
-
-{+driver-short+} represents BSON documents as Python dictionaries by default,
-and the order of keys in dictionaries is not defined. In Python, a dictionary declared with
-the "a" key first is the same as one with the "b" key first. In the following example,
-the keys are displayed in the same order regardless of their order in the ``print``
-statement:
-
-.. code-block:: python
-   
-   print({'a': 1.0, 'b': 1.0})
-   # Returns: {'a': 1.0, 'b': 1.0}
-   
-   print({'b': 1.0, 'a': 1.0})
-   # Returns: {'a': 1.0, 'b': 1.0}
-
-Similarly, Python dictionaries might not show keys in the order they are
-stored in BSON. The following example shows the result of printing the document
-inserted in a preceding example:
-
-.. code-block:: python
-
-   print(collection.find_one())
-   # Returns: {'_id': 1.0, 'subdocument': {'a': 1.0, 'b': 1.0}}
-
-To preserve the order of keys when reading BSON, use the ``SON`` class,
-which is a dictionary that remembers its key order.
-
-The following code example shows how to create a collection
-configured to use the ``SON`` class:
-
-.. code-block:: python
-
-   from bson import CodecOptions, SON
-   
-   opts = CodecOptions(document_class=SON)
-   
-   CodecOptions(document_class=...SON..., tz_aware=False, uuid_representation=UuidRepresentation.UNSPECIFIED, unicode_decode_error_handler='strict', tzinfo=None, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None), datetime_conversion=DatetimeConversion.DATETIME)
-   collection_son = collection.with_options(codec_options=opts)
-
-When you find the preceding subdocument, the driver represents query results with
-``SON`` objects and preserves key order:
-
-.. io-code-block::
-
-   .. input::
-      :language: python
-      
-      print(collection_son.find_one())
-   
-   .. output::
-
-      SON([('_id', 1.0), ('subdocument', SON([('b', 1.0), ('a', 1.0)]))])
-
-The subdocument's actual storage layout is now visible: "b" is before "a".
-
-Because a Python dictionary's key order is not defined, you cannot predict how it will be
-serialized to BSON. However, MongoDB considers subdocuments equal only if their
-keys have the same order. If you use a Python dictionary to query on a subdocument, it may
-not match:
-
-.. io-code-block::
-
-   .. input:: 
-      :language: python
-
-      collection.find_one({'subdocument': {'b': 1.0, 'a': 1.0}}) is None
-
-   .. output::
-
-      True
-
-Because Python considers the two dictionaries the same, swapping the key order in your query
-makes no difference:
-
-.. io-code-block::
-
-   .. input:: 
-      :language: python
-
-      collection.find_one({'subdocument': {'b': 1.0, 'a': 1.0}}) is None
-
-   .. output::
-
-      True
-
-You can solve this in two ways. First, you can match the subdocument field-by-field:
-
-.. io-code-block::
-
-   .. input::
-      :language: python
-
-      collection.find_one({'subdocument.a': 1.0,
-                         'subdocument.b': 1.0})
-
-   .. output::
-      
-      {'_id': 1.0, 'subdocument': {'a': 1.0, 'b': 1.0}}
-
-The query matches any subdocument with an "a" of 1.0 and a "b" of 1.0,
-regardless of the order in which you specify them in Python, or the order in which they're
-stored in BSON. This query also now matches subdocuments with additional
-keys besides "a" and "b", whereas the previous query required an exact match.
-
-The second solution is to use a ``~bson.son.SON`` object to specify the key order:
-
-.. io-code-block::
-
-   .. input::
-      :language: python
-
-      query = {'subdocument': SON([('b', 1.0), ('a', 1.0)])}
-      collection.find_one(query)
-
-   .. output::
-      
-      {'_id': 1.0, 'subdocument': {'a': 1.0, 'b': 1.0}}
-
-The driver preserves the key order you use when you create a ``~bson.son.SON``
-when serializing it to BSON and using it as a query. Thus, you can create a
-subdocument that exactly matches the subdocument in the collection.
-
-.. note:: 
-   
-   For more information about subdocument matching, see the
-   `Query on Embedded/Nested Documents <https://www.mongodb.com/docs/manual/tutorial/query-embedded-documents/>`__
-   guide in the {+mdb-server+} documentation.
-
 Cursors
 -------