0
# Utilities and Pagination
1

2
Tweepy provides utility classes for pagination, caching, error handling, and other common functionality to simplify API usage and improve application performance.
3

4
## Capabilities
5

6
### Paginator (API v2)
7

8
The Paginator class provides automatic pagination for Twitter API v2 endpoints that return paginated results.
9

10
```python { .api }
11
class Paginator:
12
    def __init__(self, method, *args, **kwargs):
13
        """
14
        Initialize paginator for a Client method.
15
        
16
        Parameters:
17
        - method (callable): Client method that returns paginated results
18
        - *args: Positional arguments for the method
19
        - **kwargs: Keyword arguments for the method
20
        """
21

22
    def flatten(self, limit=None):
23
        """
24
        Flatten paginated results into a single iterator.
25
        
26
        Parameters:
27
        - limit (int, optional): Maximum number of items to return
28
        
29
        Yields:
30
        Individual items from paginated responses
31
        """
32

33
    def get_next(self):
34
        """
35
        Get the next page of results.
36
        
37
        Returns:
38
        Response object with next page data, or None if no more pages
39
        """
40

41
    def get_previous(self):
42
        """
43
        Get the previous page of results.
44
        
45
        Returns:
46
        Response object with previous page data, or None if no previous pages
47
        """
48
```
49

50
#### Paginator Usage Examples
51

52
```python
53
import tweepy
54

55
client = tweepy.Client(bearer_token="your_bearer_token")
56

57
# Paginate through search results
58
paginator = tweepy.Paginator(
59
    client.search_recent_tweets,
60
    query="python programming",
61
    max_results=100,
62
    tweet_fields=["created_at", "public_metrics"]
63
)
64

65
# Get all results (flattened)
66
for tweet in paginator.flatten(limit=500):
67
    print(f"{tweet.created_at}: {tweet.text}")
68

69
# Manual pagination
70
for page in paginator:
71
    print(f"Page contains {len(page.data)} tweets")
72
    for tweet in page.data:
73
        print(f"  - {tweet.text[:50]}...")
74
    
75
    # Stop after 3 pages
76
    if paginator.current_page >= 3:
77
        break
78

79
# Paginate through user followers
80
follower_paginator = tweepy.Paginator(
81
    client.get_users_followers,
82
    id="783214",  # Twitter's user ID
83
    max_results=1000,
84
    user_fields=["public_metrics", "verified"]
85
)
86

87
# Count followers with high follower counts
88
high_influence_followers = 0
89
for follower in follower_paginator.flatten(limit=10000):
90
    if follower.public_metrics['followers_count'] > 1000:
91
        high_influence_followers += 1
92

93
print(f"High-influence followers: {high_influence_followers}")
94
```
95

96
### Cursor (API v1.1)
97

98
The Cursor class provides pagination for Twitter API v1.1 endpoints with different pagination patterns.
99

100
```python { .api }
101
class Cursor:
102
    def __init__(self, method, *args, **kwargs):
103
        """
104
        Initialize cursor for an API method.
105
        
106
        Parameters:
107
        - method (callable): API method that returns paginated results
108
        - *args: Positional arguments for the method
109
        - **kwargs: Keyword arguments for the method
110
        """
111

112
    def items(self, limit=None):
113
        """
114
        Iterate over individual items from paginated results.
115
        
116
        Parameters:
117
        - limit (int, optional): Maximum number of items to return
118
        
119
        Yields:
120
        Individual items (tweets, users, etc.)
121
        """
122

123
    def pages(self, limit=None):
124
        """
125
        Iterate over pages of results.
126
        
127
        Parameters:
128
        - limit (int, optional): Maximum number of pages to return
129
        
130
        Yields:
131
        Lists of items (one page at a time)
132
        """
133
```
134

135
#### Cursor Usage Examples
136

137
```python
138
import tweepy
139

140
# Initialize API with authentication
141
auth = tweepy.OAuth1UserHandler(
142
    consumer_key="your_consumer_key",
143
    consumer_secret="your_consumer_secret",
144
    access_token="your_access_token", 
145
    access_token_secret="your_access_token_secret"
146
)
147
api = tweepy.API(auth, wait_on_rate_limit=True)
148

149
# Paginate through user's timeline
150
cursor = tweepy.Cursor(api.user_timeline, screen_name="python", count=200)
151

152
# Get individual tweets
153
for tweet in cursor.items(limit=1000):
154
    print(f"{tweet.created_at}: {tweet.text}")
155

156
# Process pages of results
157
for page in cursor.pages(limit=5):
158
    print(f"Processing page with {len(page)} tweets")
159
    for tweet in page:
160
        # Process each tweet in the page
161
        pass
162

163
# Paginate through followers
164
follower_cursor = tweepy.Cursor(api.get_followers, screen_name="python", count=200)
165

166
# Count followers by location
167
location_counts = {}
168
for follower in follower_cursor.items(limit=5000):
169
    location = follower.location or "Unknown"
170
    location_counts[location] = location_counts.get(location, 0) + 1
171

172
print("Top locations:")
173
for location, count in sorted(location_counts.items(), key=lambda x: x[1], reverse=True)[:10]:
174
    print(f"  {location}: {count}")
175
```
176

177
### Caching Classes
178

179
Tweepy provides caching implementations to reduce API calls and improve performance.
180

181
```python { .api }
182
class Cache:
183
    """Base cache interface."""
184
    
185
    def get(self, key):
186
        """
187
        Get cached value by key.
188
        
189
        Parameters:
190
        - key (str): Cache key
191
        
192
        Returns:
193
        Cached value or None if not found
194
        """
195
        
196
    def store(self, key, value):
197
        """
198
        Store value in cache.
199
        
200
        Parameters:
201
        - key (str): Cache key
202
        - value: Value to cache
203
        """
204
        
205
    def cleanup(self):
206
        """Clean up expired cache entries."""
207

208
class MemoryCache(Cache):
209
    def __init__(self, timeout=60):
210
        """
211
        Initialize in-memory cache.
212
        
213
        Parameters:
214
        - timeout (int): Cache entry timeout in seconds
215
        """
216

217
class FileCache(Cache):
218
    def __init__(self, cache_dir, timeout=60):
219
        """
220
        Initialize file-based cache.
221
        
222
        Parameters:
223
        - cache_dir (str): Directory to store cache files
224
        - timeout (int): Cache entry timeout in seconds
225
        """
226
```
227

228
#### Caching Usage Examples
229

230
```python
231
import tweepy
232

233
# Use memory cache with API
234
cache = tweepy.MemoryCache(timeout=300)  # 5 minute timeout
235
api = tweepy.API(auth, cache=cache)
236

237
# First call hits the API
238
user1 = api.get_user(screen_name="python")
239

240
# Second call uses cached result (if within timeout)
241
user2 = api.get_user(screen_name="python")  # Cached!
242

243
# Use file cache for persistent caching
244
file_cache = tweepy.FileCache(cache_dir="/tmp/tweepy_cache", timeout=3600)
245
api_with_file_cache = tweepy.API(auth, cache=file_cache)
246

247
# Cached results persist between application runs
248
user = api_with_file_cache.get_user(screen_name="python")
249
```
250

251
### Response Objects
252

253
Tweepy uses structured response objects to organize API response data.
254

255
```python { .api }
256
from collections import namedtuple
257

258
Response = namedtuple("Response", ("data", "includes", "errors", "meta"))
259
StreamResponse = namedtuple("StreamResponse", ("data",))
260
```
261

262
#### Response Object Usage
263

264
```python
265
# API v2 responses use Response namedtuple
266
response = client.search_recent_tweets(query="python", max_results=10)
267

268
# Access primary data
269
tweets = response.data
270
print(f"Found {len(tweets)} tweets")
271

272
# Access included data (related objects)
273
if response.includes:
274
    users = response.includes.get('users', [])
275
    media = response.includes.get('media', [])
276
    
277
# Access response metadata
278
if response.meta:
279
    result_count = response.meta.get('result_count')
280
    next_token = response.meta.get('next_token')
281
    print(f"Total results: {result_count}")
282

283
# Handle errors
284
if response.errors:
285
    for error in response.errors:
286
        print(f"API Error: {error}")
287
```
288

289
### Error Handling Utilities
290

291
Tweepy provides structured exception classes for different types of API errors.
292

293
```python { .api }
294
class TweepyException(Exception):
295
    """Base exception class for all Tweepy errors."""
296

297
class HTTPException(TweepyException):
298
    """HTTP-related exceptions with response information."""
299
    
300
    def __init__(self, response):
301
        self.response = response
302
        self.api_errors = []  # API error details
303
        self.api_codes = []   # API error codes
304

305
class BadRequest(HTTPException):
306
    """400 Bad Request - Invalid request parameters."""
307

308
class Unauthorized(HTTPException):
309
    """401 Unauthorized - Authentication failure."""
310

311
class Forbidden(HTTPException):
312
    """403 Forbidden - Access denied."""
313

314
class NotFound(HTTPException):
315
    """404 Not Found - Resource not found."""
316

317
class TooManyRequests(HTTPException):
318
    """429 Too Many Requests - Rate limit exceeded."""
319

320
class TwitterServerError(HTTPException):
321
    """500+ Server Error - Twitter server issues."""
322
```
323

324
#### Error Handling Examples
325

326
```python
327
import tweepy
328

329
try:
330
    # API call that might fail
331
    tweet = client.create_tweet(text="Hello World!")
332
    
333
except tweepy.BadRequest as e:
334
    print(f"Bad request: {e}")
335
    if e.api_errors:
336
        for error in e.api_errors:
337
            print(f"  - {error['title']}: {error['detail']}")
338
            
339
except tweepy.Unauthorized as e:
340
    print("Authentication failed - check your credentials")
341
    
342
except tweepy.Forbidden as e:
343
    print("Access denied - insufficient permissions")
344
    
345
except tweepy.TooManyRequests as e:
346
    print("Rate limit exceeded - wait before retrying")
347
    
348
except tweepy.NotFound as e:
349
    print("Resource not found")
350
    
351
except tweepy.TwitterServerError as e:
352
    print(f"Twitter server error: {e.response.status_code}")
353
    
354
except tweepy.HTTPException as e:
355
    print(f"HTTP error {e.response.status_code}: {e}")
356
    
357
except tweepy.TweepyException as e:
358
    print(f"Tweepy error: {e}")
359
```
360

361
### Rate Limit Handling
362

363
Configure automatic rate limit handling in clients.
364

365
```python
366
# API v2 Client with rate limit handling
367
client = tweepy.Client(
368
    bearer_token="your_bearer_token",
369
    wait_on_rate_limit=True  # Automatically wait when rate limited
370
)
371

372
# API v1.1 with rate limit handling
373
api = tweepy.API(auth, wait_on_rate_limit=True)
374

375
# Manual rate limit checking (v1.1 only)
376
def check_rate_limit():
377
    rate_limit_status = api.get_rate_limit_status()
378
    
379
    # Check specific endpoint limits
380
    search_limit = rate_limit_status['resources']['search']['/search/tweets']
381
    remaining = search_limit['remaining']
382
    reset_time = search_limit['reset']
383
    
384
    print(f"Search API calls remaining: {remaining}")
385
    print(f"Rate limit resets at: {reset_time}")
386

387
check_rate_limit()
388
```
389

390
### Configuration and Settings
391

392
Configure global Tweepy settings and behavior.
393

394
```python
395
# Configure global settings
396
tweepy.client.Client.DEFAULT_TIMEOUT = 30  # Default request timeout
397
tweepy.api.API.DEFAULT_RETRY_DELAY = 5     # Default retry delay
398

399
# Custom user agent
400
custom_client = tweepy.Client(
401
    bearer_token="your_bearer_token",
402
    user_agent="MyApp/1.0"
403
)
404

405
# Configure proxy settings
406
proxied_client = tweepy.Client(
407
    bearer_token="your_bearer_token",
408
    proxy="http://proxy.example.com:8080"
409
)
410
```