DOCSP-41887 Async Migration Guide (#103)

(cherry picked from commit acff81f)

Author: jordan-smith721

snooty.toml

@@ -24,6 +24,7 @@ sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
 [constants]
 driver-short = "PyMongo"
 driver-long = "PyMongo, the MongoDB synchronous Python driver,"
+driver-async = "PyMongo Async"
 language = "Python"
 mdb-server = "MongoDB Server"
 mongo-community = "MongoDB Community Edition"

source/connect/stable-api.txt

@@ -120,4 +120,3 @@ following API documentation:
 - `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__
 - `ServerApi <{+api-root+}pymongo/server_api.html#pymongo.server_api.ServerApi>`__
 - `ServerApiVersion <{+api-root+}pymongo/server_api.html#pymongo.server_api.ServerApiVersion>`__
-

source/includes/pymongo-async-experimental.rst

@@ -0,0 +1,7 @@
+.. important::
+
+   The {+driver-async+} driver is experimental and should not be used in
+   production environments. Classes, methods, and behaviors described in this
+   guide might change prior to the full release. If you encounter any
+   issues with {+driver-async+}, you can learn how to report them on the
+   :ref:`pymongo-issues-help` page.

source/index.txt

@@ -26,6 +26,8 @@ MongoDB {+driver-short+} Documentation
    /troubleshooting
    /whats-new
    /upgrade
+   /motor-async-migration
+   /pymongo-to-async-guide
    /previous-versions
    /issues-and-help
    /compatibility
@@ -120,6 +122,21 @@ Upgrade {+driver-short+} Versions
 Learn what changes you might need to make to your application to upgrade driver versions
 in the :ref:`pymongo-upgrade` section.
 
+Migrate from Motor to {+driver-async+}
+-------------------------------------
+
+In September 2024, MongoDB released the experimental {+driver-async+} driver as a replacement
+for `Motor <https://www.mongodb.com/docs/drivers/motor/>`__, the previous asynchronous
+MongoDB driver for Python. Learn how to migrate from Motor
+to the {+driver-async+} driver in the :ref:`pymongo-async-motor-migration`
+section.
+
+Switch from {+driver-short+} to {+driver-async+}
+----------------------------------------------
+
+Learn what changes you need to make to switch from {+driver-short+} to
+the experimental {+driver-async+} driver in the :ref:`pymongo-to-async-guide` section.
+
 Previous Versions
 -----------------
 

source/motor-async-migration.txt

@@ -0,0 +1,76 @@
+.. _pymongo-async-motor-migration:
+
+====================================
+Migrate from Motor to {+driver-async+}
+====================================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: motor, async, refactor, migration
+
+.. include:: /includes/pymongo-async-experimental.rst
+
+Overview
+--------
+
+The {+driver-async+} driver is a unification of {+driver-short+} and the `Motor
+library <https://www.mongodb.com/docs/drivers/motor/>`__. In this guide, you can
+identify the changes you must make to migrate an application from
+Motor to the {+driver-async+} driver.
+
+Migrate From Motor
+------------------
+
+The {+driver-async+} driver functions similarly to the Motor library, but allows
+for improved latency and throughput due to directly using Python Asyncio instead
+of delegating work to a thread pool. In most cases, you can directly migrate
+existing Motor applications to {+driver-async+} by using ``AsyncMongoClient`` in
+place of ``MotorClient``, and changing the application's import statements to
+import from ``pymongo``.
+
+The following example shows the difference in imports to use a client for
+read and write operations in Motor compared to {+driver-async+}:
+
+.. code-block:: python
+
+   # Motor client import
+   from motor.motor_asyncio import AsyncIOMotorClient
+
+   # {+driver-async+} client import
+   from pymongo import AsyncMongoClient
+
+To see a list of the asynchronous methods available in the {+driver-async+}
+driver, see the :ref:`pymongo-async-methods` section in the {+driver-short+} to
+{+driver-async+} guide.
+
+The following section shows the method signature changes that you must implement
+in your application when migrating from Motor to the {+driver-async+} driver.
+
+Method Signature Changes
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following Motor method signatures behave differently in the {+driver-async+} driver:
+
+- ``AsyncMongoClient.__init__()`` does not accept an ``io_loop`` parameter.
+- ``AsyncCursor.each()`` does not exist in the {+driver-async+} driver.
+- ``MotorGridOut.stream_to_handler()`` does not exist in the {+driver-async+} driver.
+- ``AsyncCursor.to_list(0)`` is not valid in the {+driver-async+} driver. Use
+  ``to_list(None)`` instead.
+- ``MongoClient`` is thread safe and can be used by many threads, however, an
+  ``AsyncMongoClient`` is not thread safe and should only be used by a single
+  event loop.
+
+Additional Information
+----------------------
+
+To learn more about asynchronous Python, see the `Python Asyncio documentation
+<https://docs.python.org/3/library/asyncio.html>`__.