0
# PRAW (Python Reddit API Wrapper)
1

2
PRAW provides simple access to Reddit's API while following all of Reddit's API rules automatically. It handles authentication, rate limiting, and API compliance, making it easy to build Reddit bots, data analysis tools, content aggregators, and moderation utilities. PRAW supports both script-based and web application OAuth flows and provides extensive object-oriented models for Reddit entities.
3

4
## Package Information
5

6
- **Package Name**: praw
7
- **Language**: Python
8
- **Installation**: `pip install praw`
9
- **Supported Python**: 3.8+
10

11
## Core Imports
12

13
```python
14
import praw
15
```
16

17
Primary usage:
18
```python
19
from praw import Reddit
20
```
21

22
## Basic Usage
23

24
```python
25
import praw
26

27
# Create Reddit instance with script authentication
28
reddit = praw.Reddit(
29
    client_id="CLIENT_ID",
30
    client_secret="CLIENT_SECRET", 
31
    password="PASSWORD",
32
    user_agent="USERAGENT",
33
    username="USERNAME",
34
)
35

36
# Access a subreddit
37
subreddit = reddit.subreddit("python")
38

39
# Submit a new post
40
submission = subreddit.submit("My Title", selftext="My post content")
41

42
# Get top submissions
43
for submission in subreddit.hot(limit=10):
44
    print(submission.title)
45
    
46
# Reply to a submission
47
submission.reply("Great post!")
48

49
# Access user information
50
redditor = reddit.redditor("username")
51
print(f"User karma: {redditor.comment_karma}")
52
```
53

54
## Architecture
55

56
PRAW is built around a central `Reddit` client that provides access to specialized helper objects and models:
57

58
- **Reddit Client**: Main entry point managing authentication and API requests
59
- **Models**: Object-oriented representations of Reddit entities (Submission, Comment, Subreddit, Redditor)
60
- **Helpers**: Specialized classes for discovery, authentication, and content management
61
- **Listing Generators**: Efficient iteration over API results with automatic pagination
62

63
## Capabilities
64

65
### Reddit Client
66

67
Core Reddit API client providing authentication, request handling, and access to all Reddit functionality.
68

69
```python { .api }
70
class Reddit:
71
    def __init__(
72
        self,
73
        site_name: str = None,
74
        config_interpolation: str = None,
75
        requestor_class = None,
76
        requestor_kwargs: dict = None,
77
        token_manager = None,
78
        **config_settings
79
    ): ...
80
    
81
    def comment(self, id: str = None, url: str = None): ...
82
    def submission(self, id: str = None, url: str = None): ...
83
    def redditor(self, name: str = None, fullname: str = None): ...
84
    def subreddit(self, display_name: str): ...
85
    def random_subreddit(self, nsfw: bool = False): ...
86
    def info(self, fullnames: list = None, subreddits: list = None, url: str = None): ...
87
    def username_available(self, name: str) -> bool: ...
88
    def domain(self, domain: str): ...
89
    
90
    # HTTP Methods
91
    def get(self, path: str, params: dict = None): ...
92
    def post(self, path: str, data: dict = None, files: dict = None, json: dict = None, params: dict = None): ...
93
    def put(self, path: str, data: dict = None, json: dict = None): ...
94
    def patch(self, path: str, data: dict = None, json: dict = None, params: dict = None): ...
95
    def delete(self, path: str, data: dict = None, json: dict = None, params: dict = None): ...
96
    def request(self, method: str, path: str, params: dict = None, data: dict = None, files: dict = None, json: dict = None): ...
97
    
98
    # Properties
99
    read_only: bool
100
    validate_on_submit: bool
101
    
102
    # Helper Objects
103
    auth: Auth
104
    front: Front
105
    inbox: Inbox
106
    user: User
107
    subreddits: Subreddits
108
    redditors: Redditors
109
    drafts: DraftHelper
110
    live: LiveHelper
111
    multireddit: MultiredditHelper
112
    notes: RedditModNotes
113
```
114

115
[Reddit Client](./reddit-client.md)
116

117
### Submissions and Comments
118

119
Interact with Reddit posts and comments including creating, editing, voting, and managing content.
120

121
```python { .api }
122
class Submission:
123
    def submit(self, title: str, **kwargs): ...
124
    def reply(self, body: str): ...
125
    def edit(self, body: str): ...
126
    def delete(self): ...
127
    def upvote(self): ...
128
    def downvote(self): ...
129
    def clear_vote(self): ...
130

131
class Comment:
132
    def reply(self, body: str): ...
133
    def edit(self, body: str): ...
134
    def delete(self): ...
135
    def parent(self): ...
136
```
137

138
[Submissions and Comments](./submissions-comments.md)
139

140
### Subreddits
141

142
Access and manage subreddit communities including posting, searching, moderation, and configuration.
143

144
```python { .api }
145
class Subreddit:
146
    def submit(self, title: str, **kwargs): ...
147
    def search(self, query: str, **kwargs): ...
148
    def subscribe(self): ...
149
    def unsubscribe(self): ...
150
    def message(self, subject: str, message: str, **kwargs): ...
151
    def hot(self, **kwargs): ...
152
    def new(self, **kwargs): ...
153
    def top(self, **kwargs): ...
154
```
155

156
[Subreddits](./subreddits.md)
157

158
### User Management
159

160
Work with Reddit users including profiles, messaging, friends, and user-generated content.
161

162
```python { .api }
163
class Redditor:
164
    def message(self, subject: str, message: str, **kwargs): ...
165
    def friend(self): ...
166
    def unfriend(self): ...
167
    def block(self): ...
168
    def unblock(self): ...
169

170
class User:
171
    def me(self): ...
172
    def karma(self): ...
173
    def friends(self): ...
174
    def blocked(self): ...
175
```
176

177
[User Management](./user-management.md)
178

179
### Authentication
180

181
Handle OAuth authentication flows including script apps, web apps, and token management.
182

183
```python { .api }
184
class Auth:
185
    def authorize(self, code: str): ...
186
    def implicit(self, access_token: str, expires_in: int, scope: str): ...
187
    def url(self, scopes: list, state: str, **kwargs) -> str: ...
188
    def revoke_token(self, token: str, **kwargs): ...
189
    def scopes(self) -> set: ...
190
```
191

192
[Authentication](./authentication.md)
193

194
### Content Discovery
195

196
Discover content across Reddit including front page, popular posts, trending subreddits, and user discovery.
197

198
```python { .api }
199
class Front:
200
    def best(self, **kwargs): ...
201
    def hot(self, **kwargs): ...
202
    def new(self, **kwargs): ...
203
    def top(self, **kwargs): ...
204
    def controversial(self, **kwargs): ...
205

206
class Subreddits:
207
    def popular(self, **kwargs): ...
208
    def new(self, **kwargs): ...
209
    def search(self, query: str, **kwargs): ...
210
```
211

212
[Content Discovery](./content-discovery.md)
213

214
### Messaging and Inbox
215

216
Manage private messages, modmail, notifications, and inbox functionality.
217

218
```python { .api }
219
class Inbox:
220
    def all(self, **kwargs): ...
221
    def unread(self, **kwargs): ...
222
    def messages(self, **kwargs): ...
223
    def comment_replies(self, **kwargs): ...
224
    def submission_replies(self, **kwargs): ...
225
    def mentions(self, **kwargs): ...
226
```
227

228
[Messaging and Inbox](./messaging-inbox.md)
229

230
### Moderation
231

232
Comprehensive moderation tools for submissions, comments, users, and subreddit management.
233

234
```python { .api }
235
class SubredditModeration:
236
    def approve(self, thing): ...
237
    def remove(self, thing, **kwargs): ...
238
    def spam(self, thing): ...
239
    def distinguish(self, thing, **kwargs): ...
240
    def ignore_reports(self, thing): ...
241
    def unignore_reports(self, thing): ...
242
```
243

244
[Moderation](./moderation.md)
245

246
### Live Threads
247

248
Create and manage Reddit live threads for real-time event coverage.
249

250
```python { .api }
251
class LiveHelper:
252
    def create(self, title: str, **kwargs): ...
253
    def info(self, ids: list): ...
254
    def now(self): ...
255

256
class LiveThread:
257
    def contribute(self): ...
258
    def discussions(self, **kwargs): ...
259
    def updates(self, **kwargs): ...
260
```
261

262
[Live Threads](./live-threads.md)
263

264
### Exception Handling
265

266
PRAW-specific exceptions for error handling and API response management.
267

268
```python { .api }
269
class PRAWException(Exception): ...
270
class RedditAPIException(PRAWException): ...
271
class APIException(PRAWException): ...
272
class ClientException(PRAWException): ...
273
class InvalidURL(ClientException): ...
274
class ReadOnlyException(ClientException): ...
275
class TooLargeMediaException(ClientException): ...
276
class DuplicateReplaceException(ClientException): ...
277
class InvalidFlairTemplateID(ClientException): ...
278
class InvalidImplicitAuth(ClientException): ...
279
class MissingRequiredAttributeException(ClientException): ...
280
class WebSocketException(ClientException): ...
281
class MediaPostFailed(WebSocketException): ...
282
```
283

284
## Types
285

286
```python { .api }
287
class Reddit:
288
    """Main Reddit API client."""
289
    read_only: bool
290
    validate_on_submit: bool
291
    auth: Auth
292
    front: Front
293
    inbox: Inbox
294
    user: User
295
    subreddits: Subreddits
296
    redditors: Redditors
297
    drafts: DraftHelper
298
    live: LiveHelper
299
    multireddit: MultiredditHelper
300
    notes: RedditModNotes
301

302
class Submission:
303
    """Reddit submission/post."""
304
    id: str
305
    title: str
306
    author: Redditor
307
    subreddit: Subreddit
308
    score: int
309
    num_comments: int
310
    created_utc: float
311
    url: str
312
    selftext: str
313
    thumbnail: str
314
    is_self: bool
315
    permalink: str
316
    shortlink: str
317
    stickied: bool
318
    over_18: bool
319
    spoiler: bool
320
    locked: bool
321
    
322
class Comment:
323
    """Reddit comment."""
324
    id: str
325
    author: Redditor
326
    body: str
327
    score: int
328
    created_utc: float
329
    is_root: bool
330
    replies: CommentForest
331
    permalink: str
332
    parent_id: str
333
    link_id: str
334
    subreddit: Subreddit
335
    stickied: bool
336
    is_submitter: bool
337

338
class Subreddit:
339
    """Reddit subreddit."""
340
    display_name: str
341
    subscribers: int
342
    description: str
343
    public_description: str
344
    over18: bool
345
    url: str
346
    created_utc: float
347
    subreddit_type: str
348
    lang: str
349
    title: str
350
    active_user_count: int
351
    
352
class Redditor:
353
    """Reddit user."""
354
    name: str
355
    comment_karma: int
356
    link_karma: int
357
    created_utc: float
358
    is_gold: bool
359
    is_mod: bool
360
    is_employee: bool
361
    has_verified_email: bool
362
    id: str
363
    verified: bool
364
    
365
class CommentForest:
366
    """Container for comment replies."""
367
    def replace_more(self, limit: int = 32, threshold: int = 0) -> list: ...
368
    def list(self) -> list[Comment]: ...
369
    
370
class More:
371
    """Represents collapsed comment threads."""
372
    count: int
373
    children: list[str]
374
    
375
class DraftHelper:
376
    """Helper for managing draft submissions."""
377
    def __call__(self, draft_id: str = None): ...
378
    
379
class LiveHelper:
380
    """Helper for live thread functionality."""
381
    def __call__(self, id: str): ...
382
    def create(self, title: str, **kwargs): ...
383
    def info(self, ids: list): ...
384
    def now(self): ...
385
    
386
class MultiredditHelper:
387
    """Helper for multireddit functionality."""
388
    def __call__(self, name: str, redditor: str): ...
389
    
390
class RedditModNotes:
391
    """Helper for moderator notes functionality."""
392
    def create(self, **kwargs): ...
393
    def delete(self, delete_id: str): ...
394
```