draft start

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

@@ -26,6 +26,7 @@ MongoDB {+driver-short+} Documentation
    /troubleshooting
    /whats-new
    /upgrade
+   /motor-async-migration
    /previous-versions
    /issues-and-help
    /compatibility
@@ -120,6 +121,12 @@ 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+}
+------------------------------------
+
+Learn how to migrate your Motor application to {+driver-async+} in the
+:ref:`pymongo-motor-to-async` section.
+
 Previous Versions
 -----------------
 

source/motor-async-migration.txt

@@ -0,0 +1,77 @@
+.. _pymongo-motor-to-async:
+
+===================================
+Migrate from Motor to {+driver-async+}
+===================================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: motor, async, refactor, migration
+
+Overview
+--------
+
+The {+driver-async+} is a unification of {+driver-short+} and the Motor library.
+In this guide, you can identify the changes you must make to migrate an
+application from Motor to {+driver-async+}.
+
+Prerequisites
+-------------
+
+To migrate from Motor to {+driver-async+}, you must first complete the following
+steps:
+
+1. Upgrade Motor to v3.6.
+#. Run your application to identify any warnings or errors.
+#. Update your application to remove all warnings and errors.
+#. Update any imports in your application that import from the ``motor`` library
+   to instead import from ``pymongo.asynchronous``.
+
+API Changes
+-----------
+
+To use the following collection method calls, you must wrap them in an ``await``
+statement:
+
+- ``aggregate()``
+- ``aggregate_raw_batches()``
+- ``watch()``
+- ``list_indexes()``
+- ``list_search_indexes()``
+
+The following example demonstrates how to call the ``list_search_indexes()`` method with
+{+driver-async+}:
+
+.. code-block:: python
+
+   results = await collection.list_search_indexes()
+
+The following methods are not asynchronous in {+driver-async+}:
+
+- ``MongoClient.start_session()``
+
+The following methods are asynchronous in {+driver-async+}:
+
+- ``AsyncClientSession.start_transaction()``
+- ``Cursor.rewind()``
+
+Method Signature Changes
+------------------------
+
+The following method signatures are changed in {+driver-async+}:
+
+- ``GridOut.open()`` now returns ``None``.
+- ``AsyncMongoClient.__init__`` no longer accepts an ``io_loop`` parameter.
+- ``Gridln.set()`` does not accept a filename. Instead pass a file name by using the
+  ``Gridln.filename`` attribute.
+- ``Cursor.each()`` is removed.
+- ``to_list(0)`` is no longer valid. Use ``to_list(None)`` instead.