From 5d7743f2c6ec64e5cda903ff93e04944a558566a Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Wed, 14 May 2025 12:23:53 -0400 Subject: [PATCH 1/5] migration page updates --- snooty.toml | 2 +- .../includes/pymongo-async-experimental.rst | 7 - source/reference/migration.txt | 229 ++++++++++++++++-- 3 files changed, 204 insertions(+), 34 deletions(-) delete mode 100644 source/includes/pymongo-async-experimental.rst diff --git a/snooty.toml b/snooty.toml index 125cb037..0fff7525 100644 --- 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/pymongo-async-experimental.rst b/source/includes/pymongo-async-experimental.rst deleted file mode 100644 index 5bd947c5..00000000 --- a/source/includes/pymongo-async-experimental.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. important:: - - The {+driver-async+} driver is experimental. We do **not** - recommend using it in production environments. Classes, methods, and - behaviors described in this guide might change before the production release. - If you encounter any issues with {+driver-async+}, you can learn how to - report them on the :ref:`pymongo-issues-help` page. \ No newline at end of file diff --git a/source/reference/migration.txt b/source/reference/migration.txt index b120ccbf..0e120420 100644 --- a/source/reference/migration.txt +++ b/source/reference/migration.txt @@ -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 `__. 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:: From 2eadd883d43b7a8e42f702892f0667338c78b9d5 Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Wed, 14 May 2025 15:26:15 -0400 Subject: [PATCH 2/5] version updates --- .../language-compatibility-table-pymongo.rst | 4 +- .../mongodb-compatibility-table-pymongo.rst | 12 +++- source/reference/migration.txt | 60 +------------------ source/reference/release-notes.txt | 15 +++++ 4 files changed, 30 insertions(+), 61 deletions(-) diff --git a/source/includes/language-compatibility-table-pymongo.rst b/source/includes/language-compatibility-table-pymongo.rst index 381db20d..c06eb3cf 100644 --- 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 index 92862262..d2e9aae4 100644 --- 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/reference/migration.txt b/source/reference/migration.txt index 0e120420..019ef199 100644 --- a/source/reference/migration.txt +++ b/source/reference/migration.txt @@ -34,7 +34,7 @@ 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 +address this issue, the {+driver-async+} API implements asyncio support directly into {+driver-short+}. Synchronous Versus Asynchronous @@ -74,7 +74,7 @@ performed with 10 iterations of 1000 documents each. .. list-table:: :header-rows: 1 - :widths: 20 40 40 + :widths: 40 20 20 * - Operation - Motor Performance @@ -180,62 +180,6 @@ performed with 10 iterations of 1000 documents each. - 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 ------------------ diff --git a/source/reference/release-notes.txt b/source/reference/release-notes.txt index 60884e98..fa87324c 100644 --- 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 ` * :ref:`Version 4.12 ` * :ref:`Version 4.11 ` * :ref:`Version 4.10 ` @@ -38,6 +39,20 @@ 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, 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 `__. + .. _version-4.12: What's New in 4.12 From e6f98df936ca2e209f908e88ca31db62a008c05d Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Wed, 14 May 2025 15:42:20 -0400 Subject: [PATCH 3/5] tech feedback --- source/reference/migration.txt | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/source/reference/migration.txt b/source/reference/migration.txt index 019ef199..4ef8670a 100644 --- a/source/reference/migration.txt +++ b/source/reference/migration.txt @@ -70,7 +70,8 @@ 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. +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 @@ -82,7 +83,7 @@ performed with 10 iterations of 1000 documents each. * - ``TestFindManyAndEmptyCursor`` - 74.074 MB/s - - 112.490 MB/s + - 112.490 MB/s * - ``TestFindManyAndEmptyCursor80Tasks`` - 37.181 MB/s @@ -215,17 +216,13 @@ 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+} API. -.. warning:: - - The {+driver-async+} API does not support Tornado. - Method Signature Changes ~~~~~~~~~~~~~~~~~~~~~~~~ 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+} api-root. +- ``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. From 56a31672164c3a3bfff48d56fc847945fb5a56a1 Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Wed, 14 May 2025 16:22:55 -0400 Subject: [PATCH 4/5] asyncio --- source/reference/migration.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/reference/migration.txt b/source/reference/migration.txt index 4ef8670a..639efab3 100644 --- a/source/reference/migration.txt +++ b/source/reference/migration.txt @@ -191,7 +191,7 @@ Migrate From Motor the {+driver-async+} API while Motor is still supported. The {+driver-async+} API functions similarly to the Motor library, but allows -for improved latency and throughput due to directly using Python Asyncio instead +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 @@ -291,5 +291,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 `__. From 8152b7f40daa8f695c209751d88b18acbcdaa533 Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Wed, 14 May 2025 16:47:44 -0400 Subject: [PATCH 5/5] feedback --- source/reference/migration.txt | 17 ++++++++++------- source/reference/release-notes.txt | 3 ++- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/source/reference/migration.txt b/source/reference/migration.txt index 639efab3..5cce8449 100644 --- a/source/reference/migration.txt +++ b/source/reference/migration.txt @@ -30,12 +30,14 @@ 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, +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+}. +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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -65,6 +67,8 @@ to your application or use case: - Your application relies on other asynchronous libraries or frameworks, such as FastAPI +.. _pymongo-async-benchmarks: + Performance Benchmarks ~~~~~~~~~~~~~~~~~~~~~~ @@ -186,12 +190,11 @@ Migrate From Motor .. warning:: Motor Deprecation - Motor will be deprecated one year after the **production release** of the - {+driver-async+} API. We strongly recommend that Motor users migrate to + 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+} API functions similarly to the Motor library, but allows -for improved latency and throughput due to directly using Python asyncio instead +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 diff --git a/source/reference/release-notes.txt b/source/reference/release-notes.txt index fa87324c..a24a8696 100644 --- a/source/reference/release-notes.txt +++ b/source/reference/release-notes.txt @@ -47,7 +47,8 @@ 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, see the :ref:`pymongo-async-migration` guide. + 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