In this section, we go over everything you need to know to start building scripts or bots using PRAW, the Python Reddit API Wrapper. It’s fun and easy. Let’s get started.
- Python Knowledge
- Reddit Knowledge
A basic understanding of how Reddit works is a must. In the event you are not already familiar with Reddit start at Reddit Help.
- Reddit Account
A Reddit account is required to access Reddit’s API. Create one at reddit.com.
- Client ID & Client Secret
These two values are needed to access Reddit’s API as a script application (see Authenticating via OAuth for other application types). If you don’t already have a client ID and client secret, follow Reddit’s First Steps Guide to create them.
- User Agent
A user agent is a unique identifier that helps Reddit determine the source of network requests. To use Reddit’s API, you need a unique and descriptive user agent. The recommended format is
<platform>:<app ID>:<version string> (by u/<Reddit username>). For example,
android:com.example.myredditapp:v1.2.3 (by u/kemitche). Read more about user agents at Reddit’s API wiki page.
With these prerequisites satisfied, you are ready to learn how to do some of the most common tasks with Reddit’s API.
For the sake of brevity, the following examples pass authentication information via
praw.Reddit(). If you do this, you need to be careful not to
reveal this information to the outside world if you share your code. It is
recommended to use a praw.ini file in order to keep your
authentication information separate from your code.
To create a read-only
You may choose to provide these by passing in three keyword arguments when calling the
initializer of the
user_agent (see Configuring PRAW for other methods of providing this
information). For example:
import praw reddit = praw.Reddit( client_id="my client id", client_secret="my client secret", user_agent="my user agent", )
Just like that, you now have a read-only
print(reddit.read_only) # Output: True
With a read-only instance, you can do something like obtaining 10 “hot” submissions from
# continued from code above for submission in reddit.subreddit("learnpython").hot(limit=10): print(submission.title) # Output: 10 submissions
If you want to do more than retrieve public information from Reddit, then you need an
In the above example we are limiting the results to 10. Without the
parameter PRAW should yield as many results as it can with a single request. For
most endpoints this results in 100 items per request. If you want to retrieve as
many as possible pass in
# assume you have a reddit instance bound to variable `reddit` subreddit = reddit.subreddit("redditdev") print(subreddit.display_name) # Output: redditdev print(subreddit.title) # Output: reddit development print(subreddit.description) # Output: a subreddit for discussion of ...
Submission Instances from a
Each of these methods will immediately return a
ListingGenerator, which is to
be iterated through. For example, to iterate through the first 10 submissions based on
hot sort for a given subreddit try:
# assume you have a Subreddit instance bound to variable `subreddit` for submission in subreddit.hot(limit=10): print(submission.title) # Output: the submission's title print(submission.score) # Output: the submission's score print(submission.id) # Output: the submission's ID print(submission.url) # Output: the URL the submission points to or the submission's URL if it's a self post
You can create
Submission instances in other ways too:
# assume you have a Reddit instance bound to variable `reddit` submission = reddit.submission(id="39zje0") print(submission.title) # Output: reddit will soon only be available ... # or submission = reddit.submission(url="https://www.reddit.com/...")
There are several ways to obtain a redditor (a
Redditor instance). Two of the
most common ones are:
# assume you have a Submission instance bound to variable `submission` redditor1 = submission.author print(redditor1.name) # Output: name of the redditor # assume you have a Reddit instance bound to variable `reddit` redditor2 = reddit.redditor("bboe") print(redditor2.link_karma) # Output: u/bboe's karma
Submissions have a
comments attribute that is a
That instance is iterable and represents the top-level comments of the submission by the
default comment sort (
confidence). If you instead want to iterate over all
comments as a flattened list you can call the
list() method on a
CommentForest instance. For example:
# assume you have a Reddit instance bound to variable `reddit` top_level_comments = list(submission.comments) all_comments = submission.comments.list()
The comment sort order can be changed by updating the value of
Submission instance prior to accessing
/api/set_suggested_sort for possible values).
For example to have comments sorted by
new try something like:
# assume you have a Reddit instance bound to variable `reddit` submission = reddit.submission(id="39zje0") submission.comment_sort = "new" top_level_comments = list(submission.comments)
As you may be aware there will periodically be
scattered throughout the forest. Replace those
MoreComments instances at any
time by calling
replace_more() on a
CommentForest instance. Calling
comments, and so must be done after
updated. See Extracting comments with PRAW for an example.
Determine Available Attributes of an Object
If you have a PRAW object, e.g.,
Submission, and you want to see what attributes are
available along with their values, use the built-in
vars() function of python.
import pprint # assume you have a Reddit instance bound to variable `reddit` submission = reddit.submission(id="39zje0") print(submission.title) # to make it non-lazy pprint.pprint(vars(submission))
Note the line where we print the title. PRAW uses lazy objects so that network requests
to Reddit’s API are only issued when information is needed. Here, before the print line,
submission points to a lazy
Submission object. When we try to print its
title, additional information is needed, thus a network request is made, and the
instances ceases to be lazy. Outputting all the attributes of a lazy object will result
in fewer attributes than expected.