Added Cursor object to help with pagination. "page" based pagination working.

CHANGES

@@ -6,6 +6,9 @@ during upgrade will be listed here.
 + API
     + Added cursor parameter to API.friends and API.followers methods.
       Note: page parameter is being deprecated by twitter on 10/26
++ Cursor
+    Added the Cursor object to help with pagination within the API.
+    Please see the pagination tutorial for more details.
 
 1.0.1 -> 1.1
 =======================

tweepy/__init__.py

@@ -14,6 +14,7 @@ from . cache import Cache, MemoryCache, FileCache, MemCache
 from . auth import BasicAuthHandler, OAuthHandler
 from . streaming import Stream, StreamListener
 from . logging import TweepyLogger, DummyLogger, ConsoleLogger, FileLogger
+from . cursor import Cursor
 
 # Global, unauthenticated instance of API
 api = API()

tweepy/binder.py

@@ -150,5 +150,8 @@ def bind_api(path, parser, allowed_param=None, method='GET', require_auth=False,
 
         return out
 
+    # Expose extra data in callable object
+    _call.allowed_param = allowed_param
+
     return _call
 

tweepy/cursor.py

+# Tweepy
+# Copyright 2009 Joshua Roesslein
+# See LICENSE
+
+class Cursor(object):
+    """Pagination helper class"""
+
+    def __init__(self, method, *args, **kargs):
+        if 'cursor' in method.allowed_param:
+            self.iterator = CursorIterator(method, args, kargs)
+        elif 'page' in method.allowed_param:
+            self.iterator = PageIterator(method, args, kargs)
+        else:
+            raise TweepError('This method does not perform pagination')
+
+    def pages(self, limit=0):
+        """Return iterator for pages"""
+        if limit > 0:
+            self.iterator.limit = limit
+        return self.iterator
+
+    def items(self, limit=0):
+        """Return iterator for items in each page"""
+        items_yielded = 0
+        for page in self.iterator:
+            for item in page:
+                if limit > 0 and items_yielded == limit:
+                    raise StopIteration
+                items_yielded += 1
+                yield item
+
+class BaseIterator(object):
+
+    def __init__(self, method, args, kargs):
+        self.method = method
+        self.args = args
+        self.kargs = kargs
+        self.limit = 0
+
+    def next(self):
+        raise NotImplementedError
+
+    def prev(self):
+        raise NotImplementedError
+
+    def __iter__(self):
+        return self
+
+class CursorIterator(BaseIterator):
+
+    def next(self):
+        return
+
+    def prev(self):
+        return
+
+class PageIterator(BaseIterator):
+
+    def __init__(self, method, args, kargs):
+        BaseIterator.__init__(self, method, args, kargs)
+        self.current_page = 0
+
+    def next(self):
+        self.current_page += 1
+        items = self.method(page=self.current_page, *self.args, **self.kargs)
+        if len(items) == 0 or (self.limit > 0 and self.current_page > self.limit):
+            raise StopIteration
+        return items
+
+    def prev(self):
+        if (self.current_page == 0):
+            raise TweepError('Can not page back more, at first page')
+        self.current_page -= 1
+        return self.method(page=self.current_page, *self.args, **self.kargs)
+

tweepyshell.py

@@ -18,9 +18,6 @@ if len(sys.argv) != 3:
     exit(1)
 
 api = tweepy.API.new(auth='basic', username=sys.argv[1], password=sys.argv[2])
-if api.verify_credentials() is False:
-    print 'Invalid username and/or password!'
-    exit(1)
 
 code.interact('<Tweepy shell>', local={'tweepy': tweepy, 'api': api})