Document pagination

diff --git a/docs/index.rst b/docs/index.rst
index 279cd8de32d17844dfa5639bdfbbc498cff67706..f5109e314849e0f9acdba16ef6d46f93b36bd7f1 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -22,6 +22,7 @@ Contents:
    stream.rst
    exceptions.rst
    extended_tweets.rst
+   pagination.rst
    streaming.rst
    running_tests.rst
    changelog.md

diff --git a/docs/pagination.rst b/docs/pagination.rst
new file mode 100644 (file)
index 0000000..132860d
--- /dev/null
+++ b/docs/pagination.rst
@@ -0,0 +1,30 @@
+.. _pagination_guide:
+
+.. currentmodule:: tweepy
+
+**********
+Pagination
+**********
+
+API v2
+======
+
+.. autoclass:: Paginator
+    :members:
+
+Example
+-------
+
+::
+
+    import tweepy
+
+    client = tweepy.Client("Bearer Token here")
+
+    for response in tweepy.Paginator(client.get_users_followers, 2244994945,
+                                     max_results=1000, limit=5):
+        print(response.meta)
+
+    for tweet in tweepy.Paginator(client.search_recent_tweets, "Tweepy",
+                                  max_results=100).flatten(limit=250):
+        print(tweet.id)

diff --git a/tweepy/pagination.py b/tweepy/pagination.py
index 39ff8423b12b5cee145936dec62974b255fe8df5..6e9fd47a6e8caab052d59ced2a8f407dfa4d1001 100644 (file)
--- a/tweepy/pagination.py
+++ b/tweepy/pagination.py
@@ -6,6 +6,18 @@ from math import inf
 
 
 class Paginator:
+    """:class:`Paginator` can be used to paginate for any :class:`Client`
+    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):
         self.method = method
@@ -20,6 +32,13 @@ class Paginator:
                                   **self.kwargs)
 
     def flatten(self, limit=inf):
+        """Flatten paginated data
+
+        Parameters
+        ----------
+        limit
+            Maximum number of results to yield
+        """
         if limit <= 0:
             return