Add Code snippets tutorial.

Signed-off-by: Joshua Roesslein <jroesslein@gmail.com>

diff --git a/doc/cursor_tutorial.rst b/doc/cursor_tutorial.rst
new file mode 100644 (file)
index 0000000..2f19f5e
--- /dev/null
+++ b/doc/cursor_tutorial.rst
@@ -0,0 +1,93 @@
+.. _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 mange the pagination loop. To help mage pagination easier and
+require less code Tweepy has the Cursor object.
+
+Old way vs Cursor way
+---------------------
+
+First let's demonstrate iterating the statues in the authenticated
+user's timeline. Here is how we would do it the "old way" before
+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 Cursor
+object::
+
+   for status in 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 scene 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::
+
+   Cursor(api.user_timeline, id="twitter")
+
+Now Cursor will pass the parameter into the method for us when ever it
+makes a request.
+
+Items or Pages
+--------------
+
+So far we have just demonstrated pagination iterating per an
+item. What if instead you want to process per a page of results? You
+would use the pages() method::
+
+   for page in 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 Cursor(api.user_timeline).limit(200):
+       process_status(status)
+   
+   # Only iterate through the first 3 pages
+   for page in Cursor(api.user_timeline).pages(3):
+       process_page(page)

diff --git a/doc/index.rst b/doc/index.rst
index 230de251b7b8c10e1578dc4dd482105bed0ef848..ca6220691a41916d78d23eb3c8c5d2e343c92d93 100644 (file)
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -14,6 +14,7 @@ Contents:
    getting_started.rst
    auth_tutorial.rst
    code_snippet.rst
+   cursor_tutorial.rst
    api.rst
 
 Indices and tables