split into two pages + feedback

Author: jordan-smith721

source/index.txt

@@ -26,7 +26,8 @@ MongoDB {+driver-short+} Documentation
    /troubleshooting
    /whats-new
    /upgrade
-   /pymongo-async-migration
+   /pymongo-async-motor-migration
+   /pymongo-to-async-guide
    /previous-versions
    /issues-and-help
    /compatibility
@@ -121,13 +122,20 @@ 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
-------------------------------------
+Migrate from Motor to the {+driver-async+} Driver
+------------------------------------------------
+
+In September 2024, MongoDB released the {+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+}
+----------------------------------------------
 
-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.
+Learn what changes you need to make to switch from {+driver-short+} to
+{+driver-async+} in the :ref:`pymongo-to-async-guide` section.
 
 Previous Versions
 -----------------

source/motor-async-migration.txt

@@ -0,0 +1,74 @@
+.. _pymongo-async-motor-migration:
+
+===============================================
+Migrate from Motor 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 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:
+
+- ``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.
+
+Additional Information
+----------------------
+
+To learn more about asynchronous Python, see the `Python Asyncio documentation
+<https://docs.python.org/3/library/asyncio.html>`__.

source/pymongo-async-migration.txt renamed to source/pymongo-to-async-guide.txt

@@ -1,8 +1,8 @@
-.. _pymongo-async-migration:
+.. _pymongo-to-async-guide:
 
-===================================
-Migrate to the {+driver-async+} Driver
-===================================
+====================================
+Switch from {+driver-short+} to {+driver-async+}
+====================================
 
 .. contents:: On this page
    :local:
@@ -15,15 +15,15 @@ Migrate to the {+driver-async+} Driver
    :values: reference
 
 .. meta::
-   :keywords: motor, async, refactor, migration
+   :keywords: asyncronous, 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.
+identify the changes you must make to switch from {+driver-short+} to
+{+driver-async+}.
 
 Migrate From {+driver-short+}
 --------------------
@@ -39,6 +39,8 @@ in the following ways:
 
 The following sections describe how to implement the asynchronous API.
 
+.. _pymongo-async-methods:
+
 Asynchronous Methods
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -61,7 +63,7 @@ Client Methods
 
           from pymongo import AsyncMongoClient
 
-          AsyncMongoClient(...)
+          async with AsyncMongoClient(...)
 
    * - ``watch()``
      - .. code-block:: python
@@ -319,39 +321,8 @@ Collection Methods
 
           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:
+Additional Information
+----------------------
 
-- ``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.
+To learn more about asynchronous Python, see the `Python Asyncio documentation
+<https://docs.python.org/3/library/asyncio.html>`__.