Code Overview

Here you will find an overview of PRAW’s objects and methods, but not the objects attributes who are generated dynamically from reddit’s responses and are thus impossible to accurately describe statically. In Writing a reddit Bot there is a longer discussion of how to introspect PRAW, which you can use in conjunction with this nice visual overview.

praw Package

Python Reddit API Wrapper.

PRAW, an acronym for “Python Reddit API Wrapper”, is a python package that allows for simple access to reddit’s API. PRAW aims to be as easy to use as possible and is designed to follow all of reddit’s API rules. You have to give a useragent, everything else is handled by PRAW so you needn’t worry about violating them.

More information about PRAW can be found at https://github.com/praw-dev/praw

class praw.__init__.AuthenticatedReddit(*args, **kwargs)

Bases: praw.__init__.OAuth2Reddit, praw.__init__.UnauthenticatedReddit

This class adds the methods necessary for authenticating with reddit.

Authentication can either be login based (through login), or OAuth2 based (via set_access_credentials).

You should not directly instantiate instances of this class. Use Reddit instead.

Initialize an AuthenticatedReddit instance.

accept_moderator_invite(subreddit)

Accept a moderator invite to the given subreddit.

Callable upon an instance of Subreddit with no arguments.

Requires user/password authentication.

Returns:The json response from the server.
clear_authentication()

Clear any existing authentication on the reddit object.

This function is implicitly called on login and set_access_credentials.

delete(password, message=u'')

Delete the currently authenticated redditor.

WARNING!

This action is IRREVERSIBLE. Use only if you’re okay with NEVER accessing this reddit account again.

Parameters:
  • password – password for currently authenticated account
  • message – optional ‘reason for deletion’ message.
Returns:

json response from the server.

edit_wiki_page(subreddit, page, content, reason=u'')

Create or edit a wiki page with title page for subreddit.

Returns:The json response from the server.
get_access_information(code, update_session=True)

Return the access information for an OAuth2 authorization grant.

Parameters:
  • code – the code received in the request from the OAuth2 server
  • update_session – Update the current session with the retrieved token(s).
Returns:

A dictionary with the key/value pairs for access_token, refresh_token and scope. The refresh_token value will be done when the OAuth2 grant is not refreshable.

get_flair_choices(subreddit, link=None)

Return available flair choices and current flair.

Requires the flair oauth scope or user/password authentication.

Parameters:link – If link is given, return the flair options for this submission. Not normally given directly, but instead set by calling the flair_choices method for Submission objects. use the default for the session’s user.
Returns:A dictionary with 2 keys. ‘current’ containing current flair settings for the authenticated user and ‘choices’ containing a list of possible flair choices.
get_me()

Return a LoggedInRedditor object.

Note: This function is only intended to be used with a ‘identity’ providing OAuth2 grant. Requires the identity oauth scope or user/password authentication.

has_scope(scope)

Return True if OAuth2 authorized for the passed in scope.

is_logged_in()

Return True when session is authenticated via login.

is_oauth_session()

Return True when the current session is an OAuth2 session.

login(username=None, password=None)

Login to a reddit site.

Look for username first in parameter, then praw.ini and finally if both were empty get it from stdin. Look for password in parameter, then praw.ini (but only if username matches that in praw.ini) and finally if they both are empty get it with getpass. Add the variables user (username) and pswd (password) to your praw.ini file to allow for auto-login.

A successful login will overwrite any existing authentication.

DEPRECATED. Will be removed in a future version of PRAW. Password-based authentication will stop working on 2015/08/03 and as a result will be removed in PRAW4.

For more information please see: https://www.reddit.com/comments/2ujhkr/ Pass disable_warning=True to login to disable this warning.

refresh_access_information(refresh_token=None, update_session=True)

Return updated access information for an OAuth2 authorization grant.

Parameters:
  • refresh_token – The refresh token used to obtain the updated information. When not provided, use the stored refresh_token.
  • update_session – Update the session with the returned data.
Returns:

A dictionary with the key/value pairs for access_token, refresh_token and scope. The refresh_token value will be done when the OAuth2 grant is not refreshable. The scope value will be a set containing the scopes the tokens are valid for.

select_flair(item, flair_template_id=u'', flair_text=u'')

Select user flair or link flair on subreddits.

This can only be used for assigning your own name flair or link flair on your own submissions. For assigning other’s flairs using moderator access, see set_flair().

Requires user/password authentication.

Parameters:
  • item – A string, Subreddit object (for user flair), or Submission object (for link flair). If item is a string it will be treated as the name of a Subreddit.
  • flair_template_id – The id for the desired flair template. Use the get_flair_choices() and get_flair_choices() methods to find the ids for the available user and link flair choices.
  • flair_text – A String containing the custom flair text. Used on subreddits that allow it.
Returns:

The json response from the server.

set_access_credentials(scope, access_token, refresh_token=None, update_user=True)

Set the credentials used for OAuth2 authentication.

Calling this function will overwrite any currently existing access credentials.

Parameters:
  • scope – A set of reddit scopes the tokens provide access to
  • access_token – the access_token of the authentication
  • refresh_token – the refresh token of the authentication
  • update_user – Whether or not to set the user attribute for identity scopes
class praw.__init__.BaseReddit(user_agent, site_name=None, handler=None, disable_update_check=False, **kwargs)

Bases: object

A base class that allows access to reddit’s API.

You should not directly instantiate instances of this class. Use Reddit instead.

Initialize our connection with a reddit server.

The user_agent is how your application identifies itself. Read the official API guidelines for user_agents https://github.com/reddit/reddit/wiki/API. Applications using default user_agents such as “Python/urllib” are drastically limited.

site_name allows you to specify which reddit you want to connect to. The installation defaults are reddit.com, if you only need to connect to reddit.com then you can safely ignore this. If you want to connect to another reddit, set site_name to the name of that reddit. This must match with an entry in praw.ini. If site_name is None, then the site name will be looked for in the environment variable REDDIT_SITE. If it is not found there, the default site name reddit matching reddit.com will be used.

disable_update_check allows you to prevent an update check from occurring in spite of the check_for_updates setting in praw.ini.

All additional parameters specified via kwargs will be used to initialize the Config object. This can be used to specify configuration settings during instantiation of the Reddit instance. See https://praw.readthedocs.org/en/latest/pages/configuration_files.html for more details.

RETRY_CODES = [502, 503, 504]
evict(urls)

Evict url(s) from the cache.

Parameters:urls – An iterable containing normalized urls.
Returns:The number of items removed from the cache.
get_content(url, params=None, limit=0, place_holder=None, root_field=u'data', thing_field=u'children', after_field=u'after', _use_oauth=False, object_filter=None)

A generator method to return reddit content from a URL.

Starts at the initial url, and fetches content using the after JSON data until limit entries have been fetched, or the place_holder has been reached.

Parameters:
  • url – the url to start fetching content from
  • params – dictionary containing extra GET data to put in the url
  • limit – the number of content entries to fetch. If limit <= 0, fetch the default for your account (25 for unauthenticated users). If limit is None, then fetch as many entries as possible (reddit returns at most 100 per request, however, PRAW will automatically make additional requests as necessary).
  • place_holder (a string corresponding to a reddit base36 id without prefix, e.g. ‘asdfasdf’) – if not None, the method will fetch limit content, stopping if it finds content with id equal to place_holder. The place_holder item is the last item to be yielded from this generator. Note that the use of place_holder is not 100% reliable as the place holder item may no longer exist due to being removed or deleted.
  • root_field – indicates the field in the json response that holds the data. Most objects use ‘data’, however some (flairlist) don’t have the ‘data’ object. Use None for the root object.
  • thing_field – indicates the field under the root_field which contains the list of things. Most objects use ‘children’.
  • after_field – indicates the field which holds the after item element
  • object_filter – if set to an integer value, fetch content from the corresponding list index in the JSON response. For example the JSON response for submission duplicates is a list of objects, and the object we want to fetch from is at index 1. So we set object_filter=1 to filter out the other useless list elements.
Returns:

a list of reddit content, of type Subreddit, Comment, Submission or user flair.

request(url, params=None, data=None, retry_on_error=True)

Make a HTTP request and return the response.

Parameters:
  • url – the url to grab content from.
  • params – a dictionary containing the GET data to put in the url
  • data – a dictionary containing the extra data to submit
  • retry_on_error – if True retry the request, if it fails, for up to 3 attempts
Returns:

The HTTP response.

request_json(url, params=None, data=None, as_objects=True, retry_on_error=True)

Get the JSON processed from a page.

Parameters:
  • url – the url to grab content from.
  • params – a dictionary containing the GET data to put in the url
  • data – a dictionary containing the extra data to submit
  • as_objects – if True return reddit objects else raw json dict.
  • retry_on_error – if True retry the request, if it fails, for up to 3 attempts
Returns:

JSON processed page

update_checked = False
class praw.__init__.Config(site_name, **kwargs)

Bases: object

A class containing the configuration for a reddit site.

Initialize PRAW’s configuration.

API_PATHS = {u'comment': u'api/comment/', u'help': u'help/', u'duplicates': u'duplicates/%s/', u'username_available': u'api/username_available/', u'subreddit': u'r/%s/', u'subreddit_css': u'api/subreddit_stylesheet/', u'controversial': u'controversial/', u'select_flair': u'api/selectflair/', u'saved': u'saved/', u'blocked': u'prefs/blocked/', u'subreddit_comments': u'r/%s/comments/', u'compose': u'api/compose/', u'morechildren': u'api/morechildren/', u'user_about': u'user/%s/about/', u'save': u'api/save/', u'sent': u'message/sent/', u'info': u'api/info/', u'deleteflair': u'api/deleteflair', u'banned': u'r/%s/about/banned/', u'subreddit_settings': u'r/%s/about/edit/', u'accept_mod_invite': u'api/accept_moderator_invite', u'report': u'api/report/', u'edit': u'api/editusertext/', u'marknsfw': u'api/marknsfw/', u'remove': u'api/remove/', u'unmarknsfw': u'api/unmarknsfw/', u'gild_user': u'api/v1/gold/give/{username}/', u'ignore_reports': u'api/ignore_reports/', u'multireddit': u'user/%s/m/%s/', u'flair': u'api/flair/', u'contest_mode': u'api/set_contest_mode/', u'flairlist': u'r/%s/api/flairlist/', u'site_admin': u'api/site_admin/', u'my_con_subreddits': u'subreddits/mine/contributor/', u'mod_mail': u'r/%s/message/moderator/', u'subreddit_about': u'r/%s/about/', u'hide': u'api/hide/', u'my_multis': u'api/multi/mine/', u'unhide': u'api/unhide/', u'comments': u'comments/', u'modlog': u'r/%s/about/log/', u'wiki_page': u'r/%s/wiki/%s', u'new': u'new/', u'sub_comments_gilded': u'r/%s/comments/gilded/', u'distinguish': u'api/distinguish/', u'sticky_submission': u'api/set_subreddit_sticky/', u'search': u'r/%s/search/', u'multireddit_about': u'api/multi/user/%s/m/%s/', u'messages': u'message/messages/', u'reports': u'r/%s/about/reports/', u'moderators': u'r/%s/about/moderators/', u'delete_redditor': u'api/delete_user', u'mentions': u'message/mentions', u'login': u'api/login/', u'approve': u'api/approve/', u'authorize': u'api/v1/authorize/', u'unmoderated': u'r/%s/about/unmoderated/', u'flairconfig': u'api/flairconfig/', u'domain': u'domain/%s/', u'subscribe': u'api/subscribe/', u'rising': u'rising/', u'inbox': u'message/inbox/', u'vote': u'api/vote/', u'message': u'message/messages/%s/', u'flairtemplate': u'api/flairtemplate/', u'spam': u'r/%s/about/spam/', u'top': u'top/', u'submit': u'api/submit/', u'stylesheet': u'r/%s/about/stylesheet/', u'unignore_reports': u'api/unignore_reports/', u'friend': u'api/friend/', u'popular_subreddits': u'subreddits/popular/', u'unread_message': u'api/unread_message/', u'unfriend': u'api/unfriend/', u'upload_image': u'api/upload_sr_img', u'access_token_url': u'api/v1/access_token/', u'me': u'api/v1/me', u'reddit_url': u'/', u'subreddit_random': u'r/%s/random/', u'search_reddit_names': u'api/search_reddit_names/', u'modqueue': u'r/%s/about/modqueue/', u'del': u'api/del/', u'unread': u'message/unread/', u'clearflairtemplates': u'api/clearflairtemplates/', u'gild_thing': u'api/v1/gold/gild/{fullname}/', u'wiki_edit': u'api/wiki/edit/', u'contributors': u'r/%s/about/contributors/', u'my_subreddits': u'subreddits/mine/subscriber/', u'by_id': u'by_id/', u'delete_sr_header': u'r/%s/api/delete_sr_header', u'new_subreddits': u'subreddits/new/', u'sticky': u'r/%s/about/sticky/', u'captcha': u'captcha/', u'wiki_contributors': u'r/%s/about/wikicontributors/', u'read_message': u'api/read_message/', u'flaircsv': u'api/flaircsv/', u'wiki_pages': u'r/%s/wiki/pages/', u'unsave': u'api/unsave/', u'sub_recommendations': u'api/recommend/sr/{0}', u'flairselector': u'api/flairselector/', u'user': u'user/%s/', u'wiki_banned': u'r/%s/about/wikibanned/', u'friends': u'prefs/friends/', u'multireddit_mine': u'me/m/%s/', u'my_mod_subreddits': u'subreddits/mine/moderator/', u'delete_sr_image': u'r/%s/api/delete_sr_img', u'register': u'api/register/'}
WWW_PATHS = set([u'authorize'])
short_domain

Return the short domain of the reddit.

Used to generate the shortlink. For reddit.com the short_domain is redd.it and generate shortlinks like http://redd.it/y3r8u

class praw.__init__.ModConfigMixin(*args, **kwargs)

Bases: praw.__init__.AuthenticatedReddit

Adds methods requiring the ‘modconfig’ scope (or mod access).

You should not directly instantiate instances of this class. Use Reddit instead.

Initialize an AuthenticatedReddit instance.

create_subreddit(name, title, description=u'', language=u'en', subreddit_type=u'public', content_options=u'any', over_18=False, default_set=True, show_media=False, domain=u'', wikimode=u'disabled', captcha=None)

Create a new subreddit.

This function may result in a captcha challenge. PRAW will automatically prompt you for a response. See How can I handle captchas myself? if you want to manually handle captchas.

Requires the modconfig oauth scope or user/password authentication.

Returns:The json response from the server.
delete_image(subreddit, name=None, header=False)

Delete an image from the subreddit.

Requires the modconfig oauth scope or user/password authentication as a mod of the subreddit.

Parameters:
  • name – The name of the image if removing a CSS image.
  • header – When true, delete the subreddit header.
Returns:

The json response from the server.

get_settings(subreddit, **params)

Return the settings for the given subreddit.

Requires the modconfig oauth scope or user/password authentication as a mod of the subreddit.

set_settings(subreddit, title, public_description=u'', description=u'', language=u'en', subreddit_type=u'public', content_options=u'any', over_18=False, default_set=True, show_media=False, domain=u'', domain_css=False, domain_sidebar=False, header_hover_text=u'', wikimode=u'disabled', wiki_edit_age=30, wiki_edit_karma=100, submit_link_label=u'', submit_text_label=u'', exclude_banned_modqueue=False, comment_score_hide_mins=0, public_traffic=False, collapse_deleted_comments=False, spam_comments=u'low', spam_links=u'high', spam_selfposts=u'high', submit_text=u'', hide_ads=False, **kwargs)

Set the settings for the given subreddit.

Requires the modconfig oauth scope or user/password authentication as a mod of the subreddit.

Parameters:subreddit – Must be a subreddit object.
Returns:The json response from the server.
set_stylesheet(subreddit, stylesheet)

Set stylesheet for the given subreddit.

Requires the modconfig oauth scope or user/password authentication as a mod of the subreddit.

Returns:The json response from the server.
update_settings(subreddit, **kwargs)

Update only the given settings for the given subreddit.

The settings to update must be given by keyword and match one of the parameter names in set_settings.

Returns:The json response from the server.
upload_image(subreddit, image_path, name=None, header=False)

Upload an image to the subreddit.

Requires the modconfig oauth scope or user/password authentication as a mod of the subreddit.

Parameters:
  • image_path – A path to the jpg or png image you want to upload.
  • name – The name to provide the image. When None the name will be filename less any extension.
  • header – When True, upload the image as the subreddit header.
Returns:

True when the upload was successful. False otherwise. Note this is subject to change.

class praw.__init__.ModFlairMixin(*args, **kwargs)

Bases: praw.__init__.AuthenticatedReddit

Adds methods requiring the ‘modflair’ scope (or mod access).

You should not directly instantiate instances of this class. Use Reddit instead.

Initialize an AuthenticatedReddit instance.

add_flair_template(subreddit, text=u'', css_class=u'', text_editable=False, is_link=False)

Add a flair template to the given subreddit.

Requires the modflair oauth scope or user/password authentication as a mod of the subreddit.

Returns:The json response from the server.
clear_flair_templates(subreddit, is_link=False)

Clear flair templates for the given subreddit.

Requires the modflair oauth scope or user/password authentication as a mod of the subreddit.

Returns:The json response from the server.
configure_flair(subreddit, flair_enabled=False, flair_position=u'right', flair_self_assign=False, link_flair_enabled=False, link_flair_position=u'left', link_flair_self_assign=False)

Configure the flair setting for the given subreddit.

Requires the modflair oauth scope or user/password authentication as a mod of the subreddit.

Returns:The json response from the server.
delete_flair(subreddit, user)

Delete the flair for the given user on the given subreddit.

Requires the modflair oauth scope or user/password authentication as a mod of the subreddit.

Returns:The json response from the server.
get_flair_list(subreddit, *args, **kwargs)

Return a get_content generator of flair mappings.

Requires the modflair oauth scope or user/password authentication as a mod of the subreddit.

Parameters:subreddit – Either a Subreddit object or the name of the subreddit to return the flair list for.

The additional parameters are passed directly into get_content(). Note: the url, root_field, thing_field, and after_field parameters cannot be altered.

set_flair(subreddit, item, flair_text=u'', flair_css_class=u'')

Set flair for the user in the given subreddit.

Item can be a string, Redditor object, or Submission object. If item is a string it will be treated as the name of a Redditor.

This method can only be called by the subreddit moderator. To set flair on yourself or your own links use select_flair().

Requires the modflair oauth scope or user/password authentication as a mod of the subreddit.

Returns:The json response from the server.
set_flair_csv(subreddit, flair_mapping)

Set flair for a group of users in the given subreddit.

flair_mapping should be a list of dictionaries with the following keys:
user: the user name flair_text: the flair text for the user (optional) flair_css_class: the flair css class for the user (optional)

Requires the modflair oauth scope or user/password authentication as a mod of the subreddit.

Returns:The json response from the server.
class praw.__init__.ModLogMixin(*args, **kwargs)

Bases: praw.__init__.AuthenticatedReddit

Adds methods requiring the ‘modlog’ scope (or mod access).

You should not directly instantiate instances of this class. Use Reddit instead.

Initialize an AuthenticatedReddit instance.

get_mod_log(subreddit, mod=None, action=None, *args, **kwargs)

Return a get_content generator for moderation log items.

Requires the modlog oauth scope or user/password authentication as a mod of the subreddit.

Parameters:
  • subreddit – Either a Subreddit object or the name of the subreddit to return the flair list for.
  • mod – If given, only return the actions made by this moderator. Both a moderator name or Redditor object can be used here.
  • action – If given, only return entries for the specified action.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

class praw.__init__.ModOnlyMixin(*args, **kwargs)

Bases: praw.__init__.AuthenticatedReddit

Adds methods requiring the logged in moderator access.

You should not directly instantiate instances of this class. Use Reddit instead.

Initialize an AuthenticatedReddit instance.

get_banned(subreddit, user_only=True, *args, **kwargs)

Return a get_content generator of banned users for the subreddit.

Requires user/password authentication as a mod of the subreddit.

Parameters:
  • subreddit – The subreddit to get the banned user list for.
  • user_only – When False, the generator yields a dictionary of data associated with the server response for that user. In such cases, the Redditor will be in key ‘name’ (default: True).
get_contributors(subreddit, *args, **kwargs)

Return a get_content generator of contributors for the given subreddit.

If it’s a public subreddit, then user/pswd authentication as a moderator of the subreddit is required. For protected/private subreddits only access is required. See issue #246.

get_mod_mail(subreddit=u'mod', *args, **kwargs)

Return a get_content generator for moderator messages.

Requires the privatemessages oauth scope or user/password authentication as a mod of the subreddit.

Parameters:subreddit – Either a Subreddit object or the name of the subreddit to return the moderator mail from. Defaults to mod which includes items for all the subreddits you moderate.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

get_mod_queue(subreddit=u'mod', *args, **kwargs)

Return a get_content_generator for the moderator queue.

Requires user/password authentication as a mod of the subreddit.

Parameters:subreddit – Either a Subreddit object or the name of the subreddit to return the flair list for. Defaults to mod which includes items for all the subreddits you moderate.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

get_reports(subreddit=u'mod', *args, **kwargs)

Return a get_content generator of reported submissions.

Requires user/password authentication as a mod of the subreddit.

Parameters:subreddit – Either a Subreddit object or the name of the subreddit to return the flair list for. Defaults to mod which includes items for all the subreddits you moderate.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

get_spam(subreddit=u'mod', *args, **kwargs)

Return a get_content generator of spam-filtered items.

Requires user/password authentication as a mod of the subreddit.

Parameters:subreddit – Either a Subreddit object or the name of the subreddit to return the flair list for. Defaults to mod which includes items for all the subreddits you moderate.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

get_stylesheet(subreddit, **params)

Return the stylesheet and images for the given subreddit.

Requires the modconfig oauth scope.

get_unmoderated(subreddit=u'mod', *args, **kwargs)

Return a get_content generator of unmoderated items.

Requires user/password authentication as a mod of the subreddit.

Parameters:subreddit – Either a Subreddit object or the name of the subreddit to return the flair list for. Defaults to mod which includes items for all the subreddits you moderate.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

get_wiki_banned(subreddit, *args, **kwargs)

Return a get_content generator of users banned from the wiki.

Requires user/password authentication as a mod of the subreddit.

get_wiki_contributors(subreddit, *args, **kwargs)

Return a get_content generator of wiki contributors.

The returned users are those who have been approved as a wiki contributor by the moderators of the subreddit, Whether or not they’ve actually contributed to the wiki is irrellevant, their approval as wiki contributors is all that matters.

Requires user/password authentication as a mod of the subreddit.

class praw.__init__.MySubredditsMixin(*args, **kwargs)

Bases: praw.__init__.AuthenticatedReddit

Adds methods requiring the ‘mysubreddits’ scope (or login).

You should not directly instantiate instances of this class. Use Reddit instead.

Initialize an AuthenticatedReddit instance.

get_my_contributions(*args, **kwargs)

Return a get_content generator of subreddits.

The subreddits generated are those where the session’s user is a contributor.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

Requires the mysubreddits oauth scope or user/password authentication.

get_my_moderation(*args, **kwargs)

Return a get_content generator of subreddits.

The subreddits generated are those where the session’s user is a moderator.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

Requires the mysubreddits oauth scope or user/password authentication.

get_my_multireddits()

Return a list of the authenticated Redditor’s Multireddits.

Requires the mysubreddits oauth scope or user/password authentication.

get_my_subreddits(*args, **kwargs)

Return a get_content generator of subreddits.

The subreddits generated are those that the session’s user is subscribed to.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

Requires the mysubreddits oauth scope or user/password authentication.

class praw.__init__.OAuth2Reddit(*args, **kwargs)

Bases: praw.__init__.BaseReddit

Provides functionality for obtaining reddit OAuth2 access tokens.

You should not directly instantiate instances of this class. Use Reddit instead.

Initialize an OAuth2Reddit instance.

get_access_information(code)

Return the access information for an OAuth2 authorization grant.

Parameters:code – the code received in the request from the OAuth2 server
Returns:A dictionary with the key/value pairs for access_token, refresh_token and scope. The refresh_token value will be done when the OAuth2 grant is not refreshable. The scope value will be a set containing the scopes the tokens are valid for.
get_authorize_url(state, scope=u'identity', refreshable=False)

Return the URL to send the user to for OAuth2 authorization.

Parameters:
  • state – a unique key that represents this individual client
  • scope – the reddit scope to ask permissions for. Multiple scopes can be enabled by passing in a container of strings.
  • refreshable – when True, a permanent “refreshable” token is issued
has_oauth_app_info

Return True if all the necessary OAuth settings are set.

refresh_access_information(refresh_token)

Return updated access information for an OAuth2 authorization grant.

Parameters:refresh_token – the refresh token used to obtain the updated information
Returns:A dictionary with the key/value pairs for access_token, refresh_token and scope. The refresh_token value will be done when the OAuth2 grant is not refreshable. The scope value will be a set containing the scopes the tokens are valid for.
set_oauth_app_info(client_id, client_secret, redirect_uri)

Set the App information to use with OAuth2.

This function need only be called if your praw.ini site configuration does not already contain the necessary information.

Go to https://www.reddit.com/prefs/apps/ to discover the appropriate values for your application.

Parameters:
  • client_id – the client_id of your application
  • client_secret – the client_secret of your application
  • redirect_uri – the redirect_uri of your application
class praw.__init__.PrivateMessagesMixin(*args, **kwargs)

Bases: praw.__init__.AuthenticatedReddit

Adds methods requiring the ‘privatemessages’ scope (or login).

You should not directly instantiate instances of this class. Use Reddit instead.

Initialize an AuthenticatedReddit instance.

get_inbox(*args, **kwargs)

Return a get_content generator for inbox (messages and comments).

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

Requires the privatemessages oauth scope or user/password authentication.

get_mentions(*args, **kwargs)

Return a get_content generator for username mentions.

This will only work for users with reddit gold.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

Requires the privatemessages oauth scope or user/password authentication.

get_message(message_id, *args, **kwargs)

Return a Message object corresponding to the given ID.

Requires the privatemessages oauth scope or user/password authentication.

Parameters:message_id – The ID or Fullname for a Message

The additional parameters are passed into from_id() of Message, and subsequently into request_json().

get_messages(*args, **kwargs)

Return a get_content generator for inbox (messages only).

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

Requires the privatemessages oauth scope or user/password authentication.

get_sent(*args, **kwargs)

Return a get_content generator for sent messages.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

Requires the privatemessages oauth scope or user/password authentication.

get_unread(unset_has_mail=False, update_user=False, *args, **kwargs)

Return a get_content generator for unread messages.

Requires the privatemessages oauth scope or user/password authentication.

Parameters:
  • unset_has_mail – When True, clear the has_mail flag (orangered) for the user.
  • update_user – If both unset_has_mail and update user is True, set the has_mail attribute of the logged-in user to False.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

send_message(recipient, subject, message, from_sr=None, captcha=None)

Send a message to a redditor or a subreddit’s moderators (mod mail).

This function may result in a captcha challenge. PRAW will automatically prompt you for a response. See How can I handle captchas myself? if you want to manually handle captchas.

Requires the privatemessages oauth scope or user/password authentication.

Parameters:
  • recipient – A Redditor or Subreddit instance to send a message to. A string can also be used in which case the string is treated as a redditor unless it is prefixed with either ‘/r/’ or ‘#’, in which case it will be treated as a subreddit.
  • subject – The subject of the message to send.
  • message – The actual message content.
  • from_sr – A Subreddit instance or string to send the message from. When provided, messages are sent from the subreddit rather than from the authenticated user. Note that the authenticated user must be a moderator of the subreddit.
Returns:

The json response from the server.

class praw.__init__.Reddit(*args, **kwargs)

Bases: praw.__init__.ModConfigMixin, praw.__init__.ModFlairMixin, praw.__init__.ModLogMixin, praw.__init__.ModOnlyMixin, praw.__init__.MySubredditsMixin, praw.__init__.PrivateMessagesMixin, praw.__init__.SubmitMixin, praw.__init__.SubscribeMixin

Provides access to reddit’s API.

See BaseReddit‘s documentation for descriptions of the initialization parameters.

Initialize an AuthenticatedReddit instance.

class praw.__init__.SubmitMixin(*args, **kwargs)

Bases: praw.__init__.AuthenticatedReddit

Adds methods requiring the ‘submit’ scope (or login).

You should not directly instantiate instances of this class. Use Reddit instead.

Initialize an AuthenticatedReddit instance.

submit(subreddit, title, text=None, url=None, captcha=None, save=None, send_replies=None, resubmit=None)

Submit a new link to the given subreddit.

Accepts either a Subreddit object or a str containing the subreddit’s display name.

This function may result in a captcha challenge. PRAW will automatically prompt you for a response. See How can I handle captchas myself? if you want to manually handle captchas.

Requires the submit oauth scope or user/password authentication.

Parameters:
  • resubmit – If True, submit the link even if it has already been submitted.
  • save – If True the new Submission will be saved after creation.
  • send_replies – Gold Only Feature. If True, inbox replies will be received when people comment on the Submission. If set to None or the currently authenticated user doesn’t have gold, then the default of True for text posts and False for link posts will be used.
Returns:

The newly created Submission object if the reddit instance can access it. Otherwise, return the url to the submission.

class praw.__init__.SubscribeMixin(*args, **kwargs)

Bases: praw.__init__.AuthenticatedReddit

Adds methods requiring the ‘subscribe’ scope (or login).

You should not directly instantiate instances of this class. Use Reddit instead.

Initialize an AuthenticatedReddit instance.

subscribe(subreddit, unsubscribe=False)

Subscribe to the given subreddit.

Requires the subscribe oauth scope or user/password authentication.

Parameters:
  • subreddit – Either the subreddit name or a subreddit object.
  • unsubscribe – When True, unsubscribe.
Returns:

The json response from the server.

unsubscribe(subreddit)

Unsubscribe from the given subreddit.

Parameters:subreddit – Either the subreddit name or a subreddit object.
Returns:The json response from the server.
class praw.__init__.UnauthenticatedReddit(*args, **kwargs)

Bases: praw.__init__.BaseReddit

This mixin provides bindings for basic functions of reddit’s API.

None of these functions require authenticated access to reddit’s API.

You should not directly instantiate instances of this class. Use Reddit instead.

Initialze an UnauthenticatedReddit instance.

create_redditor(user_name, password, email=u'')

Register a new user.

Returns:The json response from the server.
get_comments(subreddit, gilded_only=False, *args, **kwargs)

Return a get_content generator for comments in the given subreddit.

May use the read oauth scope to seecontent only visible to the authenticated user.

Parameters:gilded_only – If True only return gilded comments.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

get_controversial(*args, **kwargs)

Return a get_content generator for controversial submissions.

Corresponds to submissions provided by http://www.reddit.com/controversial/ for the session.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_domain_listing(domain, sort=u'hot', period=None, *args, **kwargs)

Return a get_content generator for submissions by domain.

Corresponds to the submissions provided by http://www.reddit.com/domain/{domain}.

May use the read oauth scope to seecontent only visible to the authenticated user.

Parameters:
  • domain – The domain to generate a submission listing for.
  • sort – When provided must be one of ‘hot’, ‘new’, ‘rising’, ‘controversial, or ‘top’. Defaults to ‘hot’.
  • period – When sort is either ‘controversial’, or ‘top’ the period can be either None (for account default), ‘all’, ‘year’, ‘month’, ‘week’, ‘day’, or ‘hour’.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

get_flair(subreddit, redditor)

Return the flair for a user on the given subreddit.

Requires the modflair oauth scope or user/password authentication as a mod of the subreddit.

Parameters:
  • subreddit – Can be either a Subreddit object or the name of a subreddit.
  • redditor – Can be either a Redditor object or the name of a redditor.
Returns:

None if the user doesn’t exist, otherwise a dictionary containing the keys flair_css_class, flair_text, and user.

get_front_page(*args, **kwargs)

Return a get_content generator for the front page submissions.

Corresponds to the submissions provided by http://www.reddit.com/ for the session.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_info(url=None, thing_id=None, limit=None)

Look up existing items by thing_id (fullname) or url.

May use the read oauth scope to seecontent only visible to the authenticated user.

Parameters:
  • url – The url to lookup.
  • thing_id – A single thing_id, or a list of thing_ids. A thing_id can be any one of Comment (t1_), Link (t3_), or Subreddit (t5_) to lookup by fullname.
  • limit – The maximum number of Submissions to return when looking up by url. When None, uses account default settings.
Returns:

When a single thing_id is provided, return the corresponding thing object, or None if not found. When a list of thing_ids or a url is provided return a list of thing objects (up to limit). None is returned if any one of the thing_ids or the URL is invalid.

get_moderators(subreddit, **kwargs)

Return the list of moderators for the given subreddit.

get_multireddit(redditor, multi, *args, **kwargs)

Return a Multireddit object for the author and name specified.

Parameters:
  • redditor – The username or Redditor object of the user who owns the multireddit.
  • multi – The name of the multireddit to fetch.

The additional parameters are passed directly into the Multireddit constructor.

get_new(*args, **kwargs)

Return a get_content generator for new submissions.

Corresponds to the submissions provided by http://www.reddit.com/new/ for the session.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_new_subreddits(*args, **kwargs)

Return a get_content generator for the newest subreddits.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

Return a get_content generator for the most active subreddits.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

get_random_submission(subreddit=u'all')

Return a random Submission object.

Parameters:subreddit – Limit the submission to the specified subreddit(s). Default: all
get_random_subreddit(nsfw=False)

Return a random Subreddit object.

Parameters:nsfw – When true, return a random NSFW Subreddit object. Calling in this manner will set the ‘over18’ cookie for the duration of the PRAW session.
get_redditor(user_name, *args, **kwargs)

Return a Redditor instance for the user_name specified.

The additional parameters are passed directly into the Redditor constructor.

get_rising(*args, **kwargs)

Return a get_content generator for rising submissions.

Corresponds to the submissions provided by http://www.reddit.com/rising/ for the session.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_sticky(subreddit=None)

Return a Submission object for the sticky of the subreddit.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_submission(url=None, submission_id=None, comment_limit=0, comment_sort=None, params=None)

Return a Submission object for the given url or submission_id.

Parameters:
  • comment_limit – The desired number of comments to fetch. If <= 0 fetch the default number for the session’s user. If None, fetch the maximum possible.
  • comment_sort – The sort order for retrieved comments. When None use the default for the session’s user.
  • params – Dictionary containing extra GET data to put in the url.
get_submissions(fullnames, *args, **kwargs)

Generate Submission objects for each item provided in fullnames.

A submission fullname looks like t3_<base36_id>. Submissions are yielded in the same order they appear in fullnames.

Up to 100 items are batched at a time – this happens transparently.

The additional parameters are passed directly into get_content(). Note: the url and limit parameters cannot be altered.

get_subreddit(subreddit_name, *args, **kwargs)

Return a Subreddit object for the subreddit_name specified.

The additional parameters are passed directly into the Subreddit constructor.

get_subreddit_recommendations(subreddits, omit=None)

Return a list of recommended subreddits as Subreddit objects.

Subreddits with activity less than a certain threshold, will not have any recommendations due to lack of data.

Parameters:
  • subreddits – A list of subreddits (either names or Subreddit objects) to base the recommendations on.
  • omit – A list of subreddits (either names or Subreddit objects) that will be filtered out of the result.
get_top(*args, **kwargs)

Return a get_content generator for top submissions.

Corresponds to the submissions provided by http://www.reddit.com/top/ for the session.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_wiki_page(subreddit, page, **params)

Return a WikiPage object for the subreddit and page provided.

get_wiki_pages(subreddit)

Return a list of WikiPage objects for the subreddit.

is_username_available(username)

Return True if username is valid and available, otherwise False.

search(query, subreddit=None, sort=None, syntax=None, period=None, *args, **kwargs)

Return a generator for submissions that match the search query.

Parameters:
  • query – The query string to search for. If query is a URL only submissions which link to that URL will be returned.
  • subreddit – Limit search results to the subreddit if provided.
  • sort – The sort order of the results.
  • syntax – The syntax of the search query.
  • period – The time period of the results.

The additional parameters are passed directly into get_content(). Note: the url and param parameters cannot be altered.

See http://www.reddit.com/help/search for more information on how to build a search query.

search_reddit_names(query)

Return subreddits whose display name contains the query.

objects Module

Contains code about objects such as Submissions, Redditors or Commments.

There are two main groups of objects in this file. The first are objects that correspond to a Thing or part of a Thing as specified in reddit’s API overview, https://github.com/reddit/reddit/wiki/API. The second gives functionality that extends over multiple Things. An object that extends from Saveable indicates that it can be saved and unsaved in the context of a logged in user.

class praw.objects.Comment(reddit_session, json_dict)

Bases: praw.objects.Editable, praw.objects.Gildable, praw.objects.Inboxable, praw.objects.Moderatable, praw.objects.Refreshable, praw.objects.Reportable, praw.objects.Saveable, praw.objects.Voteable

A class that represents a reddit comments.

Construct an instance of the Comment object.

is_root

Return True when the comment is a top level comment.

Return a permalink to the comment.

replies

Return a list of the comment replies to this comment.

submission

Return the submission object this comment belongs to.

class praw.objects.Editable(reddit_session, json_dict=None, fetch=True, info_url=None, underscore_names=None)

Bases: praw.objects.RedditContentObject

Interface for Reddit content objects that can be edited and deleted.

Create a new object from the dict of attributes returned by the API.

The fetch parameter specifies whether to retrieve the object’s information from the API (only matters when it isn’t provided using json_dict).

delete()

Delete this object.

Requires the edit oauth scope or user/password authentication.

Returns:The json response from the server.
edit(text)

Replace the body of the object with text.

Requires the edit oauth scope or user/password authentication.

Returns:The updated object.
class praw.objects.Gildable(reddit_session, json_dict=None, fetch=True, info_url=None, underscore_names=None)

Bases: praw.objects.RedditContentObject

Interface for RedditContentObjects that can be gilded.

Create a new object from the dict of attributes returned by the API.

The fetch parameter specifies whether to retrieve the object’s information from the API (only matters when it isn’t provided using json_dict).

gild(months=None)

Gild the Redditor or author of the content.

Requires the creddits oauth scope or user/password authentication.

Parameters:months – Specifies the number of months to gild. This parameter is Only valid when the instance called upon is of type Redditor. When not provided, the value defaults to 1.
Returns:True on success, otherwise raises an exception.
class praw.objects.Hideable(reddit_session, json_dict=None, fetch=True, info_url=None, underscore_names=None)

Bases: praw.objects.RedditContentObject

Interface for objects that can be hidden.

Create a new object from the dict of attributes returned by the API.

The fetch parameter specifies whether to retrieve the object’s information from the API (only matters when it isn’t provided using json_dict).

hide(unhide=False)

Hide object in the context of the logged in user.

Requires user/password authentication.

Returns:The json response from the server.
unhide()

Unhide object in the context of the logged in user.

Returns:The json response from the server.
class praw.objects.Inboxable(reddit_session, json_dict=None, fetch=True, info_url=None, underscore_names=None)

Bases: praw.objects.RedditContentObject

Interface for objects that appear in the inbox (orangereds).

Create a new object from the dict of attributes returned by the API.

The fetch parameter specifies whether to retrieve the object’s information from the API (only matters when it isn’t provided using json_dict).

mark_as_read()

Mark object as read.

Returns:The json response from the server.
mark_as_unread()

Mark object as unread.

Returns:The json response from the server.
reply(text)

Reply to object with the specified text.

Returns:A Comment object for the newly created comment (reply).
class praw.objects.LoggedInRedditor(reddit_session, user_name=None, json_dict=None, fetch=False)

Bases: praw.objects.Redditor

A class representing a currently logged in Redditor.

Construct an instance of the Redditor object.

get_blocked()

Return a UserList of Redditors with whom the user has blocked.

get_cached_moderated_reddits()

Return a cached dictionary of the user’s moderated reddits.

This list is used internally. Consider using the get_my_moderation function instead.

get_friends(**params)

Return a UserList of Redditors with whom the user has friended.

get_hidden(sort=u'new', time=u'all', *args, **kwargs)

Return a get_content generator for some RedditContentObject type.

Requires the history oauth scope or user/password authentication.

Parameters:
  • sort – Specify the sort order of the results if applicable (one of 'hot', 'new', 'top', 'controversial').
  • time – Specify the time-period to return submissions if applicable (one of 'hour', 'day', 'week', 'month', 'year', 'all').

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

get_saved(sort=u'new', time=u'all', *args, **kwargs)

Return a get_content generator for some RedditContentObject type.

Requires the history oauth scope or user/password authentication.

Parameters:
  • sort – Specify the sort order of the results if applicable (one of 'hot', 'new', 'top', 'controversial').
  • time – Specify the time-period to return submissions if applicable (one of 'hour', 'day', 'week', 'month', 'year', 'all').

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

send_message(*args, **kwargs)

Send a message to a redditor or a subreddit’s moderators (mod mail).

See PrivateMessagesMixin.send_message() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

class praw.objects.Message(reddit_session, json_dict)

Bases: praw.objects.Inboxable

A class for private messages.

Construct an instnace of the Message object.

static from_id(reddit_session, message_id, *args, **kwargs)

Request the url for a Message and return a Message object.

Requires the privatemessages oauth scope or user/password authentication.

Parameters:
  • reddit_session – The session to make the request with.
  • message_id – The ID of the message to request.

The additional parameters are passed directly into request_json().

class praw.objects.Messageable(reddit_session, json_dict=None, fetch=True, info_url=None, underscore_names=None)

Bases: praw.objects.RedditContentObject

Interface for RedditContentObjects that can be messaged.

Create a new object from the dict of attributes returned by the API.

The fetch parameter specifies whether to retrieve the object’s information from the API (only matters when it isn’t provided using json_dict).

send_message(*args, **kwargs)

Send a message to a redditor or a subreddit’s moderators (mod mail).

See PrivateMessagesMixin.send_message() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

class praw.objects.ModAction(reddit_session, json_dict=None, fetch=False)

Bases: praw.objects.RedditContentObject

A moderator action.

Construct an instance of the ModAction object.

class praw.objects.Moderatable(reddit_session, json_dict=None, fetch=True, info_url=None, underscore_names=None)

Bases: praw.objects.RedditContentObject

Interface for Reddit content objects that have can be moderated.

Create a new object from the dict of attributes returned by the API.

The fetch parameter specifies whether to retrieve the object’s information from the API (only matters when it isn’t provided using json_dict).

approve()

Approve object.

This reverts a removal, resets the report counter, marks it with a green check mark (only visible to other moderators) on the website view and sets the approved_by attribute to the logged in user.

Requires the modposts oauth scope or user/password authentication as a mod of the subreddit.

Returns:The json response from the server.
distinguish(as_made_by=u'mod')

Distinguish object as made by mod, admin or special.

Distinguished objects have a different author color. With Reddit enhancement suite it is the background color that changes.

Requires the modposts oauth scope or user/password authentication as a mod of the subreddit.

Returns:The json response from the server.
ignore_reports()

Ignore future reports on this object.

This prevents future reports from causing notifications or appearing in the various moderation listing. The report count will still increment.

Requires the modposts oauth scope or user/password authentication as a mod of the subreddit.

remove(spam=False)

Remove object. This is the moderator version of delete.

The object is removed from the subreddit listings and placed into the spam listing. If spam is set to True, then the automatic spam filter will try to remove objects with similar attributes in the future.

Requires the modposts oauth scope or user/password authentication as a mod of the subreddit.

Returns:The json response from the server.
undistinguish()

Remove mod, admin or special distinguishing on object.

Returns:The json response from the server.
unignore_reports()

Remove ignoring of future reports on this object.

Undoes ‘ignore_reports’. Future reports will now cause notifications and appear in the various moderation listings.

Requires the modposts oauth scope or user/password authentication as a mod of the subreddit.

class praw.objects.MoreComments(reddit_session, json_dict)

Bases: praw.objects.RedditContentObject

A class indicating there are more comments.

Construct an instance of the MoreComment object.

comments(update=True)

Fetch and return the comments for a single MoreComments object.

class praw.objects.Multireddit(reddit_session, redditor=None, multi=None, json_dict=None, fetch=False)

Bases: praw.objects.Refreshable

A class for users’ Multireddits.

Construct an instance of the Multireddit object.

get_controversial(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_controversial_from_all(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_controversial_from_day(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_controversial_from_hour(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_controversial_from_month(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_controversial_from_week(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_controversial_from_year(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_hot(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_new(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_rising(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_top(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_top_from_all(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_top_from_day(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_top_from_hour(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_top_from_month(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_top_from_week(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_top_from_year(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

class praw.objects.PRAWListing(reddit_session, json_dict=None, fetch=False)

Bases: praw.objects.RedditContentObject

An abstract class to coerce a listing into RedditContentObjects.

Construct an instance of the PRAWListing object.

CHILD_ATTRIBUTE = None
class praw.objects.RedditContentObject(reddit_session, json_dict=None, fetch=True, info_url=None, underscore_names=None)

Bases: object

Base class that represents actual reddit objects.

Create a new object from the dict of attributes returned by the API.

The fetch parameter specifies whether to retrieve the object’s information from the API (only matters when it isn’t provided using json_dict).

classmethod from_api_response(reddit_session, json_dict)

Return an instance of the appropriate class from the json_dict.

fullname

Return the object’s fullname.

A fullname is an object’s kind mapping like t3 followed by an underscore and the object’s base36 id, e.g., t1_c5s96e0.

class praw.objects.Redditor(reddit_session, user_name=None, json_dict=None, fetch=False)

Bases: praw.objects.Gildable, praw.objects.Messageable, praw.objects.Refreshable

A class representing the users of reddit.

Construct an instance of the Redditor object.

friend()

Friend the user.

Returns:The json response from the server.
get_comments(sort=u'new', time=u'all', *args, **kwargs)

Return a get_content generator for some RedditContentObject type.

Parameters:
  • sort – Specify the sort order of the results if applicable (one of 'hot', 'new', 'top', 'controversial').
  • time – Specify the time-period to return submissions if applicable (one of 'hour', 'day', 'week', 'month', 'year', 'all').

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

get_disliked(*args, **kwargs)

Return a listing of the Submissions the user has downvoted.

Returns:get_content generator of Submission items.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

As a default, this listing is only accessible by the user. Thereby requiring either user/pswd authentication or OAuth authentication with the ‘history’ scope. Users may choose to make their voting record public by changing a user preference. In this case, no authentication will be needed to access this listing.

get_liked(*args, **kwargs)

Return a listing of the Submissions the user has upvoted.

Returns:get_content generator of Submission items.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

As a default, this listing is only accessible by the user. Thereby requirering either user/pswd authentication or OAuth authentication with the ‘history’ scope. Users may choose to make their voting record public by changing a user preference. In this case, no authentication will be needed to access this listing.

get_multireddit(multi)

Return a multireddit that belongs to this user.

Parameters:multi – The name of the multireddit
Returns:Multireddit object with author=Redditor and name=multi
get_overview(sort=u'new', time=u'all', *args, **kwargs)

Return a get_content generator for some RedditContentObject type.

Parameters:
  • sort – Specify the sort order of the results if applicable (one of 'hot', 'new', 'top', 'controversial').
  • time – Specify the time-period to return submissions if applicable (one of 'hour', 'day', 'week', 'month', 'year', 'all').

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

get_submitted(sort=u'new', time=u'all', *args, **kwargs)

Return a get_content generator for some RedditContentObject type.

Parameters:
  • sort – Specify the sort order of the results if applicable (one of 'hot', 'new', 'top', 'controversial').
  • time – Specify the time-period to return submissions if applicable (one of 'hour', 'day', 'week', 'month', 'year', 'all').

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

mark_as_read(messages, unread=False)

Mark message(s) as read or unread.

Returns:The json response from the server.
send_message(*args, **kwargs)

Send a message to a redditor or a subreddit’s moderators (mod mail).

See PrivateMessagesMixin.send_message() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

unfriend()

Unfriend the user.

Returns:The json response from the server.
class praw.objects.Refreshable(reddit_session, json_dict=None, fetch=True, info_url=None, underscore_names=None)

Bases: praw.objects.RedditContentObject

Interface for objects that can be refreshed.

Create a new object from the dict of attributes returned by the API.

The fetch parameter specifies whether to retrieve the object’s information from the API (only matters when it isn’t provided using json_dict).

refresh()

Re-query to update object with latest values. Return the object.

Note that if this call is made within cache_timeout as specified in praw.ini then this will return the cached content. Any listing, such as the submissions on a subreddits top page, will automatically be refreshed serverside. Refreshing a submission will also refresh all its comments.

class praw.objects.Reportable(reddit_session, json_dict=None, fetch=True, info_url=None, underscore_names=None)

Bases: praw.objects.RedditContentObject

Interface for RedditContentObjects that can be reported.

Create a new object from the dict of attributes returned by the API.

The fetch parameter specifies whether to retrieve the object’s information from the API (only matters when it isn’t provided using json_dict).

report(reason=None)

Report this object to the moderators.

Requires user/password authentication.

Parameters:reason – The user-supplied reason for reporting a comment or submission. Default: None (blank reason)
Returns:The json response from the server.
class praw.objects.Saveable(reddit_session, json_dict=None, fetch=True, info_url=None, underscore_names=None)

Bases: praw.objects.RedditContentObject

Interface for RedditContentObjects that can be saved.

Create a new object from the dict of attributes returned by the API.

The fetch parameter specifies whether to retrieve the object’s information from the API (only matters when it isn’t provided using json_dict).

save(unsave=False)

Save the object.

Requires the save oauth scope or user/password authentication.

Returns:The json response from the server.
unsave()

Unsave the object.

Returns:The json response from the server.
class praw.objects.Submission(reddit_session, json_dict)

Bases: praw.objects.Editable, praw.objects.Gildable, praw.objects.Hideable, praw.objects.Moderatable, praw.objects.Refreshable, praw.objects.Reportable, praw.objects.Saveable, praw.objects.Voteable

A class for submissions to reddit.

Construct an instance of the Subreddit object.

add_comment(text)

Comment on the submission using the specified text.

Returns:A Comment object for the newly created comment.
comments

Return forest of comments, with top-level comments as tree roots.

May contain instances of MoreComment objects. To easily replace these objects with Comment objects, use the replace_more_comments method then fetch this attribute. Use comment replies to walk down the tree. To get an unnested, flat list of comments from this attribute use helpers.flatten_tree.

static from_id(reddit_session, subreddit_id)

Return an edit-only submission object based on the id.

static from_json(json_response)

Return a submission object from the json response.

static from_url(reddit_session, url, comment_limit=0, comment_sort=None, comments_only=False, params=None)

Request the url and return a Submission object.

May use the read oauth scope to seecontent only visible to the authenticated user.

Parameters:
  • reddit_session – The session to make the request with.
  • url – The url to build the Submission object from.
  • comment_limit – The desired number of comments to fetch. If <= 0 fetch the default number for the session’s user. If None, fetch the maximum possible.
  • comment_sort – The sort order for retrieved comments. When None use the default for the session’s user.
  • comments_only – Return only the list of comments.
  • params – dictionary containing extra GET data to put in the url.
get_duplicates(*args, **kwargs)

Return a get_content generator for the submission’s duplicates.

Returns:get_content generator iterating over Submission objects.

The additional parameters are passed directly into get_content(). Note: the url and object_filter parameters cannot be altered.

get_flair_choices(*args, **kwargs)

Return available link flair choices and current flair.

Convenience function for get_flair_choices() populating both the subreddit and link parameters.

Returns:The json response from the server.
mark_as_nsfw(unmark_nsfw=False)

Mark as Not Safe For Work.

Requires that the currently authenticated user is the author of the submission, has the modposts oauth scope or has user/password authentication as a mod of the subreddit.

Returns:The json response from the server.
replace_more_comments(limit=32, threshold=1)

Update the comment tree by replacing instances of MoreComments.

Parameters:
  • limit – The maximum number of MoreComments objects to replace. Each replacement requires 1 API request. Set to None to have no limit, or to 0 to make no extra requests. Default: 32
  • threshold – The minimum number of children comments a MoreComments object must have in order to be replaced. Default: 1
Returns:

A list of MoreComments objects that were not replaced.

Note that after making this call, the comments attribute of the submission will no longer contain any MoreComments objects. Items that weren’t replaced are still removed from the tree, and will be included in the returned list.

set_contest_mode(state=True)

Set ‘Contest Mode’ for the comments of this submission.

Contest mode have the following effects.
  • The comment thread will default to being sorted randomly.

  • Replies to top-level comments will be hidden behind

    “[show replies]” buttons.

  • Scores will be hidden from non-moderators.

  • Scores accessed through the API (mobile apps, bots) will be

    obscured to “1” for non-moderators.

Source for effects: http://www.reddit.com/r/bestof2012/comments/159bww/
introducing_contest_mode_a_tool_for_your_voting

Requires the modposts oauth scope or user/password authentication as a mod of the subreddit.

Returns:The json response from the server.
set_flair(*args, **kwargs)

Set flair for this submission.

Convenience function that utilizes ModFlairMixin.set_flair() populating both the subreddit and item parameters.

Returns:The json response from the server.

Return a short link to the submission.

The short link points to a page on the short_domain that redirects to the main. http://redd.it/y3r8u is a short link for reddit.com.

sticky()

Sticky a post in its subreddit.

If there is already a stickied post in the concerned subreddit then it will be unstickied. Only self submissions can be stickied.

Requires the modposts oauth scope or user/password authentication as a mod of the subreddit.

Returns:The json response from the server
unmark_as_nsfw()

Mark as Safe For Work.

Returns:The json response from the server.
unset_contest_mode()

Unset ‘Contest Mode’ for the comments of this submission.

Contest mode have the following effects.
  • The comment thread will default to being sorted randomly.

  • Replies to top-level comments will be hidden behind

    “[show replies]” buttons.

  • Scores will be hidden from non-moderators.

  • Scores accessed through the API (mobile apps, bots) will be

    obscured to “1” for non-moderators.

Source for effects: http://www.reddit.com/r/bestof2012/comments/159bww/
introducing_contest_mode_a_tool_for_your_voting

Requires the modposts oauth scope or user/password authentication as a mod of the subreddit.

Returns:The json response from the server.
unsticky()

Unsticky this post.

Requires the modposts oauth scope or user/password authentication as a mod of the subreddit.

Returns:The json response from the server
class praw.objects.Subreddit(reddit_session, subreddit_name=None, json_dict=None, fetch=False)

Bases: praw.objects.Messageable, praw.objects.Refreshable

A class for Subreddits.

Construct an instance of the Subreddit object.

accept_moderator_invite(*args, **kwargs)

Accept a moderator invite to the given subreddit.

See AuthenticatedReddit.accept_moderator_invite() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

add_ban(thing, user, **kwargs)

Requires user/password authentication as a mod of the subreddit.

add_contributor(thing, user, **kwargs)

Requires user/password authentication as a mod of the subreddit.

add_flair_template(*args, **kwargs)

Add a flair template to the given subreddit.

See ModFlairMixin.add_flair_template() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

add_moderator(thing, user, **kwargs)

Requires user/password authentication as a mod of the subreddit.

add_wiki_ban(thing, user, **kwargs)

Requires user/password authentication as a mod of the subreddit.

add_wiki_contributor(thing, user, **kwargs)

Requires user/password authentication as a mod of the subreddit.

clear_all_flair()

Remove all user flair on this subreddit.

Returns:The json response from the server when there is flair to clear, otherwise returns None.
clear_flair_templates(*args, **kwargs)

Clear flair templates for the given subreddit.

See ModFlairMixin.clear_flair_templates() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

configure_flair(*args, **kwargs)

Configure the flair setting for the given subreddit.

See ModFlairMixin.configure_flair() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

delete_flair(*args, **kwargs)

Delete the flair for the given user on the given subreddit.

See ModFlairMixin.delete_flair() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

delete_image(*args, **kwargs)

Delete an image from the subreddit.

See ModConfigMixin.delete_image() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

edit_wiki_page(*args, **kwargs)

Create or edit a wiki page with title page for subreddit.

See AuthenticatedReddit.edit_wiki_page() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

get_banned(*args, **kwargs)

Return a get_content generator of banned users for the subreddit.

See ModOnlyMixin.get_banned() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

get_comments(*args, **kwargs)

Return a get_content generator for comments in the given subreddit.

See UnauthenticatedReddit.get_comments() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

get_contributors(*args, **kwargs)

See ModOnlyMixin.get_contributors() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

get_controversial(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_controversial_from_all(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_controversial_from_day(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_controversial_from_hour(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_controversial_from_month(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_controversial_from_week(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_controversial_from_year(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_flair(*args, **kwargs)

Return the flair for a user on the given subreddit.

See UnauthenticatedReddit.get_flair() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

get_flair_choices(*args, **kwargs)

Return available flair choices and current flair.

See AuthenticatedReddit.get_flair_choices() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

get_flair_list(*args, **kwargs)

Return a get_content generator of flair mappings.

See ModFlairMixin.get_flair_list() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

get_hot(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_mod_log(*args, **kwargs)

Return a get_content generator for moderation log items.

See ModLogMixin.get_mod_log() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

get_mod_mail(*args, **kwargs)

Return a get_content generator for moderator messages.

See ModOnlyMixin.get_mod_mail() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

get_mod_queue(*args, **kwargs)

Return a get_content_generator for the moderator queue.

See ModOnlyMixin.get_mod_queue() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

get_moderators(*args, **kwargs)

Return the list of moderators for the given subreddit.

See UnauthenticatedReddit.get_moderators() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

get_new(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_random_submission(*args, **kwargs)

Return a random Submission object.

See UnauthenticatedReddit.get_random_submission() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

get_reports(*args, **kwargs)

Return a get_content generator of reported submissions.

See ModOnlyMixin.get_reports() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

get_rising(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_settings(*args, **kwargs)

Return the settings for the given subreddit.

See ModConfigMixin.get_settings() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

get_spam(*args, **kwargs)

Return a get_content generator of spam-filtered items.

See ModOnlyMixin.get_spam() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

get_sticky(*args, **kwargs)

Return a Submission object for the sticky of the subreddit.

See UnauthenticatedReddit.get_sticky() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

get_stylesheet(*args, **kwargs)

Return the stylesheet and images for the given subreddit.

See ModOnlyMixin.get_stylesheet() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

get_top(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_top_from_all(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_top_from_day(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_top_from_hour(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_top_from_month(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_top_from_week(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_top_from_year(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

The additional parameters are passed directly into get_content(). Note: the url parameter cannot be altered.

May use the read oauth scope to seecontent only visible to the authenticated user.

get_unmoderated(*args, **kwargs)

Return a get_content generator of unmoderated items.

See ModOnlyMixin.get_unmoderated() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

get_wiki_banned(*args, **kwargs)

Return a get_content generator of users banned from the wiki.

See ModOnlyMixin.get_wiki_banned() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

get_wiki_contributors(*args, **kwargs)

Return a get_content generator of wiki contributors.

See ModOnlyMixin.get_wiki_contributors() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

get_wiki_page(*args, **kwargs)

Return a WikiPage object for the subreddit and page provided.

See UnauthenticatedReddit.get_wiki_page() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

get_wiki_pages(*args, **kwargs)

Return a list of WikiPage objects for the subreddit.

See UnauthenticatedReddit.get_wiki_pages() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

remove_ban(thing, user, **kwargs)

Requires user/password authentication as a mod of the subreddit.

remove_contributor(thing, user, **kwargs)

Requires user/password authentication as a mod of the subreddit.

remove_moderator(thing, user, **kwargs)

Requires user/password authentication as a mod of the subreddit.

remove_wiki_ban(thing, user, **kwargs)

Requires user/password authentication as a mod of the subreddit.

remove_wiki_contributor(thing, user, **kwargs)

Requires user/password authentication as a mod of the subreddit.

search(*args, **kwargs)

Return a generator for submissions that match the search query.

See UnauthenticatedReddit.search() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

select_flair(*args, **kwargs)

Select user flair or link flair on subreddits.

See AuthenticatedReddit.select_flair() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

set_flair(*args, **kwargs)

Set flair for the user in the given subreddit.

See ModFlairMixin.set_flair() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

set_flair_csv(*args, **kwargs)

Set flair for a group of users in the given subreddit.

See ModFlairMixin.set_flair_csv() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

set_settings(*args, **kwargs)

Set the settings for the given subreddit.

See ModConfigMixin.set_settings() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

set_stylesheet(*args, **kwargs)

Set stylesheet for the given subreddit.

See ModConfigMixin.set_stylesheet() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

submit(*args, **kwargs)

Submit a new link to the given subreddit.

See SubmitMixin.submit() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

subscribe(*args, **kwargs)

Subscribe to the given subreddit.

See SubscribeMixin.subscribe() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

unsubscribe(*args, **kwargs)

Unsubscribe from the given subreddit.

See SubscribeMixin.unsubscribe() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

update_settings(*args, **kwargs)

Update only the given settings for the given subreddit.

See ModConfigMixin.update_settings() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

upload_image(*args, **kwargs)

Upload an image to the subreddit.

See ModConfigMixin.upload_image() for complete usage. Note that you should exclude the subreddit parameter when calling this convenience method.

class praw.objects.UserList(reddit_session, json_dict=None, fetch=False)

Bases: praw.objects.PRAWListing

A list of Redditors. Works just like a regular list.

Construct an instance of the PRAWListing object.

CHILD_ATTRIBUTE = u'children'
class praw.objects.Voteable(reddit_session, json_dict=None, fetch=True, info_url=None, underscore_names=None)

Bases: praw.objects.RedditContentObject

Interface for RedditContentObjects that can be voted on.

Create a new object from the dict of attributes returned by the API.

The fetch parameter specifies whether to retrieve the object’s information from the API (only matters when it isn’t provided using json_dict).

clear_vote()

Remove the logged in user’s vote on the object.

Running this on an object with no existing vote has no adverse effects.

Note: votes must be cast by humans. That is, API clients proxying a human’s action one-for-one are OK, but bots deciding how to vote on content or amplifying a human’s vote are not. See the reddit rules for more details on what constitutes vote cheating.

Source for note: http://www.reddit.com/dev/api#POST_api_vote

Returns:The json response from the server.
downvote()

Downvote object. If there already is a vote, replace it.

Note: votes must be cast by humans. That is, API clients proxying a human’s action one-for-one are OK, but bots deciding how to vote on content or amplifying a human’s vote are not. See the reddit rules for more details on what constitutes vote cheating.

Source for note: http://www.reddit.com/dev/api#POST_api_vote

Returns:The json response from the server.
upvote()

Upvote object. If there already is a vote, replace it.

Note: votes must be cast by humans. That is, API clients proxying a human’s action one-for-one are OK, but bots deciding how to vote on content or amplifying a human’s vote are not. See the reddit rules for more details on what constitutes vote cheating.

Source for note: http://www.reddit.com/dev/api#POST_api_vote

Returns:The json response from the server.
vote(direction=0)

Vote for the given item in the direction specified.

Note: votes must be cast by humans. That is, API clients proxying a human’s action one-for-one are OK, but bots deciding how to vote on content or amplifying a human’s vote are not. See the reddit rules for more details on what constitutes vote cheating.

Source for note: http://www.reddit.com/dev/api#POST_api_vote

Requires the vote oauth scope or user/password authentication.

Returns:The json response from the server.
class praw.objects.WikiPage(reddit_session, subreddit=None, page=None, json_dict=None, fetch=True)

Bases: praw.objects.RedditContentObject

An individual WikiPage object.

Construct an instance of the WikiPage object.

edit(*args, **kwargs)

Edit the wiki page.

Convenience function that utilizes AuthenticatedReddit.edit_wiki_page() populating both the subreddit and page parameters.

classmethod from_api_response(reddit_session, json_dict)

Return an instance of the appropriate class from the json_dict.

class praw.objects.WikiPageListing(reddit_session, json_dict=None, fetch=False)

Bases: praw.objects.PRAWListing

A list of WikiPages. Works just like a regular list.

Construct an instance of the PRAWListing object.

CHILD_ATTRIBUTE = u'_tmp'

helpers Module

Helper functions.

The functions here provide functionality that is often needed by programs using PRAW, but which isn’t part of reddit’s API.

class praw.helpers.BoundedSet(max_items)

Bases: object

A set with a maxmimum size that evicts the oldest items when necessary.

This class does not implement the complete set interface.

Construct an instance of the BoundedSet.

add(item)

Add an item to the set discarding the oldest item if necessary.

praw.helpers.comment_stream(reddit_session, subreddit, limit=None, verbosity=1)

Indefinitely yield new comments from the provided subreddit.

Comments are yielded from oldest to newest.

Parameters:
  • reddit_session – The reddit_session to make requests from. In all the examples this is assigned to the variable r.
  • subreddit – Either a subreddit object, or the name of a subreddit. Use all to get the comment stream for all comments made to reddit.
  • limit – The maximum number of comments to fetch in a single iteration. When None, fetch all available comments (reddit limits this to 1000 (or multiple of 1000 for multi-subreddits). If this number is too small, comments may be missed.
  • verbosity – A number that controls the amount of output produced to stderr. <= 0: no output; >= 1: output the total number of comments processed and provide the short-term number of comments processed per second; >= 2: output when additional delays are added in order to avoid subsequent unexpected http errors. >= 3: output debugging information regarding the comment stream. (Default: 1)
praw.helpers.convert_id36_to_numeric_id(id36)

Convert strings representing base36 numbers into an integer.

praw.helpers.convert_numeric_id_to_id36(numeric_id)

Convert an integer into its base36 string representation.

This method has been cleaned up slightlyto improve readability. For more info see:

https://github.com/reddit/reddit/blob/master/r2/r2/lib/utils/_utils.pyx http://www.reddit.com/r/redditdev/comments/n624n/submission_ids_question/ http://en.wikipedia.org/wiki/Base_36#Python_implementation

praw.helpers.flatten_tree(tree, nested_attr=u'replies', depth_first=False)

Return a flattened version of the passed in tree.

Parameters:
  • nested_attr – The attribute name that contains the nested items. Defaults to replies which is suitable for comments.
  • depth_first – When true, add to the list in a depth-first manner rather than the default breadth-first manner.
praw.helpers.normalize_url(url)

Return url after stripping trailing .json and trailing slashes.

praw.helpers.submission_stream(reddit_session, subreddit, limit=None, verbosity=1)

Indefinitely yield new submissions from the provided subreddit.

Submissions are yielded from oldest to newest.

Parameters:
  • reddit_session – The reddit_session to make requests from. In all the examples this is assigned to the variable r.
  • subreddit – Either a subreddit object, or the name of a subreddit. Use all to get the submissions stream for all submissions made to reddit.
  • limit – The maximum number of submissions to fetch in a single iteration. When None, fetch all available submissions (reddit limits this to 1000 (or multiple of 1000 for multi-subreddits). If this number is too small, submissions may be missed. Since there isn’t a limit to the number of submissions that can be retrieved from r/all, the limit will be set to 1000 when limit is None.
  • verbosity – A number that controls the amount of output produced to stderr. <= 0: no output; >= 1: output the total number of submissions processed and provide the short-term number of submissions processed per second; >= 2: output when additional delays are added in order to avoid subsequent unexpected http errors. >= 3: output debugging information regarding the submission stream. (Default: 1)
praw.helpers.valid_redditors(redditors, sub)

Return a verified list of valid Redditor instances.

Parameters:
  • redditors – A list comprised of Redditor instances and/or strings that are to be verified as actual redditor accounts.
  • sub – A Subreddit instance that the authenticated account has flair changing permission on.

Note: Flair will be unset for all valid redditors in redditors on the subreddit mod_sub.

errors Module

Error classes.

Includes two main exceptions. ClientException, when something goes wrong on our end and APIExeception for when something goes wrong on the server side. A number of classes extend these two main exceptions for more specific exceptions.

exception praw.errors.APIException(error_type, message, field=u'', response=None)

Bases: praw.errors.PRAWException

Base exception class for the reddit API error message exceptions.

All exceptions of this type _should_ have their own subclass.

Construct an APIException.

Parameters:
  • error_type – The error type set on reddit’s end.
  • message – The associated message for the error.
  • field – The input field associated with the error, or ‘’.
  • response – The HTTP response that resulted in the exception.
exception praw.errors.AlreadyModerator(error_type, message, field=u'', response=None)

Bases: praw.errors.APIException

Used to indicate that a user is already a moderator of a subreddit.

Construct an APIException.

Parameters:
  • error_type – The error type set on reddit’s end.
  • message – The associated message for the error.
  • field – The input field associated with the error, or ‘’.
  • response – The HTTP response that resulted in the exception.
ERROR_TYPE = u'ALREADY_MODERATOR'
exception praw.errors.AlreadySubmitted(error_type, message, field=u'', response=None)

Bases: praw.errors.APIException

An exception to indicate that a URL was previously submitted.

Construct an APIException.

Parameters:
  • error_type – The error type set on reddit’s end.
  • message – The associated message for the error.
  • field – The input field associated with the error, or ‘’.
  • response – The HTTP response that resulted in the exception.
ERROR_TYPE = u'ALREADY_SUB'
exception praw.errors.BadCSS(error_type, message, field=u'', response=None)

Bases: praw.errors.APIException

An exception to indicate bad CSS (such as invalid) was used.

Construct an APIException.

Parameters:
  • error_type – The error type set on reddit’s end.
  • message – The associated message for the error.
  • field – The input field associated with the error, or ‘’.
  • response – The HTTP response that resulted in the exception.
ERROR_TYPE = u'BAD_CSS'
exception praw.errors.BadCSSName(error_type, message, field=u'', response=None)

Bases: praw.errors.APIException

An exception to indicate a bad CSS name (such as invalid) was used.

Construct an APIException.

Parameters:
  • error_type – The error type set on reddit’s end.
  • message – The associated message for the error.
  • field – The input field associated with the error, or ‘’.
  • response – The HTTP response that resulted in the exception.
ERROR_TYPE = u'BAD_CSS_NAME'
exception praw.errors.BadUsername(error_type, message, field=u'', response=None)

Bases: praw.errors.APIException

An exception to indicate an invalid username was used.

Construct an APIException.

Parameters:
  • error_type – The error type set on reddit’s end.
  • message – The associated message for the error.
  • field – The input field associated with the error, or ‘’.
  • response – The HTTP response that resulted in the exception.
ERROR_TYPE = u'BAD_USERNAME'
exception praw.errors.ClientException(message)

Bases: praw.errors.PRAWException

Base exception class for errors that don’t involve the remote API.

Construct a ClientException.

Params message:The error message to display.
exception praw.errors.ExceptionList(errors)

Bases: praw.errors.APIException

Raised when more than one exception occurred.

Construct an ExceptionList.

Parameters:errors – The list of errors.
exception praw.errors.InsufficientCreddits(error_type, message, field=u'', response=None)

Bases: praw.errors.APIException

Raised when there are not enough creddits to complete the action.

Construct an APIException.

Parameters:
  • error_type – The error type set on reddit’s end.
  • message – The associated message for the error.
  • field – The input field associated with the error, or ‘’.
  • response – The HTTP response that resulted in the exception.
ERROR_TYPE = u'INSUFFICIENT_CREDDITS'
exception praw.errors.InvalidCaptcha(error_type, message, field=u'', response=None)

Bases: praw.errors.APIException

An exception for when an incorrect captcha error is returned.

Construct an APIException.

Parameters:
  • error_type – The error type set on reddit’s end.
  • message – The associated message for the error.
  • field – The input field associated with the error, or ‘’.
  • response – The HTTP response that resulted in the exception.
ERROR_TYPE = u'BAD_CAPTCHA'
exception praw.errors.InvalidComment

Bases: praw.errors.PRAWException

Indicate that the comment is no longer available on reddit.

exception praw.errors.InvalidEmails(error_type, message, field=u'', response=None)

Bases: praw.errors.APIException

An exception for when invalid emails are provided.

Construct an APIException.

Parameters:
  • error_type – The error type set on reddit’s end.
  • message – The associated message for the error.
  • field – The input field associated with the error, or ‘’.
  • response – The HTTP response that resulted in the exception.
ERROR_TYPE = u'BAD_EMAILS'
exception praw.errors.InvalidFlairTarget(error_type, message, field=u'', response=None)

Bases: praw.errors.APIException

An exception raised when an invalid user is passed as a flair target.

Construct an APIException.

Parameters:
  • error_type – The error type set on reddit’s end.
  • message – The associated message for the error.
  • field – The input field associated with the error, or ‘’.
  • response – The HTTP response that resulted in the exception.
ERROR_TYPE = u'BAD_FLAIR_TARGET'
exception praw.errors.InvalidInvite(error_type, message, field=u'', response=None)

Bases: praw.errors.APIException

Raised when attempting to accept a nonexistent moderator invite.

Construct an APIException.

Parameters:
  • error_type – The error type set on reddit’s end.
  • message – The associated message for the error.
  • field – The input field associated with the error, or ‘’.
  • response – The HTTP response that resulted in the exception.
ERROR_TYPE = u'NO_INVITE_FOUND'
exception praw.errors.InvalidSubreddit

Bases: praw.errors.PRAWException

Indicates that an invalid subreddit name was supplied.

exception praw.errors.InvalidUser(error_type, message, field=u'', response=None)

Bases: praw.errors.APIException

An exception for when a user doesn’t exist.

Construct an APIException.

Parameters:
  • error_type – The error type set on reddit’s end.
  • message – The associated message for the error.
  • field – The input field associated with the error, or ‘’.
  • response – The HTTP response that resulted in the exception.
ERROR_TYPE = u'USER_DOESNT_EXIST'
exception praw.errors.InvalidUserPass(error_type, message, field=u'', response=None)

Bases: praw.errors.APIException

An exception for failed logins.

Construct an APIException.

Parameters:
  • error_type – The error type set on reddit’s end.
  • message – The associated message for the error.
  • field – The input field associated with the error, or ‘’.
  • response – The HTTP response that resulted in the exception.
ERROR_TYPE = u'WRONG_PASSWORD'
exception praw.errors.LoginOrScopeRequired(function, scope, message=None)

Bases: praw.errors.OAuthScopeRequired, praw.errors.LoginRequired

Indicates that either a logged in session or OAuth2 scope is required.

The attribute scope will contain the name of the necessary scope.

Construct a LoginOrScopeRequired exception.

Parameters:
  • function – The function that requires authentication.
  • scope – The scope that is required if not logged in.
  • message – A custom message to associate with the exception. Default: function requires a logged in session or the OAuth2 scope scope
exception praw.errors.LoginRequired(function, message=None)

Bases: praw.errors.ClientException

Indicates that a logged in session is required.

This exception is raised on a preemptive basis, whereas NotLoggedIn occurs in response to a lack of credentials on a privileged API call.

Construct a LoginRequired exception.

Parameters:
  • function – The function that requires login-based authentication.
  • message – A custom message to associate with the exception. Default: function requires a logged in session
exception praw.errors.ModeratorOrScopeRequired(function, scope)

Bases: praw.errors.LoginOrScopeRequired, praw.errors.ModeratorRequired

Indicates that a moderator of the sub or OAuth2 scope is required.

The attribute scope will contain the name of the necessary scope.

Construct a ModeratorOrScopeRequired exception.

Parameters:
  • function – The function that requires moderator authentication or a moderator scope..
  • scope – The scope that is required if not logged in with moderator access..
exception praw.errors.ModeratorRequired(function)

Bases: praw.errors.LoginRequired

Indicates that a moderator of the subreddit is required.

Construct a ModeratorRequired exception.

Parameters:function – The function that requires moderator access.
exception praw.errors.NotFound

Bases: praw.errors.PRAWException

Raised when the requested entity is not found.

exception praw.errors.NotLoggedIn(error_type, message, field=u'', response=None)

Bases: praw.errors.APIException

An exception for when a Reddit user isn’t logged in.

Construct an APIException.

Parameters:
  • error_type – The error type set on reddit’s end.
  • message – The associated message for the error.
  • field – The input field associated with the error, or ‘’.
  • response – The HTTP response that resulted in the exception.
ERROR_TYPE = u'USER_REQUIRED'
exception praw.errors.NotModified(response)

Bases: praw.errors.APIException

An exception raised when reddit returns {‘error’: 304}.

This error indicates that the requested content was not modified and is being requested too frequently. Such an error usually occurs when multiple instances of PRAW are running concurrently or in rapid succession.

Construct an instance of the NotModified exception.

This error does not have an error_type, message, nor field.

exception praw.errors.OAuthAppRequired(message)

Bases: praw.errors.ClientException

Raised when an OAuth client cannot be initialized.

This occurs when any one of the OAuth config values are not set.

Construct a ClientException.

Params message:The error message to display.
exception praw.errors.OAuthException(message, url)

Bases: praw.errors.PRAWException

Base exception class for OAuth API calls.

Attribute message contains the error message. Attribute url contains the url that resulted in the error.

Construct a OAuthException.

Parameters:
  • message – The message associated with the exception.
  • url – The url that resulted in error.
exception praw.errors.OAuthInsufficientScope(message, url)

Bases: praw.errors.OAuthException

Raised when the current OAuth scope is not sufficient for the action.

This indicates the access token is valid, but not for the desired action.

Construct a OAuthException.

Parameters:
  • message – The message associated with the exception.
  • url – The url that resulted in error.
exception praw.errors.OAuthInvalidGrant(message, url)

Bases: praw.errors.OAuthException

Raised when the code to retrieve access information is not valid.

Construct a OAuthException.

Parameters:
  • message – The message associated with the exception.
  • url – The url that resulted in error.
exception praw.errors.OAuthInvalidToken(message, url)

Bases: praw.errors.OAuthException

Raised when the current OAuth access token is not valid.

Construct a OAuthException.

Parameters:
  • message – The message associated with the exception.
  • url – The url that resulted in error.
exception praw.errors.OAuthScopeRequired(function, scope, message=None)

Bases: praw.errors.ClientException

Indicates that an OAuth2 scope is required to make the function call.

The attribute scope will contain the name of the necessary scope.

Contruct an OAuthScopeRequiredClientException.

Parameters:
  • function – The function that requires a scope.
  • scope – The scope required for the function.
  • message – A custom message to associate with the exception. Default: function requires the OAuth2 scope scope
exception praw.errors.PRAWException

Bases: exceptions.Exception

The base PRAW Exception class.

Ideally, this can be caught to handle any exception from PRAW.

exception praw.errors.RateLimitExceeded(error_type, message, field, response)

Bases: praw.errors.APIException

An exception for when something has happened too frequently.

Contains a sleep_time attribute for the number of seconds that must transpire prior to the next request.

Construct an instance of the RateLimitExceeded exception.

The parameters match that of APIException.

The sleep_time attribute is extracted from the response object.

ERROR_TYPE = u'RATELIMIT'
exception praw.errors.RedirectException(request_url, response_url)

Bases: praw.errors.PRAWException

Raised when a redirect response occurs that is not expected.

Construct a RedirectException.

Parameters:
  • request_url – The url requested.
  • response_url – The url being redirected to.
exception praw.errors.SubredditExists(error_type, message, field=u'', response=None)

Bases: praw.errors.APIException

An exception to indicate that a subreddit name is not available.

Construct an APIException.

Parameters:
  • error_type – The error type set on reddit’s end.
  • message – The associated message for the error.
  • field – The input field associated with the error, or ‘’.
  • response – The HTTP response that resulted in the exception.
ERROR_TYPE = u'SUBREDDIT_EXISTS'
exception praw.errors.UsernameExists(error_type, message, field=u'', response=None)

Bases: praw.errors.APIException

An exception to indicate that a username is not available.

Construct an APIException.

Parameters:
  • error_type – The error type set on reddit’s end.
  • message – The associated message for the error.
  • field – The input field associated with the error, or ‘’.
  • response – The HTTP response that resulted in the exception.
ERROR_TYPE = u'USERNAME_TAKEN'

handlers Module

Provides classes that handle request dispatching.

class praw.handlers.DefaultHandler

Bases: praw.handlers.RateLimitHandler

Extends the RateLimitHandler to add thread-safe caching support.

Establish the HTTP session.

ca_lock = <thread.lock object>
cache = {}
cache_hit_callback = None
classmethod clear_cache()

Remove all items from the cache.

classmethod evict(urls)

Remove items from cache matching URLs.

Return the number of items removed.

request(_cache_key, _cache_ignore, _cache_timeout, **kwargs)

Responsible for dispatching the request and returning the result.

Network level exceptions should be raised and only requests.Response should be returned.

Parameters:
  • request – A requests.PreparedRequest object containing all the data necessary to perform the request.
  • proxies – A dictionary of proxy settings to be utilized for the request.
  • timeout – Specifies the maximum time that the actual HTTP request can take.

**_ should be added to the method call to ignore the extra arguments intended for the cache handler.

timeouts = {}
static with_cache(function)

Return a decorator that interacts with a handler’s cache.

This decorator must be applied to a DefaultHandler class method or instance method as it assumes cache, ca_lock and timeouts are available.

class praw.handlers.MultiprocessHandler(host=u'localhost', port=10101)

Bases: object

A PRAW handler to interact with the PRAW multi-process server.

Construct an instance of the MultiprocessHandler.

evict(urls)

Forward the eviction to the server and return its response.

request(**kwargs)

Forward the request to the server and return its http response.

class praw.handlers.RateLimitHandler

Bases: object

The base handler that provides thread-safe rate limiting enforcement.

While this handler is threadsafe, PRAW is not thread safe when the same Reddit instance is being utilized from multiple threads.

Establish the HTTP session.

classmethod evict(urls)

Method utilized to evict entries for the given urls.

Parameters:urls – An iterable containing normalized urls.
Returns:The number of items removed from the cache.

By default this method returns False as a cache need not be present.

last_call = {}
static rate_limit(function)

Return a decorator that enforces API request limit guidelines.

We are allowed to make a API request every api_request_delay seconds as specified in praw.ini. This value may differ from reddit to reddit. For reddit.com it is 2. Any function decorated with this will be forced to delay _rate_delay seconds from the calling of the last function decorated with this before executing.

This decorator must be applied to a RateLimitHandler class method or instance method as it assumes rl_lock and last_call are available.

request(_rate_domain, _rate_delay, **kwargs)

Responsible for dispatching the request and returning the result.

Network level exceptions should be raised and only requests.Response should be returned.

Parameters:
  • request – A requests.PreparedRequest object containing all the data necessary to perform the request.
  • proxies – A dictionary of proxy settings to be utilized for the request.
  • timeout – Specifies the maximum time that the actual HTTP request can take.

**_ should be added to the method call to ignore the extra arguments intended for the cache handler.

rl_lock = <thread.lock object>

decorators Module

Decorators.

Mainly do two things. Ensure API guidelines are met and prevent unnecessary failed API requests by testing that the call can be made first. Also limit the length of output strings and parse json response for certain errors.

praw.decorators.alias_function(function, class_name)

Create a RedditContentObject function mapped to a BaseReddit function.

The BaseReddit classes define the majority of the API’s functions. The first argument for many of these functions is the RedditContentObject that they operate on. This factory returns functions appropriate to be called on a RedditContent object that maps to the corresponding BaseReddit function.

praw.decorators.deprecated(msg=u'')

Deprecate decorated method.

praw.decorators.limit_chars(function)

Truncate the string returned from a function and return the result.

praw.decorators.oauth_generator(function)

Set the _use_oauth keyword argument to True when appropriate.

This is needed because generator functions may be called at anytime, and PRAW relies on the Reddit._use_oauth value at original call time to know when to make OAuth requests.

Returned data is not modified.

praw.decorators.raise_api_exceptions(function)

Raise client side exception(s) when present in the API response.

Returned data is not modified.

praw.decorators.require_captcha(function)

Return a decorator for methods that require captchas.

praw.decorators.require_oauth(function)

Verify that the OAuth functions can be used prior to use.

Returned data is not modified.

praw.decorators.restrict_access(scope, mod=None, login=None, oauth_only=False)

Restrict function access unless the user has the necessary permissions.

Raises one of the following exceptions when appropriate:
  • LoginRequired
  • LoginOrOAuthRequired * the scope attribute will provide the necessary scope name
  • ModeratorRequired
  • ModeratorOrOAuthRequired * the scope attribute will provide the necessary scope name
Parameters:
  • scope – Indicate the scope that is required for the API call. None or False must be passed to indicate that no scope handles the API call. All scopes save for read imply login=True. Scopes with ‘mod’ in their name imply mod=True.
  • mod – Indicate that a moderator is required. Implies login=True.
  • login – Indicate that a login is required.
  • oauth_only – Indicate that only OAuth is supported for the function.

Returned data is not modified.

This decorator assumes that all mod required functions fit one of:

  • have the subreddit as the first argument (Reddit instance functions) or have a subreddit keyword argument
  • are called upon a subreddit object (Subreddit RedditContentObject)
  • are called upon a RedditContent object with attribute subreddit