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

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/cursor.py

@@ -1263,10 +1263,14 @@ async def next(self) -> _DocumentType:
             self._exhaust_checked = True
             await self._supports_exhaust()
         if self._empty:
+            if self._cursor_type == CursorType.NON_TAILABLE:
+                await self.close()
             raise StopAsyncIteration
         if len(self._data) or await self._refresh():
             return self._data.popleft()
         else:
+            if self._cursor_type == CursorType.NON_TAILABLE:
+                await self.close()
             raise StopAsyncIteration
 
     async def _next_batch(self, result: list, total: Optional[int] = None) -> bool:  # type: ignore[type-arg]

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/cursor.py

@@ -1261,10 +1261,14 @@ def next(self) -> _DocumentType:
             self._exhaust_checked = True
             self._supports_exhaust()
         if self._empty:
+            if self._cursor_type == CursorType.NON_TAILABLE:
+                self.close()
             raise StopIteration
         if len(self._data) or self._refresh():
             return self._data.popleft()
         else:
+            if self._cursor_type == CursorType.NON_TAILABLE:
+                self.close()
             raise StopIteration
 
     def _next_batch(self, result: list, total: Optional[int] = None) -> bool:  # type: ignore[type-arg]

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