From 652fece7f78f90ea11f206b4a045a2450db42cc9 Mon Sep 17 00:00:00 2001 From: Harmon Date: Thu, 29 Apr 2021 04:02:55 -0500 Subject: [PATCH] Replace Cursor Tutorial with documentation for Cursor --- docs/cursor_tutorial.rst | 94 ---------------------------------------- docs/index.rst | 1 - docs/pagination.rst | 23 ++++++++++ tweepy/cursor.py | 40 +++++++++++++++-- 4 files changed, 60 insertions(+), 98 deletions(-) delete mode 100644 docs/cursor_tutorial.rst 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 -- 2.25.1