From 17a8154f661433bffbe2bf95de4fe4169c3319fa Mon Sep 17 00:00:00 2001
From: Noah Stapp <noah.stapp@mongodb.com>
Date: Wed, 31 Jul 2024 13:18:04 -0700
Subject: [PATCH] PYTHON-4594 - Add to_list documentation (#1757)

---
 doc/changelog.rst                      |  6 ++++++
 pymongo/asynchronous/command_cursor.py | 10 ++++++++++
 pymongo/asynchronous/cursor.py         | 10 ++++++++++
 pymongo/synchronous/command_cursor.py  | 10 ++++++++++
 pymongo/synchronous/cursor.py          | 10 ++++++++++
 5 files changed, 46 insertions(+)

diff --git a/doc/changelog.rst b/doc/changelog.rst
index 420c6c6de..d14a466cd 100644
--- a/doc/changelog.rst
+++ b/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
 ...............
diff --git a/pymongo/asynchronous/command_cursor.py b/pymongo/asynchronous/command_cursor.py
index dac9a27a2..9816ccaaf 100644
--- a/pymongo/asynchronous/command_cursor.py
+++ b/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):
diff --git a/pymongo/asynchronous/cursor.py b/pymongo/asynchronous/cursor.py
index fd288c710..fa4431622 100644
--- a/pymongo/asynchronous/cursor.py
+++ b/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):
diff --git a/pymongo/synchronous/command_cursor.py b/pymongo/synchronous/command_cursor.py
index d7a19c36b..1cd4d8694 100644
--- a/pymongo/synchronous/command_cursor.py
+++ b/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):
diff --git a/pymongo/synchronous/cursor.py b/pymongo/synchronous/cursor.py
index e00c33d90..652af606c 100644
--- a/pymongo/synchronous/cursor.py
+++ b/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):