PYTHON-894 - More doc clarifications for alive.

pymongo/command_cursor.py

@@ -147,11 +147,16 @@ def _refresh(self):
     def alive(self):
         """Does this cursor have the potential to return more data?
 
-        Even if :attr:`alive` is ``True``, :meth:`.next` can raise
+        Even if :attr:`alive` is ``True``, :meth:`next` can raise
         :exc:`StopIteration`. Best to use a for loop::
 
             for doc in collection.aggregate(pipeline):
                 print(doc)
+
+        .. note:: :attr:`alive` can be True while iterating a cursor from
+          a failed server. In this case :attr:`alive` will return False after
+          :meth:`next` fails to retrieve the next batch of results from the
+          server.
         """
         return bool(len(self.__data) or (not self.__killed))
 
@@ -172,8 +177,7 @@ def __iter__(self):
         return self
 
     def next(self):
-        """Advance the cursor.
-        """
+        """Advance the cursor."""
         if len(self.__data) or self._refresh():
             coll = self.__collection
             return coll.database._fix_outgoing(self.__data.popleft(), coll)

pymongo/cursor.py

@@ -942,6 +942,12 @@ def alive(self):
 
             for doc in collection.find():
                 print(doc)
+
+        .. note:: Even if :attr:`alive` is True, :meth:`next` can raise
+          :exc:`StopIteration`. :attr:`alive` can also be True while iterating
+          a cursor from a failed server. In this case :attr:`alive` will
+          return False after :meth:`next` fails to retrieve the next batch
+          of results from the server.
         """
         return bool(len(self.__data) or (not self.__killed))
 
@@ -969,7 +975,8 @@ def address(self):
     def __iter__(self):
         return self
 
-    def __next__(self):
+    def next(self):
+        """Advance the cursor."""
         if self.__empty:
             raise StopIteration
         _db = self.__collection.database
@@ -982,7 +989,7 @@ def __next__(self):
         else:
             raise StopIteration
 
-    next = __next__
+    __next__ = next
 
     def __enter__(self):
         return self