v4.13 Release (#266)

jordan-smith721 · web-flow · commit 32b8becf9b87 · 2025-05-14T17:06:58.000-04:00
diff --git a/snooty.toml b/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"
diff --git a/source/includes/language-compatibility-table-pymongo.rst b/source/includes/language-compatibility-table-pymongo.rst
@@ -27,7 +27,7 @@ CPython
      - CPython 3.5
      - CPython 3.4
 
-   * - 4.11 to 4.12
+   * - 4.11 to 4.13
      - ✓ 
      - ✓ 
      - ✓ 
@@ -199,7 +199,7 @@ PyPy
      - PyPy3.6
      - PyPy3.5
 
-   * - 4.11 to 4.12
+   * - 4.11 to 4.13
      - ✓ 
      -
      -
diff --git a/source/includes/mongodb-compatibility-table-pymongo.rst b/source/includes/mongodb-compatibility-table-pymongo.rst
@@ -13,7 +13,17 @@
      - MongoDB 4.0
      - MongoDB 3.6
 
-   * - 4.11
+   * - 4.13
+     - ✓
+     - ✓
+     - ✓
+     - ✓
+     - ✓
+     - ✓
+     - 
+     -
+
+   * - 4.11 to 4.12
      - ✓
      - ✓
      - ✓
diff --git a/source/includes/pymongo-async-experimental.rst b/source/includes/pymongo-async-experimental.rst
diff --git a/source/reference/migration.txt b/source/reference/migration.txt
@@ -18,20 +18,31 @@ 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 implements ``asyncio`` support directly
+into {+driver-short+}. In most cases, the {+driver-async+} API results in
+improved performance over Motor. To see performance benchmarks, see the
+:ref:`pymongo-async-benchmarks` section.
 
 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 +56,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,20 +67,134 @@ to your application or use case:
 
 - Your application relies on other asynchronous libraries or frameworks, such as FastAPI
 
+.. _pymongo-async-benchmarks:
+
+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. In most
+cases, the {+driver-async+} API results in improved performance over Motor.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 20 20
+
+   * - 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
+
 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.
+   Motor will be deprecated on May 14th, 2026. 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
-for improved latency and throughput due to directly using Python Asyncio instead
+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
 place of ``MotorClient``, and changing the application's import statements to
@@ -87,26 +212,22 @@ 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.
-
-.. warning::
-
-   The {+driver-async+} driver does not support Tornado.
+in your application when migrating from Motor to the {+driver-async+} API.
 
 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.
+- ``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 +236,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 +253,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 +263,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 +284,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::
@@ -173,5 +294,5 @@ see the `API documentation <{+api-root+}pymongo/asynchronous/index.html>`__.
 Additional Information
 ----------------------
 
-To learn more about asynchronous Python, see the `Python Asyncio documentation
+To learn more about asynchronous Python, see the `Python asyncio documentation
 <https://docs.python.org/3/library/asyncio.html>`__.
diff --git a/source/reference/release-notes.txt b/source/reference/release-notes.txt
@@ -20,6 +20,7 @@ Release Notes
 
 Learn what's new in:
 
+* :ref:`Version 4.13 <version-4.13>`
 * :ref:`Version 4.12 <version-4.12>`
 * :ref:`Version 4.11 <version-4.11>`
 * :ref:`Version 4.10 <version-4.10>`
@@ -38,6 +39,21 @@ version of {+driver-short+} will raise the minimum {+mdb-server+} version from
 4.0 to 4.2. {+driver-short+} will no longer support {+mdb-server+} 4.0. To learn
 how to upgrade your driver version, see the :ref:`pymongo-upgrade` guide.
 
+.. _version-4.13:
+
+What's New in 4.13
+------------------
+
+The {+driver-short+} v4.13 release includes the following new features:
+
+- The {+driver-async+} API is generally available. To learn how to migrate
+  to the {+driver-async+} API from the {+driver-short+} driver or the Motor
+  library, see the :ref:`pymongo-async-migration` guide.
+- Fixes a bug where ``WriteConcern()`` could not be evaluated when using ``w="majority"``.
+
+To see a full list of resolved issues in this release, see the `Jira release
+notes <https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=42509>`__.
+
 .. _version-4.12:
 
 What's New in 4.12
