From: Harmon <Harmon758@gmail.com>
Date: Thu, 29 Apr 2021 09:02:55 +0000 (-0500)
Subject: Replace Cursor Tutorial with documentation for Cursor
X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=652fece7f78f90ea11f206b4a045a2450db42cc9;p=tweepy.git

Replace Cursor Tutorial with documentation for Cursor
---

diff --git a/docs/cursor_tutorial.rst b/docs/cursor_tutorial.rst
deleted file mode 100644
index 9aef25e..0000000
--- a/docs/cursor_tutorial.rst
+++ /dev/null
@@ -1,94 +0,0 @@
-.. _cursor_tutorial:
-
-***************
-Cursor Tutorial
-***************
-
-This tutorial describes details on pagination with Cursor objects.
-
-Introduction
-============
-
-We use pagination a lot in Twitter API development. Iterating through
-timelines, user lists, direct messages, etc. In order to perform
-pagination, we must supply a page/cursor parameter with each of our
-requests. The problem here is this requires a lot of boiler plate code
-just to manage the pagination loop. To help make pagination easier and
-require less code, Tweepy has the Cursor object.
-
-Old way vs Cursor way
-=====================
-
-First let's demonstrate iterating the statuses in the authenticated
-user's timeline. Here is how we would do it the "old way" before the
-Cursor object was introduced::
-
-   page = 1
-   while True:
-       statuses = api.user_timeline(page=page)
-       if statuses:
-           for status in statuses:
-               # process status here
-               process_status(status)
-       else:
-           # All done
-           break
-       page += 1  # next page
-
-As you can see, we must manage the "page" parameter manually in our
-pagination loop. Now here is the version of the code using the Cursor
-object::
-
-   for status in tweepy.Cursor(api.user_timeline).items():
-       # process status here
-       process_status(status)
-
-Now that looks much better! Cursor handles all the pagination work for
-us behind the scenes, so our code can now focus entirely on processing
-the results.
-
-Passing parameters into the API method
-======================================
-
-What if you need to pass in parameters to the API method?
-
-.. code-block :: python
-
-   api.user_timeline(id="twitter")
-
-Since we pass Cursor the callable, we can not pass the parameters
-directly into the method. Instead we pass the parameters into the
-Cursor constructor method::
-
-   tweepy.Cursor(api.user_timeline, id="twitter")
-
-Now Cursor will pass the parameter into the method for us whenever it
-makes a request.
-
-Items or Pages
-==============
-
-So far we have just demonstrated pagination iterating per
-item. What if instead you want to process per page of results? You
-would use the pages() method::
-
-   for page in tweepy.Cursor(api.user_timeline).pages():
-       # page is a list of statuses
-       process_page(page)
-
-
-Limits
-======
-
-What if you only want n items or pages returned? You pass into the
-items() or pages() methods the limit you want to impose.
-
-.. code-block :: python
-
-   # Only iterate through the first 200 statuses
-   for status in tweepy.Cursor(api.user_timeline).items(200):
-       process_status(status)
-
-   # Only iterate through the first 3 pages
-   for page in tweepy.Cursor(api.user_timeline).pages(3):
-       process_page(page)
diff --git a/docs/index.rst b/docs/index.rst
index f5109e3..1618a50 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -15,7 +15,6 @@ Contents:
    getting_started.rst
    auth_tutorial.rst
    code_snippet.rst
-   cursor_tutorial.rst
    api.rst
    client.rst
    models.rst
diff --git a/docs/pagination.rst b/docs/pagination.rst
index 132860d..e32413e 100644
--- a/docs/pagination.rst
+++ b/docs/pagination.rst
@@ -6,6 +6,29 @@
 Pagination
 **********
 
+API v1.1
+========
+
+.. autoclass:: Cursor
+    :members:
+
+Example
+-------
+
+::
+
+    import tweepy
+
+    auth = tweepy.AppAuthHandler("Consumer Key here", "Consumer Secret here")
+    api = tweepy.API(auth)
+
+    for status in tweepy.Cursor(api.search, "Tweepy", count=100).items(250):
+        print(status.id)
+
+    for page in tweepy.Cursor(api.followers, screen_name="TwitterDev",
+                              count=200).pages(5):
+        print(len(page))
+
 API v2
 ======
 
diff --git a/tweepy/cursor.py b/tweepy/cursor.py
index a9a70f0..78c00b3 100644
--- a/tweepy/cursor.py
+++ b/tweepy/cursor.py
@@ -7,7 +7,18 @@ from tweepy.parsers import ModelParser, RawParser
 
 
 class Cursor:
-    """Pagination helper class"""
+    """:class:`Cusor` can be used to paginate for any :class:`API` methods that
+    support pagination
+
+    Parameters
+    ----------
+    method
+        :class:`Client` method to paginate for
+    args
+        Positional arguments to pass to ``method``
+    kwargs
+        Keyword arguments to pass to ``method``
+    """
 
     def __init__(self, method, *args, **kwargs):
         if hasattr(method, 'pagination_mode'):
@@ -27,13 +38,36 @@ class Cursor:
             raise TweepyException('This method does not perform pagination')
 
     def pages(self, limit=0):
-        """Return iterator for pages"""
+        """Retrieve the page for each request
+
+        Parameters
+        ----------
+        limit
+            Maximum number of pages to iterate over
+
+        Returns
+        -------
+        CursorIterator or DMCursorIterator or IdIterator or NextIterator or \
+        PageIterator
+            Iterator to iterate through pages
+        """
         if limit > 0:
             self.iterator.limit = limit
         return self.iterator
 
     def items(self, limit=0):
-        """Return iterator for items in each page"""
+        """Retrieve the items in each page/request
+
+        Parameters
+        ----------
+        limit
+            Maximum number of items to iterate over
+
+        Returns
+        -------
+        ItemIterator
+            Iterator to iterate through items
+        """
         i = ItemIterator(self.iterator)
         i.limit = limit
         return i