Skip to content

v4.13 Release #266

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
May 14, 2025
Merged

v4.13 Release #266

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5d7743f
migration page updates
jordan-smith721 May 14, 2025
2eadd88
version updates
jordan-smith721 May 14, 2025
e6f98df
tech feedback
jordan-smith721 May 14, 2025
56a3167
asyncio
jordan-smith721 May 14, 2025
8152b7f
feedback
jordan-smith721 May 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion snooty.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
4 changes: 2 additions & 2 deletions source/includes/language-compatibility-table-pymongo.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ CPython
- CPython 3.5
- CPython 3.4

* - 4.11 to 4.12
* - 4.11 to 4.13
- ✓
- ✓
- ✓
Expand Down Expand Up @@ -199,7 +199,7 @@ PyPy
- PyPy3.6
- PyPy3.5

* - 4.11 to 4.12
* - 4.11 to 4.13
- ✓
-
-
Expand Down
12 changes: 11 additions & 1 deletion source/includes/mongodb-compatibility-table-pymongo.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,17 @@
- MongoDB 4.0
- MongoDB 3.6

* - 4.11
* - 4.13
- ✓
- ✓
- ✓
- ✓
- ✓
- ✓
-
-

* - 4.11 to 4.12
- ✓
- ✓
- ✓
Expand Down
7 changes: 0 additions & 7 deletions source/includes/pymongo-async-experimental.rst
View file
Open in desktop

This file was deleted.

180 changes: 149 additions & 31 deletions source/reference/migration.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,20 +18,29 @@
.. 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,
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For all mentions:

Suggested change
added later. Because of this, Motor provides full asyncio and Tornado 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,

Check failure on line 35 in source/reference/migration.txt

View workflow job for this annotation

GitHub Actions / TDBX Vale rules 

[vale] reported by reviewdog 🐶
[MongoDB.Wordiness] Consider using 'sometimes' instead of 'In some cases'.

Raw Output:
{"message": "[MongoDB.Wordiness] Consider using 'sometimes' instead of 'In some cases'.", "location": {"path": "source/reference/migration.txt", "range": {"start": {"line": 35, "column": 66}}}, "severity": "ERROR"}
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+}.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re: the comments below. I would mention in this intro paragraph that PyMongo Async has better performance in most cases, then link to the performance 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
Expand All @@ -45,7 +54,7 @@

- 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
Expand All @@ -56,20 +65,133 @@

- Your application relies on other asynchronous libraries or frameworks, such as FastAPI

Performance Benchmarks
~~~~~~~~~~~~~~~~~~~~~~

The following table shows the performance benchmarks for different tasks
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A short blurb to explain that in almost every case, the new asynchronous API performs better seems helpful here.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 I was just going to add a comment for the same thing

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.
{+driver-async+} API. We strongly recommend that Motor users migrate to
the {+driver-async+} API while Motor is still supported.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a date


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
Expand All @@ -87,26 +209,22 @@
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
Expand All @@ -115,13 +233,13 @@
.. 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
Expand All @@ -132,7 +250,7 @@
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:
Expand All @@ -142,11 +260,11 @@
- 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.
Expand All @@ -163,7 +281,7 @@
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::
Expand All @@ -173,5 +291,5 @@
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>`__.
15 changes: 15 additions & 0 deletions source/reference/release-notes.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>`
Expand All @@ -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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- The {+driver-async+} API is generally available. To learn how to migrate
to the {+driver-async+} API, see the :ref:`pymongo-async-migration` guide.
- 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
Expand Down
Loading