Merge branch 'master' into PYTHON-5215

Author: blink1073

.evergreen/generated_configs/variants.yml

@@ -535,55 +535,71 @@ buildvariants:
     display_name: "* MongoDB v4.2"
     run_on:
       - rhel87-small
+    expansions:
+      VERSION: "4.2"
     tags: [coverage_tag]
   - name: mongodb-v4.4
     tasks:
       - name: .server-version
     display_name: "* MongoDB v4.4"
     run_on:
       - rhel87-small
+    expansions:
+      VERSION: "4.4"
     tags: [coverage_tag]
   - name: mongodb-v5.0
     tasks:
       - name: .server-version
     display_name: "* MongoDB v5.0"
     run_on:
       - rhel87-small
+    expansions:
+      VERSION: "5.0"
     tags: [coverage_tag]
   - name: mongodb-v6.0
     tasks:
       - name: .server-version
     display_name: "* MongoDB v6.0"
     run_on:
       - rhel87-small
+    expansions:
+      VERSION: "6.0"
     tags: [coverage_tag]
   - name: mongodb-v7.0
     tasks:
       - name: .server-version
     display_name: "* MongoDB v7.0"
     run_on:
       - rhel87-small
+    expansions:
+      VERSION: "7.0"
     tags: [coverage_tag]
   - name: mongodb-v8.0
     tasks:
       - name: .server-version
     display_name: "* MongoDB v8.0"
     run_on:
       - rhel87-small
+    expansions:
+      VERSION: "8.0"
     tags: [coverage_tag]
   - name: mongodb-rapid
     tasks:
       - name: .server-version
     display_name: "* MongoDB rapid"
     run_on:
       - rhel87-small
+    expansions:
+      VERSION: rapid
     tags: [coverage_tag]
   - name: mongodb-latest
     tasks:
       - name: .server-version
     display_name: "* MongoDB latest"
     run_on:
       - rhel87-small
+    expansions:
+      VERSION: latest
     tags: [coverage_tag]
 
   # Stable api tests

.evergreen/scripts/generate_config.py

@@ -74,7 +74,11 @@ def create_server_version_variants() -> list[BuildVariant]:
     for version in ALL_VERSIONS:
         display_name = get_variant_name("* MongoDB", version=version)
         variant = create_variant(
-            [".server-version"], display_name, host=DEFAULT_HOST, tags=["coverage_tag"]
+            [".server-version"],
+            display_name,
+            version=version,
+            host=DEFAULT_HOST,
+            tags=["coverage_tag"],
         )
         variants.append(variant)
     return variants

pymongo/asynchronous/collection.py

@@ -1776,6 +1776,15 @@ def find(self, *args: Any, **kwargs: Any) -> AsyncCursor[_DocumentType]:
         improper type. Returns an instance of
         :class:`~pymongo.asynchronous.cursor.AsyncCursor` corresponding to this query.
 
+        Cursors are closed automatically when they are exhausted (the last batch of data is retrieved from the database).
+        If a cursor is not exhausted, it will be closed automatically upon garbage collection, which leaves resources open but unused for a potentially long period of time.
+        To avoid this, best practice is to call :meth:`AsyncCursor.close` when the cursor is no longer needed,
+        or use the cursor in a with statement::
+
+            async with collection.find() as cursor:
+                async for doc in cursor:
+                    print(doc)
+
         The :meth:`find` method obeys the :attr:`read_preference` of
         this :class:`AsyncCollection`.
 
@@ -2503,6 +2512,15 @@ async def list_indexes(
           ...
           SON([('v', 2), ('key', SON([('_id', 1)])), ('name', '_id_')])
 
+        Cursors are closed automatically when they are exhausted (the last batch of data is retrieved from the database).
+        If a cursor is not exhausted, it will be closed automatically upon garbage collection, which leaves resources open but unused for a potentially long period of time.
+        To avoid this, best practice is to call :meth:`AsyncCursor.close` when the cursor is no longer needed,
+        or use the cursor in a with statement::
+
+            async with await collection.list_indexes() as cursor:
+                async for index in cursor:
+                    print(index)
+
         :param session: a
             :class:`~pymongo.asynchronous.client_session.AsyncClientSession`.
         :param comment: A user-provided comment to attach to this
@@ -2620,6 +2638,15 @@ async def list_search_indexes(
     ) -> AsyncCommandCursor[Mapping[str, Any]]:
         """Return a cursor over search indexes for the current collection.
 
+        Cursors are closed automatically when they are exhausted (the last batch of data is retrieved from the database).
+        If a cursor is not exhausted, it will be closed automatically upon garbage collection, which leaves resources open but unused for a potentially long period of time.
+        To avoid this, best practice is to call :meth:`AsyncCursor.close` when the cursor is no longer needed,
+        or use the cursor in a with statement::
+
+            async with await collection.list_search_indexes() as cursor:
+                async for index in cursor:
+                    print(index)
+
         :param name: If given, the name of the index to search
             for.  Only indexes with matching index names will be returned.
             If not given, all search indexes for the current collection
@@ -2922,6 +2949,15 @@ async def aggregate(
         .. note:: The :attr:`~pymongo.asynchronous.collection.AsyncCollection.write_concern` of
            this collection is automatically applied to this operation.
 
+        Cursors are closed automatically when they are exhausted (the last batch of data is retrieved from the database).
+        If a cursor is not exhausted, it will be closed automatically upon garbage collection, which leaves resources open but unused for a potentially long period of time.
+        To avoid this, best practice is to call :meth:`AsyncCursor.close` when the cursor is no longer needed,
+        or use the cursor in a with statement::
+
+            async with await collection.aggregate() as cursor:
+                async for operation in cursor:
+                    print(operation)
+
         :param pipeline: a list of aggregation pipeline stages
         :param session: a
             :class:`~pymongo.asynchronous.client_session.AsyncClientSession`.

pymongo/asynchronous/database.py

@@ -643,15 +643,20 @@ async def aggregate(
         .. code-block:: python
 
            # Lists all operations currently running on the server.
-           with client.admin.aggregate([{"$currentOp": {}}]) as cursor:
-               for operation in cursor:
+           async with await client.admin.aggregate([{"$currentOp": {}}]) as cursor:
+               async for operation in cursor:
                    print(operation)
 
         The :meth:`aggregate` method obeys the :attr:`read_preference` of this
         :class:`AsyncDatabase`, except when ``$out`` or ``$merge`` are used, in
         which case  :attr:`~pymongo.read_preferences.ReadPreference.PRIMARY`
         is used.
 
+        Cursors are closed automatically when they are exhausted (the last batch of data is retrieved from the database).
+        If a cursor is not exhausted, it will be closed automatically upon garbage collection, which leaves resources open but unused for a potentially long period of time.
+        To avoid this, best practice is to call :meth:`AsyncCursor.close` when the cursor is no longer needed,
+        or use the cursor in a with statement.
+
         .. note:: This method does not support the 'explain' option. Please
            use :meth:`~pymongo.asynchronous.database.AsyncDatabase.command` instead.
 
@@ -1154,6 +1159,15 @@ async def list_collections(
     ) -> AsyncCommandCursor[MutableMapping[str, Any]]:
         """Get a cursor over the collections of this database.
 
+        Cursors are closed automatically when they are exhausted (the last batch of data is retrieved from the database).
+        If a cursor is not exhausted, it will be closed automatically upon garbage collection, which leaves resources open but unused for a potentially long period of time.
+        To avoid this, best practice is to call :meth:`AsyncCursor.close` when the cursor is no longer needed,
+        or use the cursor in a with statement::
+
+            async with await database.list_collections() as cursor:
+                async for collection in cursor:
+                    print(collection)
+
         :param session: a
             :class:`~pymongo.asynchronous.client_session.AsyncClientSession`.
         :param filter:  A query document to filter the list of

pymongo/asynchronous/mongo_client.py

@@ -202,6 +202,12 @@ def __init__(
         exception (recognizing that the operation failed) and then continue to
         execute.
 
+        Best practice is to call :meth:`AsyncMongoClient.close` when the client is no longer needed,
+        or use the client in a with statement::
+
+            async with AsyncMongoClient(url) as client:
+                # Use client here.
+
         The `host` parameter can be a full `mongodb URI
         <https://dochub.mongodb.org/core/connections>`_, in addition to
         a simple hostname. It can also be a list of hostnames but no more
@@ -2345,6 +2351,15 @@ async def list_databases(
     ) -> AsyncCommandCursor[dict[str, Any]]:
         """Get a cursor over the databases of the connected server.
 
+        Cursors are closed automatically when they are exhausted (the last batch of data is retrieved from the database).
+        If a cursor is not exhausted, it will be closed automatically upon garbage collection, which leaves resources open but unused for a potentially long period of time.
+        To avoid this, best practice is to call :meth:`AsyncCursor.close` when the cursor is no longer needed,
+        or use the cursor in a with statement::
+
+            async with await client.list_databases() as cursor:
+                async for database in cursor:
+                    print(database)
+
         :param session: a
             :class:`~pymongo.asynchronous.client_session.AsyncClientSession`.
         :param comment: A user-provided comment to attach to this

pymongo/synchronous/collection.py

@@ -1775,6 +1775,15 @@ def find(self, *args: Any, **kwargs: Any) -> Cursor[_DocumentType]:
         improper type. Returns an instance of
         :class:`~pymongo.cursor.Cursor` corresponding to this query.
 
+        Cursors are closed automatically when they are exhausted (the last batch of data is retrieved from the database).
+        If a cursor is not exhausted, it will be closed automatically upon garbage collection, which leaves resources open but unused for a potentially long period of time.
+        To avoid this, best practice is to call :meth:`Cursor.close` when the cursor is no longer needed,
+        or use the cursor in a with statement::
+
+            with collection.find() as cursor:
+                for doc in cursor:
+                    print(doc)
+
         The :meth:`find` method obeys the :attr:`read_preference` of
         this :class:`Collection`.
 
@@ -2500,6 +2509,15 @@ def list_indexes(
           ...
           SON([('v', 2), ('key', SON([('_id', 1)])), ('name', '_id_')])
 
+        Cursors are closed automatically when they are exhausted (the last batch of data is retrieved from the database).
+        If a cursor is not exhausted, it will be closed automatically upon garbage collection, which leaves resources open but unused for a potentially long period of time.
+        To avoid this, best practice is to call :meth:`Cursor.close` when the cursor is no longer needed,
+        or use the cursor in a with statement::
+
+            with collection.list_indexes() as cursor:
+                for index in cursor:
+                    print(index)
+
         :param session: a
             :class:`~pymongo.client_session.ClientSession`.
         :param comment: A user-provided comment to attach to this
@@ -2617,6 +2635,15 @@ def list_search_indexes(
     ) -> CommandCursor[Mapping[str, Any]]:
         """Return a cursor over search indexes for the current collection.
 
+        Cursors are closed automatically when they are exhausted (the last batch of data is retrieved from the database).
+        If a cursor is not exhausted, it will be closed automatically upon garbage collection, which leaves resources open but unused for a potentially long period of time.
+        To avoid this, best practice is to call :meth:`Cursor.close` when the cursor is no longer needed,
+        or use the cursor in a with statement::
+
+            with collection.list_search_indexes() as cursor:
+                for index in cursor:
+                    print(index)
+
         :param name: If given, the name of the index to search
             for.  Only indexes with matching index names will be returned.
             If not given, all search indexes for the current collection
@@ -2915,6 +2942,15 @@ def aggregate(
         .. note:: The :attr:`~pymongo.collection.Collection.write_concern` of
            this collection is automatically applied to this operation.
 
+        Cursors are closed automatically when they are exhausted (the last batch of data is retrieved from the database).
+        If a cursor is not exhausted, it will be closed automatically upon garbage collection, which leaves resources open but unused for a potentially long period of time.
+        To avoid this, best practice is to call :meth:`Cursor.close` when the cursor is no longer needed,
+        or use the cursor in a with statement::
+
+            with collection.aggregate() as cursor:
+                for operation in cursor:
+                    print(operation)
+
         :param pipeline: a list of aggregation pipeline stages
         :param session: a
             :class:`~pymongo.client_session.ClientSession`.

pymongo/synchronous/database.py

@@ -652,6 +652,11 @@ def aggregate(
         which case  :attr:`~pymongo.read_preferences.ReadPreference.PRIMARY`
         is used.
 
+        Cursors are closed automatically when they are exhausted (the last batch of data is retrieved from the database).
+        If a cursor is not exhausted, it will be closed automatically upon garbage collection, which leaves resources open but unused for a potentially long period of time.
+        To avoid this, best practice is to call :meth:`Cursor.close` when the cursor is no longer needed,
+        or use the cursor in a with statement.
+
         .. note:: This method does not support the 'explain' option. Please
            use :meth:`~pymongo.database.Database.command` instead.
 
@@ -1148,6 +1153,15 @@ def list_collections(
     ) -> CommandCursor[MutableMapping[str, Any]]:
         """Get a cursor over the collections of this database.
 
+        Cursors are closed automatically when they are exhausted (the last batch of data is retrieved from the database).
+        If a cursor is not exhausted, it will be closed automatically upon garbage collection, which leaves resources open but unused for a potentially long period of time.
+        To avoid this, best practice is to call :meth:`Cursor.close` when the cursor is no longer needed,
+        or use the cursor in a with statement::
+
+            with database.list_collections() as cursor:
+                for collection in cursor:
+                    print(collection)
+
         :param session: a
             :class:`~pymongo.client_session.ClientSession`.
         :param filter:  A query document to filter the list of

pymongo/synchronous/mongo_client.py

@@ -199,6 +199,12 @@ def __init__(
         exception (recognizing that the operation failed) and then continue to
         execute.
 
+        Best practice is to call :meth:`MongoClient.close` when the client is no longer needed,
+        or use the client in a with statement::
+
+            with MongoClient(url) as client:
+                # Use client here.
+
         The `host` parameter can be a full `mongodb URI
         <https://dochub.mongodb.org/core/connections>`_, in addition to
         a simple hostname. It can also be a list of hostnames but no more
@@ -2335,6 +2341,15 @@ def list_databases(
     ) -> CommandCursor[dict[str, Any]]:
         """Get a cursor over the databases of the connected server.
 
+        Cursors are closed automatically when they are exhausted (the last batch of data is retrieved from the database).
+        If a cursor is not exhausted, it will be closed automatically upon garbage collection, which leaves resources open but unused for a potentially long period of time.
+        To avoid this, best practice is to call :meth:`Cursor.close` when the cursor is no longer needed,
+        or use the cursor in a with statement::
+
+            with client.list_databases() as cursor:
+                for database in cursor:
+                    print(database)
+
         :param session: a
             :class:`~pymongo.client_session.ClientSession`.
         :param comment: A user-provided comment to attach to this

pyproject.toml

@@ -55,7 +55,7 @@ gevent = ["gevent", "cffi>=2.0.0b1;python_version=='3.14'"]
 eventlet = ["eventlet"]
 coverage = [
     "pytest-cov",
-    "coverage>=5,<=7.10.2"
+    "coverage>=5,<=7.10.3"
 ]
 mockupdb = [
     "mockupdb@git+https://github.com/mongodb-labs/mongo-mockup-db@master"

test/asynchronous/test_pooling.py

@@ -21,7 +21,7 @@
 import socket
 import sys
 import time
-from test.asynchronous.utils import async_get_pool, async_joinall
+from test.asynchronous.utils import async_get_pool, async_joinall, flaky
 
 from bson.codec_options import DEFAULT_CODEC_OPTIONS
 from bson.son import SON
@@ -429,6 +429,7 @@ async def find_one():
         # maxConnecting = unbounded: 30+ connections in ~0.140+ seconds
         print(len(pool.conns))
 
+    @flaky(reason="PYTHON-5492")
     @async_client_context.require_failCommand_appName
     async def test_csot_timeout_message(self):
         client = await self.async_rs_or_single_client(appName="connectionTimeoutApp")