DOCSP-41887 Async Migration Guide

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/index.txt

@@ -26,6 +26,7 @@ MongoDB {+driver-short+} Documentation
    /troubleshooting
    /whats-new
    /upgrade
+   /pymongo-async-migration
    /previous-versions
    /issues-and-help
    /compatibility
@@ -120,6 +121,14 @@ 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 to the {+driver-async+} Driver
+------------------------------------
+
+In September 2024, MongoDB released the {+driver-async+} driver to unify {+driver-short+}
+and `Motor <https://www.mongodb.com/docs/drivers/motor/>`__, the asynchronous
+MongoDB driver for Python. Learn how to migrate from {+driver-short+} or Motor
+to the {+driver-async+} driver in the :ref:`pymongo-async-migration` section.
+
 Previous Versions
 -----------------
 

source/pymongo-async-migration.txt

@@ -0,0 +1,357 @@
+.. _pymongo-async-migration:
+
+===================================
+Migrate to the {+driver-async+} Driver
+===================================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: motor, async, refactor, migration
+
+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
+{+driver-short+} or Motor to the {+driver-async+} driver.
+
+Migrate From {+driver-short+}
+--------------------
+
+The {+driver-async+} driver behaves similarly to {+driver-short+}, but
+all methods that perform network operations are coroutines and must be awaited.
+To migrate from {+driver-short+} to {+driver-async+}, you must update your code
+in the following ways:
+
+- Replace all uses of ``MongoClient`` with ``AsyncMongoClient``.
+- Add the ``await`` keyword to all asynchronous method calls.
+- If an asynchronous method is called within a function, mark the function as ``async``.
+
+The following sections describe how to implement the asynchronous API.
+
+Asynchronous Methods
+~~~~~~~~~~~~~~~~~~~~
+
+The following tables list the asynchronous methods that are available in the
+{+driver-async+} driver. To call these methods, you must ``await`` them and call them
+inside an ``async`` function.
+
+Client Methods
+``````````````
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Method
+     - Example
+
+   * - ``AsyncMongoClient()``
+     - .. code-block:: python
+
+          from pymongo import AsyncMongoClient
+
+          AsyncMongoClient(...)
+
+   * - ``watch()``
+     - .. code-block:: python
+
+          async with await client.watch(...) as stream:
+             ...
+
+   * - ``server_info()``
+     - .. code-block:: python
+
+          await client.server_info(...)
+
+   * - ``list_databases()``
+     - .. code-block:: python
+
+          await client.list_databases()
+
+   * - ``list_database_names()``
+     - .. code-block:: python
+
+          await client.list_database_names()
+
+   * - ``drop_database()``
+     - .. code-block:: python
+
+          await client.drop_database(...)
+
+Database Methods
+````````````````
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Method
+     - Example
+
+   * - ``watch()``
+     - .. code-block:: python
+
+          async with await db.watch(...) as stream:
+             ...
+
+   * - ``create_collection()``
+     -   .. code-block:: python
+
+          await db.create_collection(...)
+
+   * - ``aggregate()``
+     - .. code-block:: python
+
+          async with await client.admin.aggregate(...) as cursor:
+             ...
+
+   * - ``command()``
+     - .. code-block:: python
+
+          await db.command(...)
+
+   * - ``cursor_command()``
+     - .. code-block:: python
+
+          await db.cursor_command(...)
+
+   * - ``list_collections()``
+     - .. code-block:: python
+
+          await db.list_collections()
+
+   * - ``list_collection_names()``
+     - .. code-block:: python
+
+          await db.list_collection_names()
+
+   * - ``drop_collection()``
+     - .. code-block:: python
+
+          await db.drop_collection(...)
+
+   * - ``validate_collection()``
+     - .. code-block:: python
+
+          await db.validate_collection(...)
+
+   * - ``dereference()``   
+     - .. code-block:: python
+
+          await db.dereference(...)
+
+Collection Methods
+``````````````````
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Method
+     - Example
+
+   * - ``watch()``
+     - .. code-block:: python
+
+          async with await collection.watch(...) as stream:
+             ...
+
+   * - ``insert_one()``
+     - .. code-block:: python
+
+          await collection.insert_one(...)
+
+   * - ``insert_many()``
+     - .. code-block:: python
+
+          await collection.insert_many(...)
+
+   * - ``replace_one()``
+     - .. code-block:: python
+
+          await collection.replace_one(...)
+
+   * - ``update_one()``
+     - .. code-block:: python
+
+          await collection.update_one(...)
+
+   * - ``update_many()``
+     - .. code-block:: python
+
+          await collection.update_many(...)
+
+   * - ``drop()``
+     - .. code-block:: python
+
+          await collection.drop()
+
+   * - ``delete_one()``
+     - .. code-block:: python
+
+          await collection.delete_one(...)
+
+   * - ``delete_many()``
+     - .. code-block:: python
+
+          await collection.delete_many(...)
+
+   * - ``find_one()``
+     - .. code-block:: python
+
+          await collection.find_one(...)
+
+   * - ``estimated_document_count()``
+     - .. code-block:: python
+
+          await collection.estimated_document_count()
+
+   * - ``count_documents()``
+     - .. code-block:: python
+
+          await collection.count_documents(...)
+
+   * - ``create_index()``
+     - .. code-block:: python
+
+          await collection.create_index(...)
+
+   * - ``create_indexes()``
+     - .. code-block:: python
+
+          await collection.create_indexes(...)
+
+   * - ``drop_index()``
+     - .. code-block:: python
+
+          await collection.drop_index(...)
+
+   * - ``drop_indexes()``
+     - .. code-block:: python
+
+          await collection.drop_indexes()
+
+   * - ``list_indexes()``
+     - .. code-block:: python
+
+          await collection.list_indexes()
+
+   * - ``index_information()``
+     - .. code-block:: python
+
+          await collection.index_information()
+
+   * - ``list_search_indexes()``
+     - .. code-block:: python
+
+          await collection.list_search_indexes()
+
+   * - ``create_search_index()``
+     - .. code-block:: python
+
+          await collection.create_search_index(...)
+
+   * - ``create_search_indexes()``
+     - .. code-block:: python
+
+          await collection.create_search_indexes(...)
+
+   * - ``drop_search_index()``
+     - .. code-block:: python
+
+          await collection.drop_search_index(...)
+
+   * - ``update_search_index()``
+     - .. code-block:: python
+
+          await collection.update_search_index(...)
+
+   * - ``options()``
+     - .. code-block:: python
+
+          await collection.options()
+
+   * - ``aggregate()``
+     - .. code-block:: python
+
+          async for doc in await collection.aggregate(...):
+             ...
+
+   * - ``aggregate_raw_batches()``
+     - .. code-block:: python
+
+          async for batch in await collection.aggregate_raw_batches(...):
+             ...
+
+   * - ``rename()``
+     - .. code-block:: python
+
+          await collection.rename(...)
+
+   * - ``distinct()``
+     - .. code-block:: python
+
+          await collection.distinct(...)
+
+   * - ``find_one_and_delete()``
+     - .. code-block:: python
+
+          await collection.find_one_and_delete(...)
+
+   * - ``find_one_and_replace()``
+     - .. code-block:: python
+
+          await collection.find_one_and_replace(...)
+
+   * - ``find_one_and_update()``
+     - .. code-block:: python
+
+          await collection.find_one_and_update(...)
+
+Migrate From Motor
+------------------
+
+The {+driver-async+} driver behaves nearly identically to the Motor library. 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
+
+
+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:
+
+- ``GridOut.open()`` returns ``None``.
+- ``AsyncMongoClient.__init__()`` does not accept an ``io_loop`` parameter.
+- ``GridIn.set()`` does not accept a filename. Instead pass a file name by using the
+  ``GridIn.filename`` attribute.
+- ``Cursor.each()`` does not exist in the {+driver-async+} driver.
+- ``stream_to_handler()`` does not exist in the {+driver-async+} driver.
+- ``to_list(0)`` is not valid in the {+driver-async+} driver. Use
+  ``to_list(None)`` instead.