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/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/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..5cce8449 100644 --- 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 `__. 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 `__. diff --git a/source/reference/release-notes.txt b/source/reference/release-notes.txt index 60884e98..a24a8696 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,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 `__. + .. _version-4.12: What's New in 4.12