0
# Content Discovery
1
2
PRAW provides comprehensive content discovery capabilities including front page listings, subreddit discovery, user discovery, and domain-based content access. These features help you explore Reddit's vast content ecosystem and find relevant communities and users.
3
4
## Capabilities
5
6
### Front Page Listings
7
8
Access Reddit's front page content with various sorting and filtering options.
9
10
```python { .api }
11
class Front:
12
def __init__(self, reddit): ...
13
14
def best(self, **kwargs):
15
"""
16
Get best posts from Reddit front page.
17
18
Parameters:
19
- limit: Number of posts (default: 25, max: 100)
20
- params: Additional query parameters
21
22
Returns:
23
ListingGenerator of Submission instances
24
25
Best posts use Reddit's algorithm combining hot and top factors.
26
"""
27
28
def hot(self, **kwargs):
29
"""
30
Get hot posts from Reddit front page.
31
32
Parameters:
33
- limit: Number of posts (default: 25, max: 100)
34
- params: Additional query parameters
35
36
Returns:
37
ListingGenerator of Submission instances
38
"""
39
40
def new(self, **kwargs):
41
"""
42
Get newest posts from Reddit front page.
43
44
Parameters:
45
- limit: Number of posts (default: 25, max: 100)
46
- params: Additional query parameters
47
48
Returns:
49
ListingGenerator of Submission instances
50
"""
51
52
def top(self, time_filter: str = "all", **kwargs):
53
"""
54
Get top posts from Reddit front page.
55
56
Parameters:
57
- time_filter: Time period ("all", "day", "week", "month", "year")
58
- limit: Number of posts (default: 25, max: 100)
59
- params: Additional query parameters
60
61
Returns:
62
ListingGenerator of Submission instances
63
"""
64
65
def controversial(self, time_filter: str = "all", **kwargs):
66
"""
67
Get controversial posts from Reddit front page.
68
69
Parameters:
70
- time_filter: Time period ("all", "day", "week", "month", "year")
71
- limit: Number of posts (default: 25, max: 100)
72
- params: Additional query parameters
73
74
Returns:
75
ListingGenerator of Submission instances
76
"""
77
78
def rising(self, **kwargs):
79
"""
80
Get rising posts from Reddit front page.
81
82
Parameters:
83
- limit: Number of posts (default: 25, max: 100)
84
- params: Additional query parameters
85
86
Returns:
87
ListingGenerator of Submission instances
88
"""
89
90
def gilded(self, **kwargs):
91
"""
92
Get gilded posts from Reddit front page.
93
94
Parameters:
95
- limit: Number of posts (default: 25, max: 100)
96
- params: Additional query parameters
97
98
Returns:
99
ListingGenerator of Submission instances
100
"""
101
102
def random_rising(self, **kwargs):
103
"""
104
Get random rising posts from Reddit front page.
105
106
Parameters:
107
- limit: Number of posts (default: 25, max: 100)
108
- params: Additional query parameters
109
110
Returns:
111
ListingGenerator of Submission instances
112
"""
113
```
114
115
### Subreddit Discovery
116
117
Discover subreddits through various browsing and search methods.
118
119
```python { .api }
120
class Subreddits:
121
def __init__(self, reddit): ...
122
123
def default(self, **kwargs):
124
"""
125
Get default subreddits.
126
127
Parameters:
128
- limit: Number of subreddits (default: 25, max: 100)
129
- params: Additional query parameters
130
131
Returns:
132
ListingGenerator of Subreddit instances
133
134
Default subreddits are automatically subscribed to new accounts.
135
"""
136
137
def gold(self, **kwargs):
138
"""
139
Get Reddit Gold/Premium exclusive subreddits.
140
141
Parameters:
142
- limit: Number of subreddits (default: 25, max: 100)
143
- params: Additional query parameters
144
145
Returns:
146
ListingGenerator of Subreddit instances
147
148
Requires Reddit Premium subscription to access.
149
"""
150
151
def new(self, **kwargs):
152
"""
153
Get newly created subreddits.
154
155
Parameters:
156
- limit: Number of subreddits (default: 25, max: 100)
157
- params: Additional query parameters
158
159
Returns:
160
ListingGenerator of Subreddit instances
161
"""
162
163
def popular(self, **kwargs):
164
"""
165
Get popular subreddits.
166
167
Parameters:
168
- limit: Number of subreddits (default: 25, max: 100)
169
- params: Additional query parameters
170
171
Returns:
172
ListingGenerator of Subreddit instances
173
174
Popular subreddits based on activity and subscriber growth.
175
"""
176
177
def recommended(self, omit_subreddits: list = None, **kwargs):
178
"""
179
Get recommended subreddits for current user.
180
181
Parameters:
182
- omit_subreddits: List of subreddit names to exclude
183
- limit: Number of subreddits (default: 25, max: 100)
184
- params: Additional query parameters
185
186
Returns:
187
ListingGenerator of Subreddit instances
188
189
Personalized recommendations based on user activity.
190
Requires authentication.
191
"""
192
193
def search(
194
self,
195
query: str,
196
*,
197
sort: str = "relevance",
198
**kwargs
199
):
200
"""
201
Search for subreddits by name and description.
202
203
Parameters:
204
- query: Search query
205
- sort: Sort order ("relevance", "activity")
206
- limit: Number of results (default: 25, max: 100)
207
- params: Additional query parameters
208
209
Returns:
210
ListingGenerator of Subreddit instances
211
"""
212
213
def stream(self, **kwargs):
214
"""
215
Stream newly created subreddits.
216
217
Parameters:
218
- pause_after: Pause after this many requests
219
- skip_existing: Skip subreddits created before stream start
220
221
Yields:
222
Subreddit instances as they are created
223
"""
224
```
225
226
### User Discovery
227
228
Find and search for Reddit users across the platform.
229
230
```python { .api }
231
class Redditors:
232
def __init__(self, reddit): ...
233
234
def new(self, **kwargs):
235
"""
236
Get newly created user accounts.
237
238
Parameters:
239
- limit: Number of users (default: 25, max: 100)
240
- params: Additional query parameters
241
242
Returns:
243
ListingGenerator of Redditor instances
244
"""
245
246
def popular(self, **kwargs):
247
"""
248
Get popular Reddit users.
249
250
Parameters:
251
- limit: Number of users (default: 25, max: 100)
252
- params: Additional query parameters
253
254
Returns:
255
ListingGenerator of Redditor instances
256
257
Popular users based on karma and activity.
258
"""
259
260
def search(self, query: str, **kwargs):
261
"""
262
Search for Reddit users by username.
263
264
Parameters:
265
- query: Search query (partial username)
266
- limit: Number of results (default: 25, max: 100)
267
- params: Additional query parameters
268
269
Returns:
270
ListingGenerator of Redditor instances
271
"""
272
273
def stream(self, **kwargs):
274
"""
275
Stream newly created user accounts.
276
277
Parameters:
278
- pause_after: Pause after this many requests
279
- skip_existing: Skip users created before stream start
280
281
Yields:
282
Redditor instances as accounts are created
283
"""
284
```
285
286
### Domain-Based Discovery
287
288
Access content from specific domains and websites.
289
290
```python { .api }
291
class DomainListing:
292
"""Listings for content from specific domains."""
293
294
def __init__(self, reddit, domain: str): ...
295
296
def hot(self, **kwargs):
297
"""
298
Get hot posts from the domain.
299
300
Parameters:
301
- limit: Number of posts (default: 25, max: 100)
302
- params: Additional query parameters
303
304
Returns:
305
ListingGenerator of Submission instances
306
"""
307
308
def new(self, **kwargs):
309
"""
310
Get newest posts from the domain.
311
312
Parameters:
313
- limit: Number of posts (default: 25, max: 100)
314
- params: Additional query parameters
315
316
Returns:
317
ListingGenerator of Submission instances
318
"""
319
320
def top(self, time_filter: str = "all", **kwargs):
321
"""
322
Get top posts from the domain.
323
324
Parameters:
325
- time_filter: Time period ("all", "day", "week", "month", "year")
326
- limit: Number of posts (default: 25, max: 100)
327
- params: Additional query parameters
328
329
Returns:
330
ListingGenerator of Submission instances
331
"""
332
333
def controversial(self, time_filter: str = "all", **kwargs):
334
"""
335
Get controversial posts from the domain.
336
337
Parameters:
338
- time_filter: Time period ("all", "day", "week", "month", "year")
339
- limit: Number of posts (default: 25, max: 100)
340
- params: Additional query parameters
341
342
Returns:
343
ListingGenerator of Submission instances
344
"""
345
346
def rising(self, **kwargs):
347
"""
348
Get rising posts from the domain.
349
350
Parameters:
351
- limit: Number of posts (default: 25, max: 100)
352
- params: Additional query parameters
353
354
Returns:
355
ListingGenerator of Submission instances
356
"""
357
358
def domain(self, domain: str) -> DomainListing:
359
"""
360
Get DomainListing for specific domain.
361
362
Parameters:
363
- domain: Domain name (e.g., "github.com", "youtube.com")
364
365
Returns:
366
DomainListing instance for the domain
367
"""
368
```
369
370
### Random Content Discovery
371
372
Access random content and subreddits.
373
374
```python { .api }
375
def random_subreddit(self, nsfw: bool = False):
376
"""
377
Get a random subreddit.
378
379
Parameters:
380
- nsfw: Include NSFW subreddits in selection
381
382
Returns:
383
Subreddit instance
384
385
Randomly selects from active subreddits on Reddit.
386
"""
387
388
def random(self):
389
"""
390
Get a random submission from r/random.
391
392
Returns:
393
Submission instance
394
395
Equivalent to visiting reddit.com/r/random
396
"""
397
```
398
399
### Content Information and Metadata
400
401
Get detailed information about Reddit content by URL or ID.
402
403
```python { .api }
404
def info(
405
self,
406
fullnames: list = None,
407
subreddits: list = None,
408
url: str = None
409
):
410
"""
411
Fetch information about Reddit objects.
412
413
Parameters:
414
- fullnames: List of Reddit fullnames (e.g., ["t3_abc123", "t1_def456"])
415
- subreddits: List of subreddit names
416
- url: URL to get information about
417
418
Returns:
419
Generator yielding Reddit objects (Submission, Comment, etc.)
420
421
Can fetch up to 100 objects per request using fullnames.
422
URLs are resolved to their corresponding Reddit objects.
423
"""
424
425
def username_available(self, name: str) -> bool:
426
"""
427
Check if username is available for registration.
428
429
Parameters:
430
- name: Username to check
431
432
Returns:
433
True if username is available, False if taken
434
"""
435
```
436
437
### Listing Generators and Pagination
438
439
Efficient iteration over large result sets with automatic pagination.
440
441
```python { .api }
442
class ListingGenerator:
443
"""Generator for paginated API results."""
444
445
def __init__(self, reddit, url: str, **kwargs): ...
446
447
def __iter__(self):
448
"""Iterate over all items, handling pagination automatically."""
449
450
def __next__(self):
451
"""Get next item in sequence."""
452
453
@property
454
def params(self) -> dict:
455
"""Query parameters for the listing."""
456
457
def reset(self):
458
"""Reset generator to beginning."""
459
460
# Usage with custom limits and parameters
461
listing = reddit.front.hot(limit=100)
462
for submission in listing:
463
print(f"{submission.title} - {submission.score}")
464
465
# Access specific pages
466
listing = reddit.subreddit("python").new(limit=25, params={"after": "t3_abc123"})
467
```
468
469
## Usage Examples
470
471
### Front Page Exploration
472
473
```python
474
import praw
475
476
reddit = praw.Reddit(...)
477
478
# Get best posts from front page
479
print("Best posts:")
480
for submission in reddit.front.best(limit=10):
481
print(f"{submission.title} - r/{submission.subreddit.display_name}")
482
print(f"Score: {submission.score}, Comments: {submission.num_comments}")
483
484
# Get controversial posts from this week
485
print("\nControversial this week:")
486
for submission in reddit.front.controversial("week", limit=5):
487
print(f"{submission.title} - {submission.upvote_ratio:.2f} ratio")
488
489
# Get rising posts
490
print("\nRising posts:")
491
for submission in reddit.front.rising(limit=5):
492
print(f"{submission.title} - {submission.created_utc}")
493
```
494
495
### Subreddit Discovery
496
497
```python
498
# Search for programming-related subreddits
499
print("Programming subreddits:")
500
for subreddit in reddit.subreddits.search("programming", limit=10):
501
print(f"r/{subreddit.display_name} - {subreddit.subscribers} subscribers")
502
print(f"Description: {subreddit.public_description}")
503
504
# Get popular subreddits
505
print("\nPopular subreddits:")
506
for subreddit in reddit.subreddits.popular(limit=10):
507
print(f"r/{subreddit.display_name} - {subreddit.subscribers} subscribers")
508
509
# Get new subreddits
510
print("\nNew subreddits:")
511
for subreddit in reddit.subreddits.new(limit=5):
512
print(f"r/{subreddit.display_name} - Created: {subreddit.created_utc}")
513
```
514
515
### User Discovery
516
517
```python
518
# Search for users
519
print("Users matching 'python':")
520
for user in reddit.redditors.search("python", limit=5):
521
print(f"u/{user.name} - {user.comment_karma} comment karma")
522
523
# Get popular users
524
print("\nPopular users:")
525
for user in reddit.redditors.popular(limit=5):
526
print(f"u/{user.name} - Total karma: {user.total_karma}")
527
528
# Get new users
529
print("\nNew users:")
530
for user in reddit.redditors.new(limit=5):
531
print(f"u/{user.name} - Created: {user.created_utc}")
532
```
533
534
### Domain-Based Content
535
536
```python
537
# Get content from specific domains
538
github_domain = reddit.domain("github.com")
539
540
print("Hot GitHub posts:")
541
for submission in github_domain.hot(limit=10):
542
print(f"{submission.title}")
543
print(f"r/{submission.subreddit.display_name} - {submission.score} points")
544
545
# Get top YouTube videos this week
546
youtube_domain = reddit.domain("youtube.com")
547
for submission in youtube_domain.top("week", limit=5):
548
print(f"{submission.title} - {submission.url}")
549
```
550
551
### Random Content Exploration
552
553
```python
554
# Get random subreddits
555
for i in range(5):
556
random_sub = reddit.random_subreddit()
557
print(f"Random: r/{random_sub.display_name}")
558
559
# Include NSFW subreddits
560
random_nsfw = reddit.random_subreddit(nsfw=True)
561
print(f"Random NSFW: r/{random_nsfw.display_name}")
562
563
# Get random submission
564
random_post = reddit.random()
565
print(f"Random post: {random_post.title}")
566
```
567
568
### Content Information Lookup
569
570
```python
571
# Look up content by fullnames
572
fullnames = ["t3_abc123", "t1_def456"] # submission and comment IDs
573
for item in reddit.info(fullnames=fullnames):
574
if hasattr(item, 'title'): # It's a submission
575
print(f"Submission: {item.title}")
576
else: # It's a comment
577
print(f"Comment: {item.body[:50]}...")
578
579
# Look up content by URL
580
url_content = list(reddit.info(url="https://www.reddit.com/r/python/comments/abc123/"))
581
for item in url_content:
582
print(f"Found: {item.title}")
583
584
# Check username availability
585
available = reddit.username_available("test_username_123")
586
print(f"Username available: {available}")
587
```
588
589
### Streaming New Content
590
591
```python
592
# Stream new subreddits
593
print("Monitoring new subreddits...")
594
for subreddit in reddit.subreddits.stream():
595
print(f"New subreddit: r/{subreddit.display_name}")
596
print(f"Description: {subreddit.public_description}")
597
# Add your processing logic here
598
599
# Stream new users
600
print("Monitoring new users...")
601
for user in reddit.redditors.stream():
602
print(f"New user: u/{user.name}")
603
# Add your processing logic here
604
```
605
606
### Advanced Listing Usage
607
608
```python
609
# Custom pagination
610
all_posts = []
611
after = None
612
for page in range(3): # Get 3 pages
613
params = {"limit": 25}
614
if after:
615
params["after"] = after
616
617
page_posts = list(reddit.subreddit("python").hot(**params))
618
all_posts.extend(page_posts)
619
620
if page_posts:
621
after = page_posts[-1].fullname
622
else:
623
break
624
625
print(f"Collected {len(all_posts)} posts across {page+1} pages")
626
627
# Filter results during iteration
628
high_karma_posts = []
629
for submission in reddit.front.hot(limit=100):
630
if submission.score > 1000:
631
high_karma_posts.append(submission)
632
if len(high_karma_posts) >= 10:
633
break
634
635
print(f"Found {len(high_karma_posts)} high karma posts")
636
```
637
638
## Types
639
640
```python { .api }
641
class Listing:
642
"""Generic listing container."""
643
644
def __init__(self, reddit, json_dict: dict): ...
645
646
after: str # Pagination cursor for next page
647
before: str # Pagination cursor for previous page
648
children: list # List of contained objects
649
650
class FlairListing:
651
"""Flair-specific listing container."""
652
653
class ModNoteListing:
654
"""Moderator note listing container."""
655
656
class ModeratorListing:
657
"""Moderator listing container."""
658
```