PYTHON-4594 - Add to_list documentation (#1757)

doc/changelog.rst

@@ -11,6 +11,12 @@ PyMongo 4.9 brings a number of improvements including:
 - Add support for :attr:`~pymongo.encryption.Algorithm.RANGE` and deprecate
   :attr:`~pymongo.encryption.Algorithm.RANGEPREVIEW`.
 - pymongocrypt>=1.10 is now required for :ref:`In-Use Encryption` support.
+- Added :meth:`~pymongo.cursor.Cursor.to_list` to :class:`~pymongo.cursor.Cursor`,
+  :class:`~pymongo.command_cursor.CommandCursor`,
+  :class:`~pymongo.asynchronous.cursor.AsyncCursor`,
+  and :class:`~pymongo.asynchronous.command_cursor.AsyncCommandCursor`
+  as an asynchronous-friendly alternative to ``list(cursor)``.
+
 
 Issues Resolved
 ...............

pymongo/asynchronous/command_cursor.py

@@ -382,6 +382,16 @@ class AsyncCommandCursor(Generic[_DocumentType]):
         await self.close()
 
     async def to_list(self) -> list[_DocumentType]:
+        """Converts the contents of this cursor to a list more efficiently than ``[doc async for doc in cursor]``.
+
+        To use::
+
+          >>> await cursor.to_list()
+
+        If the cursor is empty or has no more results, an empty list will be returned.
+
+        .. versionadded:: 4.9
+        """
         res: list[_DocumentType] = []
         while self.alive:
             if not await self._next_batch(res):

pymongo/asynchronous/cursor.py

@@ -1287,6 +1287,16 @@ class AsyncCursor(Generic[_DocumentType]):
         await self.close()
 
     async def to_list(self) -> list[_DocumentType]:
+        """Converts the contents of this cursor to a list more efficiently than ``[doc async for doc in cursor]``.
+
+        To use::
+
+          >>> await cursor.to_list()
+
+        If the cursor is empty or has no more results, an empty list will be returned.
+
+        .. versionadded:: 4.9
+        """
         res: list[_DocumentType] = []
         while self.alive:
             if not await self._next_batch(res):

pymongo/synchronous/command_cursor.py

@@ -382,6 +382,16 @@ class CommandCursor(Generic[_DocumentType]):
         self.close()
 
     def to_list(self) -> list[_DocumentType]:
+        """Converts the contents of this cursor to a list more efficiently than ``[doc async for doc in cursor]``.
+
+        To use::
+
+          >>> await cursor.to_list()
+
+        If the cursor is empty or has no more results, an empty list will be returned.
+
+        .. versionadded:: 4.9
+        """
         res: list[_DocumentType] = []
         while self.alive:
             if not self._next_batch(res):

pymongo/synchronous/cursor.py

@@ -1285,6 +1285,16 @@ class Cursor(Generic[_DocumentType]):
         self.close()
 
     def to_list(self) -> list[_DocumentType]:
+        """Converts the contents of this cursor to a list more efficiently than ``[doc async for doc in cursor]``.
+
+        To use::
+
+          >>> await cursor.to_list()
+
+        If the cursor is empty or has no more results, an empty list will be returned.
+
+        .. versionadded:: 4.9
+        """
         res: list[_DocumentType] = []
         while self.alive:
             if not self._next_batch(res):