migration page updates

Author: jordan-smith721

snooty.toml

@@ -31,7 +31,7 @@ mdb-server = "MongoDB Server"
 mongo-community = "MongoDB Community Edition"
 mongo-enterprise = "MongoDB Enterprise Edition"
 docs-branch = "master"                                                       # always set this to the docs branch (i.e. master, 1.7, 1.8, etc.)
-version-number = "4.12"
+version-number = "4.13"
 patch-version-number = "{+version-number+}.0"                                # always set this to the driver branch (i.e. 1.7.0, 1.8.0, etc.)
 version = "v{+version-number+}"
 stable-api = "Stable API"

source/includes/pymongo-async-experimental.rst

@@ -18,20 +18,29 @@ Migrate to {+driver-async+}
 .. meta::
    :keywords: motor, async, refactor, migration, asynchronous
 
-.. include:: /includes/pymongo-async-experimental.rst
-
 Overview
 --------
 
-The {+driver-async+} driver is a unification of {+driver-short+} and the `Motor
+The {+driver-async+} API 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.
+Motor to the {+driver-async+} API.
+
+Motivation
+~~~~~~~~~~
+
+The {+driver-async+} API is designed to be a replacement for the Motor
+library. Motor was created to provide support for Tornado, with asyncio support
+added later. Because of this, Motor provides full asyncio and Tornado support,
+but still relies on a thread pool to perform network operations. In some cases,
+this might lead to performance degradation when using the Motor library. To
+address this issue, the {+driver-async+} API includes asyncio support directly
+into {+driver-short+}.
 
 Synchronous Versus Asynchronous
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To determine whether to migrate to the {+driver-async+} driver or to continue using
+To determine whether to migrate to the {+driver-async+} API or to continue using
 Synchronous {+driver-short+}, consider the information in this section.
 
 Synchronous {+driver-short+} is preferable if the following criteria applies to your
@@ -45,7 +54,7 @@ application or use case:
 
 - You prefer the simplicity of synchronous logic when debugging your application
 
-Consider migrating to the {+driver-async+} driver if the following criteria applies
+Consider migrating to the {+driver-async+} API if the following criteria applies
 to your application or use case:
 
 - Your application implements large, highly concurrent workloads (on the order of
@@ -56,19 +65,187 @@ to your application or use case:
 
 - Your application relies on other asynchronous libraries or frameworks, such as FastAPI
 
+Performance Benchmarks
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following table shows the performance benchmarks for different tasks
+performed with the {+driver-async+} API and the Motor library. Each task was
+performed with 10 iterations of 1000 documents each.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 40 40
+
+   * - Operation
+     - Motor Performance
+     - {+driver-async+} Performance
+   
+   * - ``TestFindManyAndEmptyCursor``
+     - 74.074 MB/s
+     -  112.490 MB/s
+   
+   * - ``TestFindManyAndEmptyCursor80Tasks``
+     - 37.181 MB/s
+     - 89.521 MB/s
+   
+   * - ``TestFindManyAndEmptyCursor8Tasks``
+     - 63.145 MB/s
+     - 97.165 MB/s
+   
+   * - ``TestFindOneByID``
+     - 3.121 MB/s
+     - 2.922 MB/s
+   
+   * - ``TestFindOneByID80Tasks``
+     - 3.789 MB/s
+     - 4.071 MB/s
+   
+   * - ``TestFindOneByID8Tasks``
+     - 3.697 MB/s
+     - 3.445 MB/s
+   
+   * - ``TestFindOneByIDUnlimitedTasks``
+     - 3.866 MB/s
+     - 4.171 MB/s
+   
+   * - ``TestGridFsDownload``
+     - 573.770 MB/s
+     - 603.578 MB/s
+   
+   * - ``TestGridFsUpload``
+     - 430.870 MB/s
+     - 444.445 MB/s
+   
+   * - ``TestLargeDocBulkInsert``
+     - 82.631 MB/s
+     - 102.105 MB/s
+   
+   * - ``TestLargeDocClientBulkInsert``
+     - 75.057 MB/s
+     - 90.345 MB/s
+   
+   * - ``TestLargeDocCollectionBulkInsert``
+     - 85.810 MB/s
+     - 101.838 MB/s
+   
+   * - ``TestLargeDocInsertOne``
+     - 84.832 MB/s
+     - 101.934 MB/s
+   
+   * - ``TestLargeDocInsertOneUnlimitedTasks``
+     - 120.389 MB/s
+     - 163.553 MB/s
+   
+   * - ``TestRunCommand``
+     - 0.036 MB/s
+     - 0.034 MB/s
+   
+   * - ``TestRunCommand80Tasks``
+     - 0.042 MB/s
+     - 0.043 MB/s
+   
+   * - ``TestRunCommand8Tasks``
+     - 0.039 MB/s
+     - 0.041 MB/s
+   
+   * - ``TestRunCommandUnlimitedTasks``
+     - 0.043 MB/s
+     - 0.042 MB/s
+   
+   * - ``TestSmallDocBulkInsert``
+     - 35.071 MB/s
+     - 38.213 MB/s
+   
+   * - ``TestSmallDocBulkMixedOps``
+     - 0.729 MB/s
+     - 0.446 MB/s
+   
+   * - ``TestSmallDocClientBulkInsert``
+     - 25.032 MB/s
+     - 25.727 MB/s
+   
+   * - ``TestSmallDocClientBulkMixedOps``
+     - 1.746 MB/s
+     - 1.723 MB/s
+   
+   * - ``TestSmallDocCollectionBulkInsert``
+     - 34.144 MB/s
+     - 37.666 MB/s
+   
+   * - ``TestSmallDocInsertOne``
+     - 0.539 MB/s
+     - 0.572 MB/s
+   
+   * - ``TestSmallDocInsertOneUnlimitedTasks``
+     - 0.740 MB/s
+     - 0.786 MB/s
+
+**Motor**
+
+TestFindManyAndEmptyCursor 74.074 MB/s
+TestFindManyAndEmptyCursor80Tasks 37.181 MB/s
+TestFindManyAndEmptyCursor8Tasks 63.145 MB/s
+TestFindOneByID 3.121 MB/s
+TestFindOneByID80Tasks 3.789 MB/s
+TestFindOneByID8Tasks 3.697 MB/s
+TestFindOneByIDUnlimitedTasks 3.866 MB/s
+TestGridFsDownload 573.770 MB/s
+TestGridFsUpload 430.870 MB/s
+TestLargeDocBulkInsert 82.631 MB/s
+TestLargeDocClientBulkInsert 75.057 MB/s
+TestLargeDocCollectionBulkInsert 85.810 MB/s
+TestLargeDocInsertOne 84.832 MB/s
+TestLargeDocInsertOneUnlimitedTasks 120.389 MB/s
+TestRunCommand 0.036 MB/s
+TestRunCommand80Tasks 0.042 MB/s
+TestRunCommand8Tasks 0.039 MB/s
+TestRunCommandUnlimitedTasks 0.043 MB/s
+TestSmallDocBulkInsert 35.071 MB/s
+TestSmallDocBulkMixedOps 0.729 MB/s
+TestSmallDocClientBulkInsert 25.032 MB/s
+TestSmallDocClientBulkMixedOps 1.746 MB/s
+TestSmallDocCollectionBulkInsert 34.144 MB/s
+TestSmallDocInsertOne 0.539 MB/s
+TestSmallDocInsertOneUnlimitedTasks 0.740 MB/s 
+
+{+driver-async+}
+
+TestFindManyAndEmptyCursor 112.490 MB/s
+TestFindManyAndEmptyCursor8Tasks 97.165 MB/s
+TestFindManyAndEmptyCursor80Tasks 89.521 MB/s
+TestFindOneByID 2.922 MB/s
+TestFindOneByID8Tasks 3.445 MB/s
+TestFindOneByID80Tasks 4.071 MB/s
+TestFindOneByIDUnlimitedTasks 4.171 MB/s
+TestGridFsDownload 603.578 MB/s
+TestGridFsUpload 444.445 MB/s
+TestLargeDocBulkInsert 102.105 MB/s
+TestLargeDocClientBulkInsert 90.345 MB/s
+TestLargeDocCollectionBulkInsert 101.838 MB/s
+TestLargeDocInsertOne 101.934 MB/s
+TestLargeDocInsertOneUnlimitedTasks 163.553 MB/s
+TestRunCommand 0.034 MB/s
+TestRunCommand8Tasks 0.041 MB/s
+TestRunCommand80Tasks 0.043 MB/s
+TestRunCommandUnlimitedTasks 0.042 MB/s
+TestSmallDocBulkInsert 38.213 MB/s
+TestSmallDocBulkMixedOps 0.446 MB/s
+TestSmallDocClientBulkInsert 25.727 MB/s
+TestSmallDocClientBulkMixedOps 1.723 MB/s
+TestSmallDocCollectionBulkInsert 37.666 MB/s
+TestSmallDocInsertOne 0.572 MB/s
+TestSmallDocInsertOneUnlimitedTasks 0.786 MB/s 
+
 Migrate From Motor
 ------------------
 
 .. warning:: Motor Deprecation
-
-   The {+driver-async+} driver is experimental. We do **not** recommend using it
-   in production environments.
 
    Motor will be deprecated one year after the **production release** of the
-   {+driver-async+} driver. We strongly recommend that Motor users migrate to
-   the {+driver-async+} driver while Motor is still supported.
+   {+driver-async+} API. We strongly recommend that Motor users migrate to
+   the {+driver-async+} API while Motor is still supported.
 
-The {+driver-async+} driver functions similarly to the Motor library, but allows
+The {+driver-async+} API 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
@@ -87,26 +264,26 @@ read and write operations in Motor compared to {+driver-async+}:
    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. To learn about the versions of Motor
+API, see the :ref:`pymongo-async-methods` section. To learn about the versions of Motor
 that correspond to {+driver-short+}, see the :ref:`pymongo-motor-compatibility` section of
 the Compatibility 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.
+in your application when migrating from Motor to the {+driver-async+} API.
 
 .. warning::
 
-   The {+driver-async+} driver does not support Tornado.
+   The {+driver-async+} API does not support Tornado.
 
 Method Signature Changes
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following Motor method signatures behave differently in the {+driver-async+} driver:
+The following Motor method signatures behave differently in the {+driver-async+} API:
 
 - ``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
+- ``AsyncCursor.each()`` does not exist in the {+driver-async+} api-root.
+- ``MotorGridOut.stream_to_handler()`` does not exist in the {+driver-async+} API.
+- ``AsyncCursor.to_list(0)`` is not valid in the {+driver-async+} API. 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
@@ -115,13 +292,13 @@ The following Motor method signatures behave differently in the {+driver-async+}
 .. warning::
 
    Motor users may experience a degradation of performance when switching to the
-   {+driver-async+} driver. This is due to the {+driver-async+} driver using native
+   {+driver-async+} API. This is due to the {+driver-async+} API using native
    ``asyncio`` tasks instead of thread-based executors. Thread-based executors
    have similar performance characteristics to the synchronous driver, but slower.
    This means they perform better for workloads that do not fit the preceding criteria
-   for the {+driver-async+} driver.
+   for the {+driver-async+} API.
 
-   If you are experiencing performance slowdown, identify whether the {+driver-async+} driver
+   If you are experiencing performance slowdown, identify whether the {+driver-async+} API
    is necessary for your usecase. If you determine your use case is better served by
    synchronous {+driver-short+}, consider using the synchronous driver
    with ``asyncio.loop.run_in_executor()`` for asynchronous compatibility. To learn more, see
@@ -132,7 +309,7 @@ The following Motor method signatures behave differently in the {+driver-async+}
 Migrate from {+driver-short+}
 -----------------------------
 
-The {+driver-async+} driver behaves similarly to {+driver-short+}, but
+The {+driver-async+} API 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:
@@ -142,11 +319,11 @@ in the following ways:
 - If you call an asynchronous method inside a function, mark the function as ``async``.
 
 Keep the following points in mind when migrating from synchronous {+driver-short+}
-to the {+driver-async+} driver:
+to the {+driver-async+} API:
 
 - To convert an ``AsyncCursor`` to a list, you must use the asynchronous ``cursor.to_list()``
   method.
-- The ``AsyncCollection.find()`` method in the {+driver-async+} driver is synchronous, but
+- The ``AsyncCollection.find()`` method in the {+driver-async+} API is synchronous, but
   returns an ``AsyncCursor``. To iterate through the cursor, you must use an ``async for``
   loop.
 - The ``AsyncMongoClient`` object does not support the ``connect`` keyword argument.
@@ -163,7 +340,7 @@ to the {+driver-async+} driver:
 Asynchronous Methods
 --------------------
 
-For a complete list of asynchronous methods available in the {+driver-async+} driver,
+For a complete list of asynchronous methods available in the {+driver-async+} API,
 see the `API documentation <{+api-root+}pymongo/asynchronous/index.html>`__.
 
 .. note::