Quick Start
In this section, we go over everything you need to know to start building scripts or bots using Async PRAW, the Asynchronous Python Reddit API Wrapper. It’s fun and easy. Let’s get started.
Prerequisites
- Python Knowledge:
You need to know at least a little Python and some understanding of asynchronous usage in Python to use Async PRAW. Async PRAW supports Python 3.7+. If you are stuck on a problem, r/learnpython is a great place to ask for help.
- 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.
Common Tasks
Obtain a Reddit
Instance
Warning
For the sake of brevity, the following examples pass authentication information via
arguments to asyncpraw.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.
You need an instance of the Reddit
class to do anything with Async PRAW.
There are two distinct states a Reddit
instance can be in: read-only, and authorized.
Read-only Reddit
Instances
To create a read-only Reddit
instance, you need three pieces of information:
Client ID
Client secret
User agent
You may choose to provide these by passing in three keyword arguments when calling the
initializer of the Reddit
class: client_id
, client_secret
,
user_agent
(see Configuring Async PRAW for other methods of providing this
information). For example:
import asyncpraw
reddit = asyncpraw.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 Reddit
instance.
print(reddit.read_only)
# Output: True
With a read-only instance, you can do something like obtaining 10 “hot” submissions from
r/test
:
# continued from code above
subreddit = await reddit.subreddit("test")
async for submission in subreddit.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
authorized Reddit
instance.
Note
In the above example we are limiting the results to 10
. Without the limit
parameter Async 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 limit=None
.
Obtain a Subreddit
To obtain a Subreddit
instance, pass the subreddit’s name when calling
subreddit
on your Reddit
instance. For example:
# assume you have a asyncpraw.Reddit instance bound to variable `reddit`
subreddit = await reddit.subreddit("redditdev", fetch=True)
print(subreddit.display_name)
# Output: redditdev
print(subreddit.title)
# Output: reddit development
print(subreddit.description)
# Output: a subreddit for discussion of ...
Obtain Submission
Instances from a Subreddit
Now that you have a Subreddit
instance, you can iterate through some of its
submissions, each bound to an instance of Submission
. There are several sorts
that you can iterate through:
controversial
gilded
hot
new
rising
top
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
the hot
sort for a given subreddit try:
# assume you have a Subreddit instance bound to variable `subreddit`
async 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
Note
The act of calling a method that returns a ListingGenerator
does not
result in any network requests until you begin to iterate through the
ListingGenerator
.
You can create Submission
instances in other ways too:
# assume you have a asyncpraw.Reddit instance bound to variable `reddit`
submission = await reddit.submission("39zje0")
print(submission.title)
# Output: reddit will soon only be available ...
# or
submission = await reddit.submission(url="https://www.reddit.com/...")
Obtain Redditor
Instances
There are several ways to obtain a redditor (a Redditor
instance). Two of the
most common ones are:
via the
author
attribute of aSubmission
orComment
instancevia the
redditor()
method ofReddit
For example:
# 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 asyncpraw.Reddit instance bound to variable `reddit`
redditor2 = await reddit.redditor("bboe", fetch=True)
print(redditor2.link_karma)
# Output: u/bboe's karma
Obtain Comment
Instances
Submissions have a comments
attribute that is a CommentForest
instance.
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 asyncpraw.Reddit instance bound to variable `reddit`
top_level_comments = await submission.comments()
all_comments = await submission.comments.list()
Note
The comment sort order can be changed by updating the value of comment_sort
on
the Submission
instance prior to accessing comments
(see:
/api/set_suggested_sort for possible values).
For example, to have comments sorted by new
try something like:
# assume you have a asyncpraw.Reddit instance bound to variable `reddit`
submission = await reddit.submission("39zje0")
submission.comment_sort = "new"
top_level_comments = await submission.comments()
As you may be aware there will periodically be MoreComments
instances
scattered throughout the forest. Replace those MoreComments
instances at any
time by calling replace_more()
on a CommentForest
instance. Calling
replace_more()
access comments
, and so must be done after comment_sort
is
updated. See Extracting comments with Async PRAW for an example.
Determine Available Attributes of an Object
If you have a Async PRAW object, e.g., Comment
, Message
,
Redditor
, or Submission
, and you want to see what attributes are
available along with their values, use the built-in vars()
function of python.
For example:
import pprint
# assume you have a asyncpraw.Reddit instance bound to variable `reddit`
submission = await reddit.submission("39zje0")
pprint.pprint(vars(submission))