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.

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='')

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='')

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_me()

Return a LoggedInRedditor object.

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.

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='', flair_text='')

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, check 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 – 36 characters id found in the HTML of a flair selector.
  • 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.

get_content(url, params=None, limit=0, place_holder=None, root_field='data', thing_field='children', after_field='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_json(url, params=None, data=None, as_objects=True, retry_on_error=None)

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.

API_PATHS = {'comment': 'api/comment/', 'feedback': 'api/feedback/', 'duplicates': 'duplicates/%s/', 'username_available': 'api/username_available/', 'subreddit': 'r/%s/', 'subreddit_css': 'api/subreddit_stylesheet/', 'controversial': 'controversial/', 'select_flair': 'api/selectflair/', 'saved': 'saved/', 'blocked': 'prefs/blocked/', 'subreddit_comments': 'r/%s/comments/', 'compose': 'api/compose/', 'morechildren': 'api/morechildren/', 'help': 'help/', 'user_about': 'user/%s/about/', 'save': 'api/save/', 'sent': 'message/sent/', 'info': 'api/info/', 'deleteflair': 'api/deleteflair', 'banned': 'r/%s/about/banned/', 'subreddit_settings': 'r/%s/about/edit/', 'accept_mod_invite': 'api/accept_moderator_invite', 'report': 'api/report/', 'unmarknsfw': 'api/unmarknsfw/', 'marknsfw': 'api/marknsfw/', 'remove': 'api/remove/', 'edit': 'api/editusertext/', 'ignore_reports': 'api/ignore_reports/', 'unsave': 'api/unsave/', 'flair': 'api/flair/', 'contest_mode': 'api/set_contest_mode/', 'flairlist': 'r/%s/api/flairlist/', 'site_admin': 'api/site_admin/', 'my_con_subreddits': 'subreddits/mine/contributor/', 'mod_mail': 'r/%s/message/moderator/', 'subreddit_about': 'r/%s/about/', 'hide': 'api/hide/', 'unhide': 'api/unhide/', 'comments': 'comments/', 'modlog': 'r/%s/about/log/', 'wiki_page': 'r/%s/wiki/%s', 'new': 'new/', 'sub_comments_gilded': 'r/%s/comments/gilded/', 'distinguish': 'api/distinguish/', 'sticky_submission': 'api/set_subreddit_sticky/', 'search': 'r/%s/search/', 'by_id': 'by_id/', 'reports': 'r/%s/about/reports/', 'moderators': 'r/%s/about/moderators/', 'delete_redditor': 'api/delete_user', 'mentions': 'message/mentions', 'login': 'api/login/', 'approve': 'api/approve/', 'authorize': 'api/v1/authorize/', 'unmoderated': 'r/%s/about/unmoderated/', 'flairconfig': 'api/flairconfig/', 'domain': 'domain/%s/', 'subscribe': 'api/subscribe/', 'rising': 'rising/', 'inbox': 'message/inbox/', 'vote': 'api/vote/', 'flairtemplate': 'api/flairtemplate/', 'spam': 'r/%s/about/spam/', 'top': 'top/', 'submit': 'api/submit/', 'stylesheet': 'r/%s/about/stylesheet/', 'unignore_reports': 'api/unignore_reports/', 'friend': 'api/friend/', 'popular_subreddits': 'subreddits/popular/', 'unread_message': 'api/unread_message/', 'unfriend': 'api/unfriend/', 'upload_image': 'api/upload_sr_img', 'access_token_url': 'api/v1/access_token/', 'me': 'api/v1/me', 'reddit_url': '/', 'subreddit_random': 'r/%s/random/', 'search_reddit_names': 'api/search_reddit_names/', 'modqueue': 'r/%s/about/modqueue/', 'del': 'api/del/', 'unread': 'message/unread/', 'clearflairtemplates': 'api/clearflairtemplates/', 'wiki_edit': 'api/wiki/edit/', 'contributors': 'r/%s/about/contributors/', 'my_subreddits': 'subreddits/mine/subscriber/', 'delete_sr_header': 'r/%s/api/delete_sr_header', 'new_subreddits': 'subreddits/new/', 'captcha': 'captcha/', 'wiki_contributors': 'r/%s/about/wikicontributors/', 'read_message': 'api/read_message/', 'flaircsv': 'api/flaircsv/', 'wiki_pages': 'r/%s/wiki/pages/', 'sub_recommendations': 'api/subreddit_recommendations/', 'user': 'user/%s/', 'wiki_banned': 'r/%s/about/wikibanned/', 'friends': 'prefs/friends/', 'my_mod_subreddits': 'subreddits/mine/moderator/', 'delete_sr_image': 'r/%s/api/delete_sr_img', 'register': 'api/register/'}
SSL_PATHS = ('access_token_url', 'authorize', 'login')
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.

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

Create a new subreddit.

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)

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='', description='', language='en', subreddit_type='public', content_options='any', over_18=False, default_set=True, show_media=False, domain='', domain_css=False, domain_sidebar=False, header_hover_text='', prev_description_id=None, prev_public_description_id=None, wikimode='disabled', wiki_edit_age=30, wiki_edit_karma=100, submit_link_label='', submit_text_label='', exclude_banned_modqueue=False, comment_score_hide_mins=0, public_traffic=False, prev_submit_text_id=None, spam_comments='low', spam_links='high', spam_selfposts='high', submit_text='', **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, prevstyle=None)

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.

add_flair_template(subreddit, text='', css_class='', 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='right', flair_self_assign=False, link_flair_enabled=False, link_flair_position='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='', flair_css_class='')

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.

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.

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.

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='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='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='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='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)

Return the stylesheet and images for the given subreddit.

get_unmoderated(subreddit='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.

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_reddits(*args, **kwargs)

Return a get_content generator of subreddits.

DEPRECATED. Will be removed in a future version of PRAW. Please use get_my_subreddits instead.

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.

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='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://ssl.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.

get_inbox(*args, **kwargs)

Return a get_content generator for inbox 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_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_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, captcha=None)

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

When sending a message to a subreddit the recipient parameter must either be a subreddit object or the subreddit name needs to be prefixed with either ‘/r/’ or ‘#’.

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.

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.

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.

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.

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.

create_redditor(user_name, password, email='', captcha=None)

Register a new user.

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.

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

Return a get_content generator for comments from all subreddits.

DEPRECATED. Will be removed in a future version of PRAW. Please use get_comments(‘all’, ...) instead.

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='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 Submissions 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 – The submission 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 thing_id is provided, return the corresponding Submission object, or None if not found. When url is provided return a list of Submission objects (up to limit) for the url.

get_moderators(subreddit)

Return the list of moderators for the given subreddit.

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.

DEPRECATED. Will be removed in a future version of PRAW. Please use get_popular_subreddits instead.

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='all')

Return a random Submission object.

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

Return a random Subreddit object.

Utilizes the same mechanism as http://www.reddit.com/r/random/.

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_submission(url=None, submission_id=None, comment_limit=0, comment_sort=None, params={})

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, omitted=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.
  • omitted – 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)

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

send_feedback(name, email, message, reason='feedback', captcha=None)

Send feedback to the admins.

Please don’t abuse this. Read the send feedback page at http://www.reddit.com/feedback/ (for reddit.com) before use.

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.

Returns:The json response from the server.

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.Inboxable, praw.objects.Moderatable, praw.objects.Reportable, praw.objects.Voteable

A class that represents a reddit comments.

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.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=True)

Bases: praw.objects.Redditor

A class representing a currently logged in Redditor.

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()

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

Will throw a RedirectException while https://github.com/praw-dev/praw/issues/175 is unresolved.

get_hidden(sort='new', time='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.
  • time – Specify the time-period to return submissions if applicable.

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

get_saved(sort='new', time='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.
  • time – Specify the time-period to return submissions if applicable.

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.

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.

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='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.

comments(update=True)

Fetch and return the comments for a single MoreComments object.

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

Bases: praw.objects.RedditContentObject

An abstract class to coerce a listing into RedditContentObjects.

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=True)

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

A class representing the users of reddit.

friend()

Friend the user.

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

Return a get_content generator for some RedditContentObject type.

Parameters:
  • sort – Specify the sort order of the results if applicable.
  • time – Specify the time-period to return submissions if applicable.

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

get_disliked()

Return a listing of the things the user has downvoted.

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_liked()

Return a listing of the things the user has upvoted.

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_overview(sort='new', time='all', *args, **kwargs)

Return a get_content generator for some RedditContentObject type.

Parameters:
  • sort – Specify the sort order of the results if applicable.
  • time – Specify the time-period to return submissions if applicable.

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

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

Return a get_content generator for some RedditContentObject type.

Parameters:
  • sort – Specify the sort order of the results if applicable.
  • time – Specify the time-period to return submissions if applicable.

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.

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()

Report this object to the moderators.

Requires user/password authentication.

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.Hideable, praw.objects.Moderatable, praw.objects.Refreshable, praw.objects.Reportable, praw.objects.Saveable, praw.objects.Voteable

A class for submissions to reddit.

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_url(reddit_session, url, comment_limit=0, comment_sort=None, comments_only=False, params={})

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_fileter parameters cannot be altered.

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

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.

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.

ban(thing, user, **kwargs)

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

DEPRECATED. Will be removed in a future version of PRAW. Please use add_ban instead.

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_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_new_by_date(*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.

DEPRECATED. Will be removed in a future version of PRAW. Please use get_new instead.

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

DEPRECATED. Will be removed in a future version of PRAW. Please use get_rising instead.

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

make_contributor(thing, user, **kwargs)

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

DEPRECATED. Will be removed in a future version of PRAW. Please use add_contributor instead.

make_moderator(thing, user, **kwargs)

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

DEPRECATED. Will be removed in a future version of PRAW. Please use add_moderator instead.

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.

unban(thing, user, **kwargs)

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

DEPRECATED. Will be removed in a future version of PRAW. Please use remove_ban instead.

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.

CHILD_ATTRIBUTE = '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.

edit(*args, **kwargs)

Edit the wiki page.

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

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.

CHILD_ATTRIBUTE = '_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.

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 base 36 into numeric ID

praw.helpers.convert_numeric_id_to_id36(numeric_id)

Convert numeric ID into base36, method has been cleaned up slightly to 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)

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='', response=None)

Bases: exceptions.Exception

Base exception class for the reddit API error message exceptions.

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

Bases: praw.errors.APIException

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

ERROR_TYPE = 'ALREADY_MODERATOR'
exception praw.errors.AlreadySubmitted(error_type, message, field='', response=None)

Bases: praw.errors.APIException

An exception to indicate that a URL was previously submitted.

ERROR_TYPE = 'ALREADY_SUB'
exception praw.errors.BadCSS(error_type, message, field='', response=None)

Bases: praw.errors.APIException

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

ERROR_TYPE = 'BAD_CSS'
exception praw.errors.BadCSSName(error_type, message, field='', response=None)

Bases: praw.errors.APIException

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

ERROR_TYPE = 'BAD_CSS_NAME'
exception praw.errors.BadUsername(error_type, message, field='', response=None)

Bases: praw.errors.APIException

An exception to indicate an invalid username was used.

ERROR_TYPE = 'BAD_USERNAME'
exception praw.errors.ClientException(message)

Bases: exceptions.Exception

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

exception praw.errors.ExceptionList(errors)

Bases: praw.errors.APIException

Raised when more than one exception occurred.

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

Bases: praw.errors.APIException

An exception for when an incorrect captcha error is returned.

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

Bases: praw.errors.APIException

An exception for when invalid emails are provided.

ERROR_TYPE = 'BAD_EMAILS'
exception praw.errors.InvalidFlairTarget(error_type, message, field='', response=None)

Bases: praw.errors.APIException

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

ERROR_TYPE = 'BAD_FLAIR_TARGET'
exception praw.errors.InvalidInvite(error_type, message, field='', response=None)

Bases: praw.errors.APIException

Raised when attempting to accept a nonexistent moderator invite.

ERROR_TYPE = 'NO_INVITE_FOUND'
exception praw.errors.InvalidSubreddit(message)

Bases: praw.errors.ClientException

Indicates that an invalid subreddit name was supplied.

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

Bases: praw.errors.APIException

An exception for when a user doesn’t exist.

ERROR_TYPE = 'USER_DOESNT_EXIST'
exception praw.errors.InvalidUserPass(error_type, message, field='', response=None)

Bases: praw.errors.APIException

An exception for failed logins.

ERROR_TYPE = '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.

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.

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.

exception praw.errors.ModeratorRequired(function)

Bases: praw.errors.LoginRequired

Indicates that a moderator of the subreddit is required.

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

Bases: praw.errors.APIException

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

ERROR_TYPE = '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.

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.

exception praw.errors.OAuthException(message, url)

Bases: exceptions.Exception

Base exception class for OAuth API calls.

Attribute message contains the error message. Attribute url contains the url that resulted in the 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.

exception praw.errors.OAuthInvalidGrant(message, url)

Bases: praw.errors.OAuthException

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

exception praw.errors.OAuthInvalidToken(message, url)

Bases: praw.errors.OAuthException

Raised when the current OAuth access token is not valid.

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.

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

Bases: praw.errors.APIException

An exception for when something has happened too frequently.

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

Bases: praw.errors.ClientException

Raised when a redirect response occurs that is not expected.

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

Bases: praw.errors.APIException

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

ERROR_TYPE = 'SUBREDDIT_EXISTS'
exception praw.errors.UsernameExists(error_type, message, field='', response=None)

Bases: praw.errors.APIException

An exception to indicate that a username is not available.

ERROR_TYPE = '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.

ca_lock = <thread.lock object at 0x7f4fa28a0830>
cache = {}
cache_hit_callback = None
classmethod evict(urls)

Remove items from cache matching URL.

Return whether or not any items were 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='localhost', port=10101)

Bases: object

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

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.

classmethod evict(urls)

Method utilized to evict entries for the given urls.

Parameters:urls – An iterable containing normalized urls.
Returns:Whether or not an item was 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 at 0x7f4fa28a0750>

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='')

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)
  • are called upon a subreddit object (Subreddit RedditContentObject)
  • are called upon a RedditContent object with attribute subreddit

internal Module

Internal helper functions.