0
# Submissions and Comments
1
2
PRAW provides comprehensive support for interacting with Reddit submissions (posts) and comments. These models support all standard Reddit operations including creation, editing, voting, saving, and advanced features like gilding and moderation.
3
4
## Capabilities
5
6
### Submission Management
7
8
Create, edit, and manage Reddit submissions with full support for text posts, link posts, and media uploads.
9
10
```python { .api }
11
class Submission:
12
def __init__(self, reddit, id: str = None, url: str = None): ...
13
14
@classmethod
15
def id_from_url(cls, url: str) -> str:
16
"""
17
Extract submission ID from Reddit URL.
18
19
Parameters:
20
- url: Reddit submission URL
21
22
Returns:
23
Submission ID (base36)
24
"""
25
26
def reply(self, body: str):
27
"""
28
Reply to submission with comment.
29
30
Parameters:
31
- body: Comment text (markdown supported)
32
33
Returns:
34
Comment instance
35
"""
36
37
def edit(self, body: str):
38
"""
39
Edit submission text (self posts only).
40
41
Parameters:
42
- body: New text content (markdown supported)
43
44
Returns:
45
Updated Submission instance
46
"""
47
48
def delete(self):
49
"""Delete the submission."""
50
51
def hide(self):
52
"""Hide submission from user's view."""
53
54
def unhide(self):
55
"""Unhide submission from user's view."""
56
57
def save(self, category: str = None):
58
"""
59
Save submission.
60
61
Parameters:
62
- category: Save category (Reddit Premium feature)
63
"""
64
65
def unsave(self):
66
"""Unsave submission."""
67
68
def report(self, reason: str):
69
"""
70
Report submission.
71
72
Parameters:
73
- reason: Report reason
74
"""
75
```
76
77
### Submission Voting
78
79
Vote on submissions with support for upvotes, downvotes, and clearing votes.
80
81
```python { .api }
82
def upvote(self):
83
"""Upvote the submission."""
84
85
def downvote(self):
86
"""Downvote the submission."""
87
88
def clear_vote(self):
89
"""Clear existing vote on submission."""
90
```
91
92
### Submission Properties and Data
93
94
Access submission metadata, content, and related objects.
95
96
```python { .api }
97
# Core properties
98
id: str # Submission ID
99
title: str # Submission title
100
author: Redditor # Submission author
101
subreddit: Subreddit # Subreddit where posted
102
score: int # Current score (upvotes - downvotes)
103
upvote_ratio: float # Ratio of upvotes (0.0-1.0)
104
num_comments: int # Number of comments
105
created_utc: float # Creation timestamp (UTC)
106
edited: bool | float # Edit timestamp or False
107
url: str # Submission URL
108
permalink: str # Reddit permalink
109
shortlink: str # Short Reddit URL (redd.it)
110
111
# Content properties
112
selftext: str # Self-post text content
113
selftext_html: str # Self-post HTML content
114
is_self: bool # Whether self-post
115
is_video: bool # Whether video post
116
media: dict # Media metadata
117
secure_media: dict # Secure media metadata
118
119
# Status properties
120
archived: bool # Whether archived
121
locked: bool # Whether locked
122
pinned: bool # Whether pinned
123
stickied: bool # Whether stickied
124
over_18: bool # Whether NSFW
125
spoiler: bool # Whether spoiler
126
hidden: bool # Whether hidden by user
127
saved: bool # Whether saved by user
128
clicked: bool # Whether clicked by user
129
visited: bool # Whether visited by user
130
131
# Interaction objects
132
comments: CommentForest # Comment tree
133
flair: SubmissionFlair # Flair management
134
mod: SubmissionModeration # Moderation actions
135
```
136
137
### Comment Management
138
139
Create, edit, and manage Reddit comments with full threading support.
140
141
```python { .api }
142
class Comment:
143
def __init__(self, reddit, id: str = None, url: str = None): ...
144
145
@classmethod
146
def id_from_url(cls, url: str) -> str:
147
"""
148
Extract comment ID from Reddit URL.
149
150
Parameters:
151
- url: Reddit comment URL
152
153
Returns:
154
Comment ID (base36)
155
"""
156
157
def reply(self, body: str):
158
"""
159
Reply to comment.
160
161
Parameters:
162
- body: Reply text (markdown supported)
163
164
Returns:
165
Comment instance
166
"""
167
168
def edit(self, body: str):
169
"""
170
Edit comment text.
171
172
Parameters:
173
- body: New comment text (markdown supported)
174
175
Returns:
176
Updated Comment instance
177
"""
178
179
def delete(self):
180
"""Delete the comment."""
181
182
def save(self, category: str = None):
183
"""
184
Save comment.
185
186
Parameters:
187
- category: Save category (Reddit Premium feature)
188
"""
189
190
def unsave(self):
191
"""Unsave comment."""
192
193
def report(self, reason: str):
194
"""
195
Report comment.
196
197
Parameters:
198
- reason: Report reason
199
"""
200
201
def parent(self):
202
"""
203
Get parent comment or submission.
204
205
Returns:
206
Comment or Submission instance
207
"""
208
209
def refresh(self):
210
"""Refresh comment and load replies."""
211
```
212
213
### Comment Voting
214
215
Vote on comments with support for upvotes, downvotes, and clearing votes.
216
217
```python { .api }
218
def upvote(self):
219
"""Upvote the comment."""
220
221
def downvote(self):
222
"""Downvote the comment."""
223
224
def clear_vote(self):
225
"""Clear existing vote on comment."""
226
```
227
228
### Comment Properties and Data
229
230
Access comment metadata, content, and threading information.
231
232
```python { .api }
233
# Core properties
234
id: str # Comment ID
235
body: str # Comment text
236
body_html: str # Comment HTML
237
author: Redditor # Comment author
238
subreddit: Subreddit # Subreddit where posted
239
submission: Submission # Parent submission
240
score: int # Current score
241
ups: int # Upvote count
242
downs: int # Downvote count (always 0)
243
created_utc: float # Creation timestamp (UTC)
244
edited: bool | float # Edit timestamp or False
245
permalink: str # Comment permalink
246
247
# Threading properties
248
parent_id: str # Parent comment/submission ID
249
is_root: bool # Whether top-level comment
250
depth: int # Comment thread depth
251
replies: CommentForest # Comment replies
252
253
# Status properties
254
archived: bool # Whether archived
255
locked: bool # Whether locked
256
stickied: bool # Whether stickied
257
saved: bool # Whether saved by user
258
score_hidden: bool # Whether score hidden
259
collapsed: bool # Whether collapsed
260
is_submitter: bool # Whether author is OP
261
262
# Interaction objects
263
mod: CommentModeration # Moderation actions
264
```
265
266
### Comment Forest Navigation
267
268
Navigate and manipulate comment trees efficiently.
269
270
```python { .api }
271
class CommentForest:
272
"""Container for comment trees with lazy loading."""
273
274
def __init__(self, submission): ...
275
276
def list(self) -> list:
277
"""
278
Return flattened list of all comments.
279
280
Returns:
281
List of Comment instances
282
"""
283
284
def replace_more(self, limit: int = 32, threshold: int = 0) -> list:
285
"""
286
Replace MoreComments objects with actual comments.
287
288
Parameters:
289
- limit: Maximum MoreComments to replace
290
- threshold: Minimum comment count threshold
291
292
Returns:
293
List of MoreComments that were removed
294
"""
295
```
296
297
### Advanced Features
298
299
#### Gilding Support
300
301
Give awards and gold to submissions and comments.
302
303
```python { .api }
304
def gild(self):
305
"""Give gold award (Reddit Premium required)."""
306
307
def award(self, gild_type: str = "gid_1"):
308
"""
309
Give specific award.
310
311
Parameters:
312
- gild_type: Award type ID
313
"""
314
```
315
316
#### Media and Rich Content
317
318
Handle media uploads and rich content in submissions.
319
320
```python { .api }
321
# Inline media support
322
class InlineMedia:
323
"""Base class for inline media."""
324
325
class InlineGif(InlineMedia):
326
"""Inline GIF media."""
327
328
class InlineImage(InlineMedia):
329
"""Inline image media."""
330
331
class InlineVideo(InlineMedia):
332
"""Inline video media."""
333
```
334
335
## Usage Examples
336
337
### Creating Submissions
338
339
```python
340
# Text post
341
subreddit = reddit.subreddit("test")
342
submission = subreddit.submit(
343
title="My Text Post",
344
selftext="This is the post content with **markdown** support."
345
)
346
347
# Link post
348
submission = subreddit.submit(
349
title="Interesting Article",
350
url="https://example.com/article"
351
)
352
353
# Image post
354
submission = subreddit.submit_image(
355
title="My Image",
356
image_path="/path/to/image.jpg"
357
)
358
```
359
360
### Working with Comments
361
362
```python
363
# Get submission and add comment
364
submission = reddit.submission(id="abc123")
365
comment = submission.reply("Great post!")
366
367
# Reply to a comment
368
reply = comment.reply("Thanks for sharing!")
369
370
# Navigate comment tree
371
for top_comment in submission.comments:
372
print(f"Comment: {top_comment.body}")
373
for reply in top_comment.replies:
374
print(f" Reply: {reply.body}")
375
376
# Load all comments
377
submission.comments.replace_more(limit=None)
378
all_comments = submission.comments.list()
379
```
380
381
### Voting and Interaction
382
383
```python
384
# Vote on content
385
submission.upvote()
386
comment.downvote()
387
388
# Save interesting content
389
submission.save()
390
comment.save(category="interesting")
391
392
# Report problematic content
393
submission.report("Spam")
394
comment.report("Harassment")
395
```
396
397
## Types
398
399
```python { .api }
400
class MoreComments:
401
"""Placeholder for additional comments."""
402
count: int # Number of hidden comments
403
children: list # Child comment IDs
404
405
def comments(self, **kwargs):
406
"""Load the additional comments."""
407
408
class SubmissionFlair:
409
"""Submission flair management."""
410
411
class CommentModeration:
412
"""Comment moderation actions."""
413
414
class SubmissionModeration:
415
"""Submission moderation actions."""
416
```