0
# Subreddits
1
2
PRAW provides comprehensive subreddit management capabilities including posting content, searching, subscribing, moderation, and accessing subreddit-specific features like flairs, widgets, and stylesheets.
3
4
## Capabilities
5
6
### Subreddit Access and Basic Operations
7
8
Access subreddits and perform basic operations like subscribing and messaging.
9
10
```python { .api }
11
class Subreddit:
12
def __init__(self, reddit, display_name: str): ...
13
14
def subscribe(self):
15
"""Subscribe to the subreddit."""
16
17
def unsubscribe(self):
18
"""Unsubscribe from the subreddit."""
19
20
def message(self, subject: str, message: str, *, from_subreddit = None):
21
"""
22
Send a message to the subreddit moderators.
23
24
Parameters:
25
- subject: Message subject
26
- message: Message body (markdown supported)
27
- from_subreddit: Send from subreddit instead of user
28
"""
29
```
30
31
### Content Submission
32
33
Submit various types of content to subreddits including text posts, links, images, and media.
34
35
```python { .api }
36
def submit(
37
self,
38
title: str,
39
*,
40
flair_id: str = None,
41
flair_text: str = None,
42
nsfw: bool = False,
43
spoiler: bool = False,
44
**kwargs
45
):
46
"""
47
Submit content to the subreddit.
48
49
Parameters:
50
- title: Submission title
51
- selftext: Text content (for text posts)
52
- url: URL (for link posts)
53
- flair_id: Flair template ID
54
- flair_text: Custom flair text
55
- nsfw: Mark as NSFW
56
- spoiler: Mark as spoiler
57
- send_replies: Enable inbox replies (default: True)
58
- resubmit: Allow resubmitting same URL
59
- draft: Save as draft instead of posting
60
61
Returns:
62
Submission instance
63
"""
64
65
def submit_image(
66
self,
67
title: str,
68
image_path: str,
69
*,
70
flair_id: str = None,
71
flair_text: str = None,
72
nsfw: bool = False,
73
spoiler: bool = False,
74
timeout: int = 10,
75
**kwargs
76
):
77
"""
78
Submit an image to the subreddit.
79
80
Parameters:
81
- title: Submission title
82
- image_path: Path to image file
83
- flair_id: Flair template ID
84
- flair_text: Custom flair text
85
- nsfw: Mark as NSFW
86
- spoiler: Mark as spoiler
87
- timeout: Upload timeout in seconds
88
89
Returns:
90
Submission instance
91
"""
92
93
def submit_video(
94
self,
95
title: str,
96
video_path: str,
97
*,
98
thumbnail_path: str = None,
99
flair_id: str = None,
100
flair_text: str = None,
101
nsfw: bool = False,
102
spoiler: bool = False,
103
timeout: int = 10,
104
**kwargs
105
):
106
"""
107
Submit a video to the subreddit.
108
109
Parameters:
110
- title: Submission title
111
- video_path: Path to video file
112
- thumbnail_path: Path to thumbnail image
113
- flair_id: Flair template ID
114
- flair_text: Custom flair text
115
- nsfw: Mark as NSFW
116
- spoiler: Mark as spoiler
117
- timeout: Upload timeout in seconds
118
119
Returns:
120
Submission instance
121
"""
122
```
123
124
### Content Discovery and Listings
125
126
Access different content listings and search within subreddits.
127
128
```python { .api }
129
def hot(self, **kwargs):
130
"""
131
Get hot submissions from the subreddit.
132
133
Parameters:
134
- limit: Number of submissions (default: 25, max: 100)
135
- params: Additional query parameters
136
137
Returns:
138
ListingGenerator of Submission instances
139
"""
140
141
def new(self, **kwargs):
142
"""
143
Get new submissions from the subreddit.
144
145
Parameters:
146
- limit: Number of submissions (default: 25, max: 100)
147
- params: Additional query parameters
148
149
Returns:
150
ListingGenerator of Submission instances
151
"""
152
153
def top(self, time_filter: str = "all", **kwargs):
154
"""
155
Get top submissions from the subreddit.
156
157
Parameters:
158
- time_filter: Time period ("all", "day", "week", "month", "year")
159
- limit: Number of submissions (default: 25, max: 100)
160
- params: Additional query parameters
161
162
Returns:
163
ListingGenerator of Submission instances
164
"""
165
166
def controversial(self, time_filter: str = "all", **kwargs):
167
"""
168
Get controversial submissions from the subreddit.
169
170
Parameters:
171
- time_filter: Time period ("all", "day", "week", "month", "year")
172
- limit: Number of submissions (default: 25, max: 100)
173
- params: Additional query parameters
174
175
Returns:
176
ListingGenerator of Submission instances
177
"""
178
179
def rising(self, **kwargs):
180
"""
181
Get rising submissions from the subreddit.
182
183
Parameters:
184
- limit: Number of submissions (default: 25, max: 100)
185
- params: Additional query parameters
186
187
Returns:
188
ListingGenerator of Submission instances
189
"""
190
191
def gilded(self, **kwargs):
192
"""
193
Get gilded submissions from the subreddit.
194
195
Parameters:
196
- limit: Number of submissions (default: 25, max: 100)
197
- params: Additional query parameters
198
199
Returns:
200
ListingGenerator of Submission instances
201
"""
202
203
def search(
204
self,
205
query: str,
206
*,
207
sort: str = "relevance",
208
syntax: str = "plain",
209
time_filter: str = "all",
210
**kwargs
211
):
212
"""
213
Search within the subreddit.
214
215
Parameters:
216
- query: Search query
217
- sort: Sort order ("relevance", "hot", "top", "new", "comments")
218
- syntax: Search syntax ("plain", "lucene", "cloudsearch")
219
- time_filter: Time period ("all", "day", "week", "month", "year")
220
- limit: Number of results (default: 25, max: 100)
221
222
Returns:
223
ListingGenerator of Submission instances
224
"""
225
```
226
227
### Subreddit Properties and Metadata
228
229
Access subreddit information and configuration.
230
231
```python { .api }
232
# Basic properties
233
display_name: str # Subreddit name (without r/ prefix)
234
id: str # Subreddit ID
235
title: str # Subreddit title
236
description: str # Full description
237
public_description: str # Short description
238
description_html: str # Description as HTML
239
public_description_html: str # Short description as HTML
240
241
# Statistics
242
subscribers: int # Subscriber count
243
accounts_active: int # Currently active users
244
active_user_count: int # Active users (may be None)
245
246
# Status and settings
247
over18: bool # Whether NSFW
248
quarantine: bool # Whether quarantined
249
user_is_subscriber: bool # Whether current user is subscribed
250
user_is_moderator: bool # Whether current user is moderator
251
user_is_contributor: bool # Whether current user is contributor
252
user_is_banned: bool # Whether current user is banned
253
user_can_flair_in_sr: bool # Whether user can set flair
254
255
# Timestamps
256
created_utc: float # Creation timestamp (UTC)
257
258
# Colors and styling
259
primary_color: str # Primary theme color
260
key_color: str # Key theme color
261
banner_background_color: str # Banner background color
262
banner_background_image: str # Banner image URL
263
header_img: str # Header image URL
264
icon_img: str # Icon image URL
265
266
# Configuration
267
submission_type: str # Allowed submission types
268
subreddit_type: str # Subreddit type (public, restricted, private)
269
content_options: str # Content options
270
allow_images: bool # Whether images allowed
271
allow_videos: bool # Whether videos allowed
272
allow_polls: bool # Whether polls allowed
273
wiki_enabled: bool # Whether wiki enabled
274
show_media: bool # Whether to show media
275
show_media_preview: bool # Whether to show media previews
276
```
277
278
### Flair Management
279
280
Manage user and submission flairs within the subreddit.
281
282
```python { .api }
283
class SubredditFlair:
284
"""Subreddit flair management."""
285
286
def choices(self):
287
"""
288
Get available flair choices for current user.
289
290
Returns:
291
List of flair choice dictionaries
292
"""
293
294
def link_templates(self):
295
"""
296
Get link flair templates.
297
298
Returns:
299
List of flair template dictionaries
300
"""
301
302
def user_templates(self):
303
"""
304
Get user flair templates.
305
306
Returns:
307
List of flair template dictionaries
308
"""
309
310
def set(
311
self,
312
redditor,
313
text: str = None,
314
css_class: str = None,
315
flair_template_id: str = None
316
):
317
"""
318
Set user flair.
319
320
Parameters:
321
- redditor: Redditor instance or username
322
- text: Flair text
323
- css_class: CSS class
324
- flair_template_id: Template ID
325
"""
326
327
def delete(self, redditor):
328
"""
329
Remove user flair.
330
331
Parameters:
332
- redditor: Redditor instance or username
333
"""
334
335
def update(
336
self,
337
flair_list: list,
338
text: str = "",
339
css_class: str = ""
340
):
341
"""
342
Update multiple user flairs.
343
344
Parameters:
345
- flair_list: List of flair updates
346
- text: Default flair text
347
- css_class: Default CSS class
348
"""
349
350
flair: SubredditFlair # Flair management instance
351
```
352
353
### Moderation Access
354
355
Access comprehensive moderation tools for the subreddit.
356
357
```python { .api }
358
class SubredditModeration:
359
"""Subreddit moderation capabilities."""
360
361
def approve(self, thing):
362
"""Approve a submission or comment."""
363
364
def remove(self, thing, *, mod_note: str = None, spam: bool = None):
365
"""Remove a submission or comment."""
366
367
def spam(self, thing):
368
"""Mark as spam."""
369
370
def notes(self, **kwargs):
371
"""Get moderator notes."""
372
373
def log(self, **kwargs):
374
"""Get moderation log."""
375
376
def queue(self, **kwargs):
377
"""Get moderation queue."""
378
379
def reports(self, **kwargs):
380
"""Get reported items."""
381
382
def spam_queue(self, **kwargs):
383
"""Get spam queue."""
384
385
def modmail_conversations(self, **kwargs):
386
"""Get modmail conversations."""
387
388
def settings(self):
389
"""Get subreddit settings."""
390
391
def update(self, **settings):
392
"""Update subreddit settings."""
393
394
mod: SubredditModeration # Moderation instance
395
```
396
397
### Widget Management
398
399
Manage subreddit widgets for new Reddit design.
400
401
```python { .api }
402
class SubredditWidgets:
403
"""Subreddit widget management."""
404
405
def __init__(self, subreddit): ...
406
407
def sidebar(self):
408
"""Get sidebar widgets."""
409
410
def topbar(self):
411
"""Get topbar widgets."""
412
413
def id_card(self):
414
"""Get ID card widget."""
415
416
def moderators_widget(self):
417
"""Get moderators widget."""
418
419
def progressive_images(self):
420
"""Upload progressive images for widgets."""
421
422
widgets: SubredditWidgets # Widget management instance
423
```
424
425
### Wiki Access
426
427
Access and manage subreddit wiki pages.
428
429
```python { .api }
430
class SubredditWiki:
431
"""Subreddit wiki management."""
432
433
def __init__(self, subreddit): ...
434
435
def __getitem__(self, page_name: str):
436
"""Get wiki page by name."""
437
438
def create(
439
self,
440
name: str,
441
content: str,
442
reason: str = None,
443
**kwargs
444
):
445
"""
446
Create wiki page.
447
448
Parameters:
449
- name: Page name
450
- content: Page content (markdown)
451
- reason: Edit reason
452
"""
453
454
wiki: SubredditWiki # Wiki management instance
455
```
456
457
### Stylesheet Management
458
459
Manage subreddit stylesheets for old Reddit design.
460
461
```python { .api }
462
class SubredditStylesheet:
463
"""Subreddit stylesheet management."""
464
465
def __call__(self):
466
"""Get current stylesheet."""
467
468
def update(
469
self,
470
stylesheet: str,
471
reason: str = None
472
):
473
"""
474
Update stylesheet.
475
476
Parameters:
477
- stylesheet: CSS content
478
- reason: Update reason
479
"""
480
481
def upload(
482
self,
483
name: str,
484
image_path: str
485
):
486
"""
487
Upload stylesheet image.
488
489
Parameters:
490
- name: Image name
491
- image_path: Path to image file
492
"""
493
494
def delete_image(self, name: str):
495
"""Delete stylesheet image."""
496
497
stylesheet: SubredditStylesheet # Stylesheet management instance
498
```
499
500
### Streaming and Real-time Updates
501
502
Stream new submissions and comments from the subreddit.
503
504
```python { .api }
505
class SubredditStream:
506
"""Real-time subreddit content streaming."""
507
508
def submissions(self, **kwargs):
509
"""
510
Stream new submissions.
511
512
Parameters:
513
- pause_after: Pause after this many requests
514
- skip_existing: Skip submissions created before stream start
515
516
Yields:
517
Submission instances
518
"""
519
520
def comments(self, **kwargs):
521
"""
522
Stream new comments.
523
524
Parameters:
525
- pause_after: Pause after this many requests
526
- skip_existing: Skip comments created before stream start
527
528
Yields:
529
Comment instances
530
"""
531
532
stream: SubredditStream # Streaming instance
533
```
534
535
### Filters Management
536
537
Manage content filters for the subreddit.
538
539
```python { .api }
540
class SubredditFilters:
541
"""Subreddit content filters."""
542
543
def __init__(self, subreddit): ...
544
545
def __iter__(self):
546
"""Iterate over filters."""
547
548
def add(self, filterName: str):
549
"""Add content filter."""
550
551
def remove(self, filterName: str):
552
"""Remove content filter."""
553
554
filters: SubredditFilters # Filters management instance
555
```
556
557
### Collections Support
558
559
Manage post collections within the subreddit.
560
561
```python { .api }
562
class SubredditCollections:
563
"""Subreddit collections management."""
564
565
def __call__(self, **kwargs):
566
"""Get collections."""
567
568
collections: SubredditCollections # Collections management instance
569
```
570
571
## Usage Examples
572
573
### Basic Subreddit Operations
574
575
```python
576
# Access subreddit
577
subreddit = reddit.subreddit("python")
578
579
# Subscribe/unsubscribe
580
subreddit.subscribe()
581
subreddit.unsubscribe()
582
583
# Get subreddit info
584
print(f"r/{subreddit.display_name}")
585
print(f"Subscribers: {subreddit.subscribers}")
586
print(f"Description: {subreddit.public_description}")
587
```
588
589
### Submitting Content
590
591
```python
592
# Text post
593
submission = subreddit.submit(
594
title="My Python Question",
595
selftext="I need help with...",
596
flair_text="Help"
597
)
598
599
# Link post
600
submission = subreddit.submit(
601
title="Interesting Article",
602
url="https://example.com/article"
603
)
604
605
# Image post
606
submission = subreddit.submit_image(
607
title="My Screenshot",
608
image_path="/path/to/image.png",
609
nsfw=False
610
)
611
```
612
613
### Browsing Content
614
615
```python
616
# Get hot posts
617
for submission in subreddit.hot(limit=10):
618
print(f"{submission.title} - Score: {submission.score}")
619
620
# Search within subreddit
621
for submission in subreddit.search("python tutorial", limit=5):
622
print(f"Found: {submission.title}")
623
624
# Get top posts from this week
625
for submission in subreddit.top("week", limit=10):
626
print(f"{submission.title} - {submission.upvote_ratio}")
627
```
628
629
### Flair Management
630
631
```python
632
# Get available flairs
633
flair_choices = subreddit.flair.choices()
634
for choice in flair_choices:
635
print(f"Flair: {choice['flair_text']}")
636
637
# Set user flair
638
subreddit.flair.set(
639
redditor="username",
640
text="Python Developer",
641
css_class="developer"
642
)
643
```
644
645
### Real-time Monitoring
646
647
```python
648
# Stream new submissions
649
for submission in subreddit.stream.submissions():
650
print(f"New post: {submission.title}")
651
# Process new submission
652
653
# Stream new comments
654
for comment in subreddit.stream.comments():
655
print(f"New comment by {comment.author}: {comment.body[:50]}...")
656
# Process new comment
657
```
658
659
## Types
660
661
```python { .api }
662
class SubredditHelper:
663
"""Helper for creating subreddits."""
664
665
def create(
666
self,
667
name: str,
668
title: str = None,
669
link_type: str = "any",
670
subreddit_type: str = "public",
671
wikimode: str = "disabled",
672
**kwargs
673
):
674
"""Create a new subreddit."""
675
676
class SubredditModmail:
677
"""Subreddit modmail management."""
678
679
def __call__(self, id: str = None):
680
"""Get modmail conversation."""
681
682
def conversations(self, **kwargs):
683
"""Get modmail conversations."""
684
685
def create(self, subject: str, body: str, recipient: str, **kwargs):
686
"""Create modmail conversation."""
687
688
modmail: SubredditModmail # Modmail management instance
689
```