PYTHON-3606 - Document best practice for closing MongoClients and cursors

Author: NoahStapp

pymongo/asynchronous/collection.py

@@ -1776,6 +1776,13 @@ def find(self, *args: Any, **kwargs: Any) -> AsyncCursor[_DocumentType]:
         improper type. Returns an instance of
         :class:`~pymongo.asynchronous.cursor.AsyncCursor` corresponding to this query.
 
+        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`.
 

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::
+
+            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

pymongo/synchronous/collection.py

@@ -1775,6 +1775,13 @@ def find(self, *args: Any, **kwargs: Any) -> Cursor[_DocumentType]:
         improper type. Returns an instance of
         :class:`~pymongo.cursor.Cursor` corresponding to this query.
 
+        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`.
 

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