PYTHON-4592 - Synchronize inline examples and docstrings (mongodb#1756)

Author: NoahStapp

pymongo/asynchronous/aggregation.py

@@ -40,8 +40,8 @@ class _AggregationCommand:
     """The internal abstract base class for aggregation cursors.
 
     Should not be called directly by application developers. Use
-    :meth:`pymongo.collection.AsyncCollection.aggregate`, or
-    :meth:`pymongo.database.AsyncDatabase.aggregate` instead.
+    :meth:`pymongo.asynchronous.collection.AsyncCollection.aggregate`, or
+    :meth:`pymongo.asynchronous.database.AsyncDatabase.aggregate` instead.
     """
 
     def __init__(

pymongo/asynchronous/change_stream.py

@@ -91,9 +91,9 @@ class AsyncChangeStream(Generic[_DocumentType]):
     """The internal abstract base class for change stream cursors.
 
     Should not be called directly by application developers. Use
-    :meth:`pymongo.collection.AsyncCollection.watch`,
-    :meth:`pymongo.database.AsyncDatabase.watch`, or
-    :meth:`pymongo.mongo_client.AsyncMongoClient.watch` instead.
+    :meth:`pymongo.asynchronous.collection.AsyncCollection.watch`,
+    :meth:`pymongo.asynchronous.database.AsyncDatabase.watch`, or
+    :meth:`pymongo.asynchronous.mongo_client.AsyncMongoClient.watch` instead.
 
     .. versionadded:: 3.6
     .. seealso:: The MongoDB documentation on `changeStreams <https://mongodb.com/docs/manual/changeStreams/>`_.
@@ -166,7 +166,7 @@ def _aggregation_command_class(self) -> Type[_AggregationCommand]:
     @property
     def _client(self) -> AsyncMongoClient:
         """The client against which the aggregation commands for
-        this ChangeStream will be run.
+        this AsyncChangeStream will be run.
         """
         raise NotImplementedError
 
@@ -204,7 +204,7 @@ def _command_options(self) -> dict[str, Any]:
         return options
 
     def _aggregation_pipeline(self) -> list[dict[str, Any]]:
-        """Return the full aggregation pipeline for this ChangeStream."""
+        """Return the full aggregation pipeline for this AsyncChangeStream."""
         options = self._change_stream_options()
         full_pipeline: list = [{"$changeStream": options}]
         full_pipeline.extend(self._pipeline)
@@ -238,7 +238,7 @@ def _process_result(self, result: Mapping[str, Any], conn: AsyncConnection) -> N
     async def _run_aggregation_cmd(
         self, session: Optional[AsyncClientSession], explicit_session: bool
     ) -> AsyncCommandCursor:
-        """Run the full aggregation pipeline for this ChangeStream and return
+        """Run the full aggregation pipeline for this AsyncChangeStream and return
         the corresponding AsyncCommandCursor.
         """
         cmd = self._aggregation_command_class(
@@ -272,7 +272,7 @@ async def _resume(self) -> None:
         self._cursor = await self._create_cursor()
 
     async def close(self) -> None:
-        """Close this ChangeStream."""
+        """Close this AsyncChangeStream."""
         self._closed = True
         await self._cursor.close()
 
@@ -299,27 +299,27 @@ async def next(self) -> _DocumentType:
             try:
                 resume_token = None
                 pipeline = [{'$match': {'operationType': 'insert'}}]
-                async with db.collection.watch(pipeline) as stream:
+                async with await db.collection.watch(pipeline) as stream:
                     async for insert_change in stream:
                         print(insert_change)
                         resume_token = stream.resume_token
             except pymongo.errors.PyMongoError:
-                # The ChangeStream encountered an unrecoverable error or the
+                # The AsyncChangeStream encountered an unrecoverable error or the
                 # resume attempt failed to recreate the cursor.
                 if resume_token is None:
                     # There is no usable resume token because there was a
-                    # failure during ChangeStream initialization.
+                    # failure during AsyncChangeStream initialization.
                     logging.error('...')
                 else:
-                    # Use the interrupted ChangeStream's resume token to create
-                    # a new ChangeStream. The new stream will continue from the
+                    # Use the interrupted AsyncChangeStream's resume token to create
+                    # a new AsyncChangeStream. The new stream will continue from the
                     # last seen insert change without missing any events.
-                    async with db.collection.watch(
+                    async with await db.collection.watch(
                             pipeline, resume_after=resume_token) as stream:
                         async for insert_change in stream:
                             print(insert_change)
 
-        Raises :exc:`StopIteration` if this ChangeStream is closed.
+        Raises :exc:`StopIteration` if this AsyncChangeStream is closed.
         """
         while self.alive:
             doc = await self.try_next()
@@ -348,10 +348,10 @@ async def try_next(self) -> Optional[_DocumentType]:
         This method returns the next change document without waiting
         indefinitely for the next change. For example::
 
-            async with db.collection.watch() as stream:
+            async with await db.collection.watch() as stream:
                 while stream.alive:
                     change = await stream.try_next()
-                    # Note that the ChangeStream's resume token may be updated
+                    # Note that the AsyncChangeStream's resume token may be updated
                     # even when no changes are returned.
                     print("Current resume token: %r" % (stream.resume_token,))
                     if change is not None:
@@ -447,7 +447,7 @@ class AsyncCollectionChangeStream(AsyncChangeStream[_DocumentType]):
     """A change stream that watches changes on a single collection.
 
     Should not be called directly by application developers. Use
-    helper method :meth:`pymongo.collection.AsyncCollection.watch` instead.
+    helper method :meth:`pymongo.asynchronous.collection.AsyncCollection.watch` instead.
 
     .. versionadded:: 3.7
     """
@@ -467,7 +467,7 @@ class AsyncDatabaseChangeStream(AsyncChangeStream[_DocumentType]):
     """A change stream that watches changes on all collections in a database.
 
     Should not be called directly by application developers. Use
-    helper method :meth:`pymongo.database.AsyncDatabase.watch` instead.
+    helper method :meth:`pymongo.asynchronous.database.AsyncDatabase.watch` instead.
 
     .. versionadded:: 3.7
     """
@@ -487,7 +487,7 @@ class AsyncClusterChangeStream(AsyncDatabaseChangeStream[_DocumentType]):
     """A change stream that watches changes on all collections in the cluster.
 
     Should not be called directly by application developers. Use
-    helper method :meth:`pymongo.mongo_client.AsyncMongoClient.watch` instead.
+    helper method :meth:`pymongo.asynchronous.mongo_client.AsyncMongoClient.watch` instead.
 
     .. versionadded:: 3.7
     """

pymongo/asynchronous/client_session.py

@@ -102,7 +102,7 @@
 
 MongoDB 5.0 adds support for snapshot reads. Snapshot reads are requested by
 passing the ``snapshot`` option to
-:meth:`~pymongo.mongo_client.AsyncMongoClient.start_session`.
+:meth:`~pymongo.asynchronous.mongo_client.AsyncMongoClient.start_session`.
 If ``snapshot`` is True, all read operations that use this session read data
 from the same snapshot timestamp. The server chooses the latest
 majority-committed snapshot timestamp when executing the first read operation
@@ -123,11 +123,11 @@
 Snapshot reads sessions are incompatible with ``causal_consistency=True``.
 Only the following read operations are supported in a snapshot reads session:
 
-- :meth:`~pymongo.collection.AsyncCollection.find`
-- :meth:`~pymongo.collection.AsyncCollection.find_one`
-- :meth:`~pymongo.collection.AsyncCollection.aggregate`
-- :meth:`~pymongo.collection.AsyncCollection.count_documents`
-- :meth:`~pymongo.collection.AsyncCollection.distinct` (on unsharded collections)
+- :meth:`~pymongo.asynchronous.collection.AsyncCollection.find`
+- :meth:`~pymongo.asynchronous.collection.AsyncCollection.find_one`
+- :meth:`~pymongo.asynchronous.collection.AsyncCollection.aggregate`
+- :meth:`~pymongo.asynchronous.collection.AsyncCollection.count_documents`
+- :meth:`~pymongo.asynchronous.collection.AsyncCollection.distinct` (on unsharded collections)
 
 Classes
 =======
@@ -492,7 +492,7 @@ class AsyncClientSession:
 
     Should not be initialized directly by application developers - to create a
     :class:`AsyncClientSession`, call
-    :meth:`~pymongo.mongo_client.AsyncMongoClient.start_session`.
+    :meth:`~pymongo.asynchronous.mongo_client.AsyncMongoClient.start_session`.
     """
 
     def __init__(
@@ -550,7 +550,7 @@ async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
 
     @property
     def client(self) -> AsyncMongoClient:
-        """The :class:`~pymongo.mongo_client.AsyncMongoClient` this session was
+        """The :class:`~pymongo.asynchronous.mongo_client.AsyncMongoClient` this session was
         created from.
         """
         return self._client
@@ -898,7 +898,7 @@ def advance_cluster_time(self, cluster_time: Mapping[str, Any]) -> None:
         """Update the cluster time for this session.
 
         :param cluster_time: The
-            :data:`~pymongo.client_session.AsyncClientSession.cluster_time` from
+            :data:`~pymongo.asynchronous.client_session.AsyncClientSession.cluster_time` from
             another `AsyncClientSession` instance.
         """
         if not isinstance(cluster_time, _Mapping):
@@ -919,7 +919,7 @@ def advance_operation_time(self, operation_time: Timestamp) -> None:
         """Update the operation time for this session.
 
         :param operation_time: The
-            :data:`~pymongo.client_session.AsyncClientSession.operation_time` from
+            :data:`~pymongo.asynchronous.client_session.AsyncClientSession.operation_time` from
             another `AsyncClientSession` instance.
         """
         if not isinstance(operation_time, Timestamp):
@@ -1133,7 +1133,7 @@ def pop_all(self) -> list[_ServerSession]:
     def get_server_session(self, session_timeout_minutes: Optional[int]) -> _ServerSession:
         # Although the Driver Sessions Spec says we only clear stale sessions
         # in return_server_session, PyMongo can't take a lock when returning
-        # sessions from a __del__ method (like in Cursor.__die), so it can't
+        # sessions from a __del__ method (like in AsyncCursor.__die), so it can't
         # clear stale sessions there. In case many sessions were returned via
         # __del__, check for stale sessions here too.
         self._clear_stale(session_timeout_minutes)