Quick Start

In this section, we are going over everything you need to know to start building bots using Python Reddit API Wrapper (PRAW). It’s fun and easy. Let’s get started.

Prerequisites

Python:Obviously, you need to know at least a little Python to use PRAW; it’s a Python wrapper after all. PRAW supports Python 2.7, and Python 3.3 to 3.5. If you are stuck on a problem, /r/learnpython is a a great place to get help.
Reddit:A basic understanding of how reddit.com works is a must, although we can safely assume that a person who is reading the documentation of a Reddit API wrapper must have that covered. Just in case you don’t, here is the FAQ.

You would also need a Reddit account to register apps with Reddit before you can use their API through PRAW.

user-agent:A user-agent is a string that helps the Reddit server identify the source of the requests. To use Reddit’s API, you need a unique and descriptive user-agent string. 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-agent strings on Reddit’s API wiki page.
client ID & client secret:
 These two values are mandatory for PRAW. If you don’t already have them check out follow Redddit’s First Steps Guide and then continue below.

That’s pretty much it! You are ready to learn how to do some of the most common tasks of Reddit bot building!

Common Tasks

Obtain a Reddit Instance

You need an instance of the Reddit class to do anything with 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 settings information:

  1. user agent
  2. client ID
  3. client secret

You may choose to provide these by passing in three key-word arguments when calling the initializer of the Reddit class: user_agent, client_id, and client_secret. For example:

import praw

my_user_agent = 'my user agent'
my_client_id = 'my client ID'
my_client_secret = 'my client secret'

reddit = praw.Reddit(user_agent=my_user_agent,
                     client_id=my_client_id,
                     client_secret=my_client_secret)

Just like that, you now have a read-only Reddit instance.

print(reddit.read_only)  # Output: True

You can do limited (read-only) things with this instance like “obtaining 10 ‘hot’ submissions of the ‘learnpython’ subreddit”:

# continued from code above

for submission in reddit.subreddit('learnpython').hot(limit=10):
    print(submission.title)

# Output: 10 submission

You can do some things with a read-only instance, but not a lot. In most cases you need an authorized Reddit instance.

Authorized Reddit Instances

In order to create an authorized Reddit instance, two additional pieces of information are required:

  1. your Reddit user name, and
  2. your Reddit password

Again, you may choose to provide these by passing in key-word arguments, username and password, when you call the Reddit initializer, like this:

import praw

my_user_agent = 'my user agent'
my_client_id = 'my client ID'
my_client_secret = 'my client secret'
my_username = 'my username'
my_password = 'my password'

reddit = praw.Reddit(user_agent=my_user_agent,
                     client_id=my_client_id,
                     client_secret=my_client_secret,
                     username=my_username,
                     password=my_password)

print(reddit.read_only)  # Output: False

Now you can do whatever your Reddit account is authorized to do. And you can switch back to read-only mode whenever you want:

# continued from code above
reddit.read_only = True

Note

If you are uncomfortable hard coding your credentials into your program, there are some options available to you. Please see: Configuring PRAW.

Obtain a Subreddit

To obtain a Subreddit instance, all you need to know is the subreddit’s display name. Pass that name when calling subreddit on your Reddit instance. For example:

# 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 ...

Obtain Submission Instances from a Subreddit

Now that you have a Subreddit instance, you can obtain some submissions (Submission instances) from it! There are several ways of sorting all the submissions of a subreddit: hot, new, top, etc. A Subreddit instance has a method for each of these sorting approaches, namely, these:

  • controversial
  • gilded
  • hot
  • new
  • rising
  • top

Each of these methods will immediately return a ListingGenerator, which is something that you can iterate through. For example:

# assume you have a Subreddit instance bound to variable `subreddit`
for submission in subreddit.hot(limit=10):
    print(submission.title)  # Output: the title of the submission
    print(submission.ups)    # Output: upvote count
    print(submission.id)     # Output: the ID of the submission
    print(submission.url)    # Output: the URL the submission points to
                             # or the the submission 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 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/...')

Obtain Redditor Instances

There are several ways to obtain a redditor (a Redditor instance), two of the most common ones are:

For example:

# assume you have a Reddit instance bound to variable `reddit`
# assume you have a Submission instance bound to variable `submission`
redditor1 = submission.author
print(redditor1.name) # Output: name of the redditor

redditor2 = reddit.redditor('bboe')
print(redditor2.link_karma) # Output: 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 (best). 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()

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 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 MoreComments instances scattered throughout the forest. Replace those MoreComments instances at any time by calling replace_more() on a CommentForest instance. See Extracting comments with PRAW for an example.

Determine Available Attributes of an Object

If you have a PRAW object, be it Submission or Comment, and you want to see what attributes are available and their values, use the built-in vars function of python. For example:

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 to only make API calls when the information is needed. Here, before the print line, submission points to a lazy Submission object. When we try to print its title, information is needed, so it ceased to be lazy – PRAW makes the actual API call at this point. Now it is a good time to print out all the available attributes and their values!