Auto-import from docs-pymongo

Author: docs-builder-bot

dbx/language-compatibility-table-pymongo.rst

@@ -193,8 +193,98 @@ Python 3
    :ref:`TLS <pymongo-troubleshoot-tls>` section of the Troubleshooting guide.
 .. [#three-six-compat] Pymongo 4.1 requires Python 3.6.2 or later.
 
+For more information about how to read the compatibility tables, see
+:ref:`MongoDB Compatibility Tables. <about-driver-compatibility>`
+
 Python 2
 ~~~~~~~~
 
-{+driver-short+} versions 3.7 through 3.12 are compatible with Python 2.7 and PyPy, a Python 2.7-
-compatible alternative interpreter.
+{+driver-short+} versions 3.7 through 3.12 are compatible with Python 2.7 and PyPy, a
+Python 2.7-compatible alternative interpreter. However, in some cases, {+driver-short+}
+applications behave differently when running in a Python 2 environment.
+
+The following sections describe the differences in behavior between Python 2 and Python 3
+when using {+driver-short+}.
+
+Binary Data
+```````````
+
+In all versions of Python, {+driver-short+} encodes instances of the
+`bytes <https://docs.python.org/3/library/stdtypes.html#bytes>`__ class
+as binary data with subtype 0, the default subtype for binary data. In Python 3,
+{+driver-short+} decodes these values to instances of the ``bytes`` class. In Python 2,
+the driver decodes them to instances of the
+`Binary <https://pymongo.readthedocs.io/en/4.11/api/bson/binary.html#bson.binary.Binary>`__
+class with subtype 0. For code examples that show the differences, see the
+:ref:`Extended JSON <pymongo-serialization-binary-data>` page.
+
+The driver behaves the same way when decoding JSON binary values with subtype 0. In
+Python 3, it 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. For code
+examples that show the differences, see the
+:ref:`Extended JSON <pymongo-extended-json-binary-values>` page.
+            
+Pickled ObjectIds
+`````````````````
+
+If you pickled an ``ObjectId`` in Python 2 and want to unpickle it in Python 3, you must
+pass ``encoding='latin-1'`` as an argument to the ``pickle.loads()`` method.
+
+The following example shows how to use Python 3 to unpickle an ``ObjectId`` that was
+pickled in Python 2:
+
+.. code-block:: python
+   :emphasize-lines: 2
+
+   import pickle
+   pickle.loads(b'<ObjectId byte stream>', encoding='latin-1')
+
+If a Python 3 application uses a compatible serialization protocol to pickle an ``ObjectId``,
+you can use Python 2 to unpickle it. To specify a compatible protocol in Python 3, pass
+a value of 0, 1, or 2 for the ``protocol`` parameter of the ``pickle.dumps()`` method.
+
+The following example pickles an ``ObjectId`` in Python 3, then prints the ``ObjectId``
+and resulting ``bytes`` instance:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input::
+      :language: python
+
+      import pickle
+      from bson.objectid import ObjectId
+
+      oid = ObjectId()
+      oid_bytes = pickle.dumps(oid, protocol=2)
+      print("ObjectId: {}".format(oid))
+      print("ObjectId bytes: {}".format(oid_bytes))
+   
+   .. output::
+      :language: shell
+
+      ObjectId: 67af9b1fae9260c0e97eb9eb
+      ObjectId bytes: b'\x80\x02cbson.objectid\nObjectId\nq\x00...
+
+The following example unpickles the ``ObjectId`` from the previous example, and then
+prints the ``bytes`` and ``ObjectId`` instances:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input::
+      :language: python
+
+      import pickle
+      from bson.objectid import ObjectId
+
+      oid_bytes = b'\x80\x02cbson.objectid\nObjectId\nq\x00...' 
+      oid = pickle.loads(oid_bytes)
+      print("ObjectId bytes: {}".format(oid_bytes))
+      print("ObjectId: {}".format(oid))
+   
+   .. output::
+      :language: shell
+
+      ObjectId bytes: b'\x80\x02cbson.objectid\nObjectId\nq\x00)...
+      ObjectId: 67af9b1fae9260c0e97eb9eb