DOCSP-41887 Async Migration Guide #103

jordan-smith721 · 2024-08-30T19:36:14Z

Pull Request Info

JIRA - https://jira.mongodb.org/browse/DOCSP-41887
Staging -
https://deploy-preview-103--docs-pymongo.netlify.app/motor-async-migration/
https://deploy-preview-103--docs-pymongo.netlify.app/pymongo-to-async-guide

Self-Review Checklist

Is this free of any warnings or errors in the RST?
Did you run a spell-check?
Did you run a grammar-check?
Are all the links working?
Are the facets and meta keywords accurate?

netlify · 2024-08-30T19:36:31Z

✅ Deploy Preview for docs-pymongo ready!

Name	Link
🔨 Latest commit	`bf38a06`
🔍 Latest deploy log	https://app.netlify.com/sites/docs-pymongo/deploys/670e80f656934f000844f0aa
😎 Deploy Preview	https://deploy-preview-103--docs-pymongo.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

rustagir

a few things!

rustagir · 2024-09-06T18:21:19Z

source/index.txt

+Migrate to the {+driver-async+} Driver
+------------------------------------
+
+Learn how to migrate from {+driver-short+} or Motor to the {+driver-async+} driver in the


S: I think another sentence here could be useful before linking to the guide. Maybe you can mention the time period that this applies to?

Eg.
In Aug 2024, MongoDB released the PyMongo Async driver to unify PyMongo and Motor, the asynchronous MongoDB driver for Python.

Flagging this again, but also ok if you wanted to leave as is!

Oops, misread this the first time and applied it to the wrong area. Fixed!

source/pymongo-async-migration.txt

rustagir

approving as comments arent blocking but happy to re-review if needed!

rustagir · 2024-09-10T17:49:34Z

source/index.txt

+Migrate to the {+driver-async+} Driver
+------------------------------------
+
+Learn how to migrate from {+driver-short+} or Motor to the {+driver-async+} driver in the


Flagging this again, but also ok if you wanted to leave as is!

source/pymongo-async-migration.txt

rustagir · 2024-09-10T17:51:12Z

source/pymongo-async-migration.txt

+   * - ``AsyncMongoClient()``
+     - .. code-block:: python
+
+          from pymongo import AsyncMongoClient
+
+          client = AsyncMongoClient(...)


S: perhaps this should have its own subsection as its a constructor rather than a method?

I thought about that at first, but it seemed weird to be in its own table and it's related to the client so I figured it made sense here. Can change if anyone has strong feelings the other way though

source/pymongo-async-migration.txt

NoahStapp

First pass, I'll take another look tomorrow morning for a deeper dive on the technical details.

NoahStapp · 2024-09-10T19:41:59Z

source/index.txt

+
+In September 2024, MongoDB released the {+driver-async+} driver to unify {+driver-short+}
+and `Motor <https://www.mongodb.com/docs/drivers/motor/>`__, the asynchronous
+MongoDB driver for Python. Learn how to migrate from {+driver-short+} or Motor


We should be clear that the new Async API is a replacement for Motor specifically and that any existing users of PyMongo will only have to migrate if they want to switch to async.

NoahStapp · 2024-09-10T19:43:30Z

source/pymongo-async-migration.txt

+
+The {+driver-async+} driver 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


Same here, the word "migrate" seems a little confusing for existing PyMongo users. Is there a different wording we can use to make sure users understand that they only need to make changes if they want to use the new async API?

Reworded this after splitting pages

NoahStapp · 2024-09-10T19:44:16Z

source/pymongo-async-migration.txt

+- Add the ``await`` keyword to all asynchronous method calls.
+- If an asynchronous method is called within a function, mark the function as ``async``.
+
+The following sections describe how to implement the asynchronous API.


I'd also link to the official Python async docs here for some additional context.

NoahStapp · 2024-09-10T19:45:19Z

source/pymongo-async-migration.txt

+
+          from pymongo import AsyncMongoClient
+
+          AsyncMongoClient(...)


To use an AsyncMongoClient as a context manager users will have to do async with AsyncMongoClient(...) instead of with MongoClient(...).

ShaneHarvey · 2024-09-11T15:47:29Z

source/pymongo-async-migration.txt

+Migrate From Motor
+------------------
+
+The {+driver-async+} driver behaves nearly identically to the Motor library. In


This is a little misleading. Async PyMongo is (or should be) vastly superior to Motor in behavior both in terms of latency and throughput because Async Pymongo directly uses asyncio whereas Motor delegates all work to a thread pool.

Updated the wording here, let me know if that works better!

ShaneHarvey · 2024-09-11T15:48:51Z

source/pymongo-async-migration.txt

+
+          await collection.find_one_and_update(...)
+
+Migrate From Motor


I'd like to see the motor -> async pymongo migration as its own dedicated page. The pymongo sync -> async differences clutters the page for motor users.

Split the pages into two

NoahStapp

One clarifying suggestion, otherwise looks good!

NoahStapp · 2024-09-20T17:15:34Z

source/pymongo-to-async-guide.txt

+
+- Replace all uses of ``MongoClient`` with ``AsyncMongoClient``.
+- Add the ``await`` keyword to all asynchronous method calls.
+- If an asynchronous method is called within a function, mark the function as ``async``.


It's unclear that this last point is for functions that the user defines.

Good call. Updated

jordan-smith721 · 2024-09-26T12:50:05Z

@ShaneHarvey any other suggested changes on your end before I merge?

ShaneHarvey · 2024-09-26T19:15:07Z

source/index.txt

+Migrate from Motor to {+driver-async+}
+-------------------------------------
+
+In September 2024, MongoDB released the {+driver-async+} driver as a replacement


The Async PyMongo is released yes, but it's only in beta (ie experimental) and not ready for production use. We should make this loud and clear one every one of these pages.

ShaneHarvey · 2024-09-26T19:18:42Z

source/motor-async-migration.txt

+
+- ``GridOut.open()`` returns ``None``.
+- ``AsyncMongoClient.__init__()`` does not accept an ``io_loop`` parameter.
+- ``GridIn.set()`` does not accept a filename. Instead pass a file name by using the


@noah is this true? Does GridIn here refer to a motor class? The pymongo class is AsyncGridIn.

AsyncGridIn.set() does accept filenames.

These were from the original draft migration notes linked in the ticket. Should I delete the GridIn bullets?

@NoahStapp @ShaneHarvey

ShaneHarvey · 2024-09-26T19:18:55Z

source/motor-async-migration.txt

+
+The following Motor method signatures behave differently in the {+driver-async+} driver:
+
+- ``GridOut.open()`` returns ``None``.


Does GridOut here refer to a motor class? The pymongo class is AsyncGridOut.

ShaneHarvey · 2024-09-26T19:19:15Z

source/motor-async-migration.txt

+- ``AsyncMongoClient.__init__()`` does not accept an ``io_loop`` parameter.
+- ``GridIn.set()`` does not accept a filename. Instead pass a file name by using the
+  ``GridIn.filename`` attribute.
+- ``Cursor.each()`` does not exist in the {+driver-async+} driver.


Cursor -> AsyncCursor.

ShaneHarvey · 2024-09-26T19:20:25Z

source/motor-async-migration.txt

+- ``GridIn.set()`` does not accept a filename. Instead pass a file name by using the
+  ``GridIn.filename`` attribute.
+- ``Cursor.each()`` does not exist in the {+driver-async+} driver.
+- ``stream_to_handler()`` does not exist in the {+driver-async+} driver.


MotorGridOut.stream_to_handler()

ShaneHarvey · 2024-09-26T19:20:52Z

source/motor-async-migration.txt

+  ``GridIn.filename`` attribute.
+- ``Cursor.each()`` does not exist in the {+driver-async+} driver.
+- ``stream_to_handler()`` does not exist in the {+driver-async+} driver.
+- ``to_list(0)`` is not valid in the {+driver-async+} driver. Use


AsyncCursor.to_list(0)

ShaneHarvey · 2024-09-26T19:22:50Z

source/pymongo-to-async-guide.txt

+
+- Replace all uses of ``MongoClient`` with ``AsyncMongoClient``.
+- Add the ``await`` keyword to all asynchronous method calls.
+- If you call an asynchronous method inside of a function, mark the function as ``async``.


Add:

- A ``MongoClient`` is thread safe and can be used be many threads. A ``AsyncMongoClient`` is not thread safe and should only be used by a single event loop.

(cherry picked from commit acff81f)

draft start

c29250e

jordan-smith721 added 3 commits September 6, 2024 08:48

migration page

7a49198

edits

5e2d5a5

small edits

ca264a9

jordan-smith721 marked this pull request as ready for review September 6, 2024 17:25

jordan-smith721 changed the title ~~draft start~~ DOCSP-41887 Async Migration Guide Sep 6, 2024

rustagir requested changes Sep 6, 2024

View reviewed changes

jordan-smith721 added 4 commits September 10, 2024 07:00

Rea feedback

e36034b

typo

bc1a8a3

typo

3e9acc3

wrong source constant

edfff73

jordan-smith721 requested a review from rustagir September 10, 2024 14:30

rustagir approved these changes Sep 10, 2024

View reviewed changes

Rea feedback

3045f0d

NoahStapp suggested changes Sep 10, 2024

View reviewed changes

ShaneHarvey suggested changes Sep 11, 2024

View reviewed changes

jordan-smith721 added 3 commits September 20, 2024 09:35

split into two pages + feedback

6f728ce

toc

301ba14

fixes

6637b87

jordan-smith721 requested review from ShaneHarvey and NoahStapp September 20, 2024 17:06

NoahStapp suggested changes Sep 20, 2024

View reviewed changes

clarify bulletpoint

102c829

ShaneHarvey reviewed Sep 26, 2024

View reviewed changes

ShaneHarvey suggested changes Sep 26, 2024

View reviewed changes

jordan-smith721 added 2 commits September 30, 2024 06:56

feedback

afc9ddf

remove gridIn mentions

bf38a06

jordan-smith721 requested a review from ShaneHarvey October 15, 2024 14:50

ShaneHarvey approved these changes Oct 18, 2024

View reviewed changes

jordan-smith721 merged commit acff81f into mongodb:master Oct 22, 2024
4 of 5 checks passed

jordan-smith721 deleted the DOCSP-41887-pymongoasync-migration-guide branch October 22, 2024 14:07

jordan-smith721 added a commit that referenced this pull request Oct 22, 2024

DOCSP-41887 Async Migration Guide (#103)

dea3455

(cherry picked from commit acff81f)

jordan-smith721 added a commit that referenced this pull request Oct 22, 2024

DOCSP-41887 Async Migration Guide (#103)

f2e9b04

(cherry picked from commit acff81f)


		The following Motor method signatures behave differently in the {+driver-async+} driver:

		- ``GridOut.open()`` returns ``None``.

DOCSP-41887 Async Migration Guide #103

DOCSP-41887 Async Migration Guide #103

Uh oh!

Conversation

jordan-smith721 commented Aug 30, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Info

Self-Review Checklist

Uh oh!

netlify bot commented Aug 30, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for docs-pymongo ready!

Uh oh!

rustagir left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rustagir left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

NoahStapp left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

NoahStapp left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jordan-smith721 commented Sep 26, 2024

Uh oh!

ShaneHarvey Sep 26, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jordan-smith721 commented Aug 30, 2024 •

edited

Loading

netlify bot commented Aug 30, 2024 •

edited

Loading

ShaneHarvey Sep 26, 2024 •

edited

Loading