Code Overview

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

praw Package

Python Reddit API Wrapper.

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

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

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

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

This class adds the methods necessary for authenticating with reddit.

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

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

Initialize an AuthenticatedReddit instance.

accept_moderator_invite(subreddit)

Accept a moderator invite to the given subreddit.

Callable upon an instance of Subreddit with no arguments.

Returns:The json response from the server.

clear_authentication()

Clear any existing authentication on the reddit object.

This function is implicitly called on login and set_access_credentials.

delete(password, message=u'')

Delete the currently authenticated redditor.

WARNING!

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

Parameters:

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

Returns:

json response from the server.

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

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

Returns:The json response from the server.

get_access_information(code, update_session=True)

Return the access information for an OAuth2 authorization grant.

Parameters:

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

Returns:

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

get_flair_choices(subreddit, link=None)

Return available flair choices and current flair.

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

get_friends(**params)

Return a UserList of Redditors with whom the user is friends.

get_me()

Return a LoggedInRedditor object.

Note: This function is only intended to be used with an ‘identity’ providing OAuth2 grant.

has_scope(scope)

Return True if OAuth2 authorized for the passed in scope(s).

is_logged_in()

Return True when the session is authenticated via username/password.

Username and passwords are provided via login().

is_oauth_session()

Return True when the current session is an OAuth2 session.

login(username=None, password=None, **kwargs)

Login to a reddit site.

DEPRECATED. Will be removed in a future version of PRAW.

https://www.reddit.com/comments/2ujhkr/ https://www.reddit.com/comments/37e2mv/

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 None when the OAuth2 grant is not refreshable. The scope value will be a set containing the scopes the tokens are valid for.

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

Select user flair or link flair on subreddits.

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

Parameters:

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

Returns:

The json response from the server.

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

Set the credentials used for OAuth2 authentication.

Calling this function will overwrite any currently existing access credentials.

Parameters:

• scope – A set of reddit scopes the tokens provide access to
• access_token – the access token of the authentication
• refresh_token – the refresh token of the authentication
• update_user – Whether or not to set the user attribute for identity scopes

class praw.__init__.BaseReddit(user_agent, site_name=None, handler=None, disable_update_check=False, **kwargs)

Bases: object

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

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

Initialize our connection with a reddit server.

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

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

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

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

RETRY_CODES = [502, 503, 504]

evict(urls)

Evict url(s) from the cache.

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

get_content(url, params=None, limit=0, place_holder=None, root_field=u'data', thing_field=u'children', after_field=u'after', object_filter=None, **kwargs)

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.

openssl_warned = False

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

Make a HTTP request and return the response.

Parameters:

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

Returns:

The HTTP response.

request_json(url, params=None, data=None, as_objects=True, retry_on_error=True, method=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.

Initialize PRAW’s configuration.

API_PATHS = {u'authorize': u'api/v1/authorize/', u'comment': u'api/comment/', u'flairconfig': u'api/flairconfig/', u'leavecontributor': u'api/leavecontributor', u'help': u'help/', u'wiki_page_editor': u'r/{subreddit}/api/wiki/alloweditor/{method}', u'friend_v1': u'api/v1/me/friends/{user}', u'duplicates': u'duplicates/{submissionid}/', u'comment_replies': u'message/comments/', u'username_available': u'api/username_available/', u'domain': u'domain/{domain}/', u'subreddit': u'r/{subreddit}/', u'subscribe': u'api/subscribe/', u'subreddit_css': u'api/subreddit_stylesheet/', u'rising': u'rising/', u'inbox': u'message/inbox/', u'controversial': u'controversial/', u'select_flair': u'api/selectflair/', u'vote': u'api/vote/', u'message': u'message/messages/{messageid}/', u'saved': u'saved/', u'flairtemplate': u'api/flairtemplate/', u'my_subreddits': u'subreddits/mine/subscriber/', u'blocked': u'prefs/blocked/', u'subreddit_comments': u'r/{subreddit}/comments/', u'compose': u'api/compose/', u'morechildren': u'api/morechildren/', u'spam': u'r/{subreddit}/about/spam/', u'top': u'top/', u'post_replies': u'message/selfreply/', u'submit': u'api/submit/', u'multireddit_add': u'api/multi/user/{user}/m/{multi}/r/{subreddit}', u'default_subreddits': u'subreddits/default/', u'stylesheet': u'r/{subreddit}/about/stylesheet/', u'unread_message': u'api/unread_message/', u'user_about': u'user/{user}/about/', u'multireddit_rename': u'api/multi/rename/', u'save': u'api/save/', u'friend': u'api/friend/', u'me': u'api/v1/me', u'deleteflair': u'api/deleteflair', u'unmoderated': u'r/{subreddit}/about/unmoderated/', u'unfriend': u'api/unfriend/', u'rules': u'r/{subreddit}/about/rules/', u'banned': u'r/{subreddit}/about/banned/', u'subreddit_settings': u'r/{subreddit}/about/edit/', u'search': u'r/{subreddit}/search/', u'accept_mod_invite': u'api/accept_moderator_invite', u'subreddit_random': u'r/{subreddit}/random/', u'new': u'new/', u'report': u'api/report/', u'upload_image': u'api/upload_sr_img', u'access_token_url': u'api/v1/access_token/', u'info': u'api/info/', u'suggested_sort': u'api/set_suggested_sort/', u'unignore_reports': u'api/unignore_reports/', u'reddit_url': u'/', u'collapse_message': u'api/collapse_message/', u'leavemoderator': u'api/leavemoderator', u'edit': u'api/editusertext/', u'search_reddit_names': u'api/search_reddit_names/', u'marknsfw': u'api/marknsfw/', u'unlock': u'api/unlock/', u'remove': u'api/remove/', u'modqueue': u'r/{subreddit}/about/modqueue/', u'gild_user': u'api/v1/gold/give/{username}/', u'del': u'api/del/', u'sent': u'message/sent/', u'wiki_contributors': u'r/{subreddit}/about/wikicontributors/', u'unread': u'message/unread/', u'multireddit': u'user/{user}/m/{multi}/', u'clearflairtemplates': u'api/clearflairtemplates/', u'contest_mode': u'api/set_contest_mode/', u'gild_thing': u'api/v1/gold/gild/{fullname}/', u'mute_sender': u'api/mute_message_author/', u'contributors': u'r/{subreddit}/about/contributors/', u'flairlist': u'r/{subreddit}/api/flairlist/', u'lock': u'api/lock/', u'site_admin': u'api/site_admin/', u'delete_sr_header': u'r/{subreddit}/api/delete_sr_header', u'new_subreddits': u'subreddits/new/', u'sticky': u'r/{subreddit}/about/sticky/', u'captcha': u'captcha/', u'my_con_subreddits': u'subreddits/mine/contributor/', u'mod_mail': u'r/{subreddit}/message/moderator/', u'register': u'api/register/', u'subreddit_about': u'r/{subreddit}/about/', u'hide': u'api/hide/', u'my_multis': u'api/multi/mine/', u'unhide': u'api/unhide/', u'muted': u'r/{subreddit}/about/muted/', u'wiki_banned': u'r/{subreddit}/about/wikibanned/', u'comments': u'comments/', u'modlog': u'r/{subreddit}/about/log/', u'wiki_page': u'r/{subreddit}/wiki/{page}', u'ignore_reports': u'api/ignore_reports/', u'sub_comments_gilded': u'r/{subreddit}/comments/gilded/', u'wiki_edit': u'api/wiki/edit/', u'edited': u'r/{subreddit}/about/edited/', u'flaircsv': u'api/flaircsv/', u'wiki_pages': u'r/{subreddit}/wiki/pages/', u'messages': u'message/messages/', u'sub_recommendations': u'api/recommend/sr/{subreddits}', u'unmarknsfw': u'api/unmarknsfw/', u'subreddit_traffic': u'r/{subreddit}/about/traffic/', u'multireddit_copy': u'api/multi/copy/', u'wiki_page_settings': u'r/{subreddit}/wiki/settings/{page}', u'flairselector': u'api/flairselector/', u'uncollapse_message': u'api/uncollapse_message/', u'unsave': u'api/unsave/', u'distinguish': u'api/distinguish/', u'read_message': u'api/read_message/', u'unmute_sender': u'api/unmute_message_author/', u'friends': u'prefs/friends/', u'popular_subreddits': u'subreddits/popular/', u'multireddit_mine': u'me/m/{multi}/', u'sticky_submission': u'api/set_subreddit_sticky/', u'my_mod_subreddits': u'subreddits/mine/moderator/', u'delete_sr_image': u'r/{subreddit}/api/delete_sr_img', u'multireddit_about': u'api/multi/user/{user}/m/{multi}/', u'multireddit_user': u'api/multi/user/{user}/', u'by_id': u'by_id/', u'reports': u'r/{subreddit}/about/reports/', u'moderators': u'r/{subreddit}/about/moderators/', u'delete_redditor': u'api/delete_user', u'mentions': u'message/mentions', u'login': u'api/login/', u'flair': u'api/flair/', u'approve': u'api/approve/', u'user': u'user/{user}/'}

WWW_PATHS = set([u'authorize'])

short_domain

Return the short domain of the reddit server.

Used to generate the shortlink. For reddit.com the short_domain is redd.it.

static ua_string(praw_info)

Return the user-agent string.

The user-agent string contains PRAW version and platform version info.

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

Bases: praw.__init__.AuthenticatedReddit

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

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

Initialize an AuthenticatedReddit instance.

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

Create a new subreddit.

Returns:The json response from the server.

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.

delete_image(subreddit, name=None, header=False)

Delete an image from the subreddit.

Parameters:

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

Returns:

The json response from the server.

get_settings(subreddit, **params)

Return the settings for the given subreddit.

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

Set the settings for the given subreddit.

Parameters:subreddit – Must be a subreddit object. Returns:The json response from the server.

set_stylesheet(subreddit, stylesheet)

Set stylesheet for the given subreddit.

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_as=None)

Upload an image to 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.
• upload_as – Must be ‘jpg’, ‘png’ or None. When None, this will match the format of the image itself. In all cases where both this value and the image format is not png, reddit will also convert the image mode to RGBA. reddit optimizes the image according to this value.

Returns:

A link to the uploaded image. Raises an exception otherwise.

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

Bases: praw.__init__.AuthenticatedReddit

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

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

Initialize an AuthenticatedReddit instance.

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

Add a flair template to the given subreddit.

Returns:The json response from the server.

clear_flair_templates(subreddit, is_link=False)

Clear flair templates for the given subreddit.

Returns:The json response from the server.

configure_flair(subreddit, flair_enabled=False, flair_position=u'right', flair_self_assign=False, link_flair_enabled=False, link_flair_position=u'left', link_flair_self_assign=False)

Configure the flair setting for the given subreddit.

Returns:The json response from the server.

delete_flair(subreddit, user)

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

Returns:The json response from the server.

get_flair_list(subreddit, *args, **kwargs)

Return a get_content generator of flair mappings.

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

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

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

Set flair for the user in the given subreddit.

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

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

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)

Returns:The json response from the server.

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

Bases: praw.__init__.AuthenticatedReddit

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

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

Initialize an AuthenticatedReddit instance.

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

Return a get_content generator for moderation log items.

Parameters:

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

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

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

Bases: praw.__init__.AuthenticatedReddit

Adds methods requiring the logged in moderator access.

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

Initialize an AuthenticatedReddit instance.

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

Return a get_content generator of banned users for the subreddit.

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 authentication as a moderator of the subreddit is required. For protected/private subreddits only access is required. See issue #246.

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

Return a get_content generator of edited items.

Parameters:subreddit – Either a Subreddit object or the name of the subreddit to return the edited items 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_mod_mail(subreddit=u'mod', *args, **kwargs)

Return a get_content generator for moderator messages.

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

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

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

Return a get_content generator for the moderator queue.

Parameters:subreddit – Either a Subreddit object or the name of the subreddit to return the modqueue 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_muted(subreddit, user_only=True, *args, **kwargs)

Return a get_content generator for modmail-muted users.

Parameters:subreddit – Either a Subreddit object or the name of a subreddit to get the list of muted users from.

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

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

Return a get_content generator of reported items.

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

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

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

Return a get_content generator of spam-filtered items.

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

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

get_stylesheet(subreddit, **params)

Return the stylesheet and images for the given subreddit.

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

Return a get_content generator of unmoderated submissions.

Parameters:subreddit – Either a Subreddit object or the name of the subreddit to return the unmoderated submissions 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.

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.

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

Bases: praw.__init__.AuthenticatedReddit

Adds methods pertaining to the ‘modself’ OAuth scope (or login).

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

Initialize an AuthenticatedReddit instance.

leave_contributor(subreddit)

Abdicate approved submitter status in a subreddit. Use with care.

Parameters:subreddit – The name of the subreddit to leave status from. Returns:the json response from the server.

leave_moderator(subreddit)

Abdicate moderator status in a subreddit. Use with care.

Parameters:subreddit – The name of the subreddit to leave status from. Returns:the json response from the server.

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

Bases: praw.__init__.AuthenticatedReddit

Adds methods pertaining to multireddits.

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

Initialize an AuthenticatedReddit instance.

MULTI_PATH = u'/user/{0}/m/{1}'

copy_multireddit(from_redditor, from_name, to_name=None, *args, **kwargs)

Copy a multireddit.

Parameters:

• from_redditor – The username or Redditor object for the user who owns the original multireddit
• from_name – The name of the multireddit, belonging to from_redditor
• to_name – The name to copy the multireddit as. If None, uses the name of the original

The additional parameters are passed directly into request_json()

create_multireddit(name, description_md=None, icon_name=None, key_color=None, subreddits=None, visibility=None, weighting_scheme=None, overwrite=False, *args, **kwargs)

Create a new multireddit.

Parameters:

• name – The name of the new multireddit.
• description_md – Optional description for the multireddit, formatted in markdown.
• icon_name – Optional, choose an icon name from this list: art and design, ask, books, business, cars, comics, cute animals, diy, entertainment, food and drink, funny, games, grooming, health, life advice, military, models pinup, music, news, philosophy, pictures and gifs, science, shopping, sports, style, tech, travel, unusual stories, video, or None.
• key_color – Optional rgb hex color code of the form #xxxxxx.
• subreddits – Optional list of subreddit names or Subreddit objects to initialize the Multireddit with. You can always add more later with add_subreddit().
• visibility – Choose a privacy setting from this list: public, private, hidden. Defaults to private if blank.
• weighting_scheme – Choose a weighting scheme from this list: classic, fresh. Defaults to classic if blank.
• overwrite – Allow for overwriting / updating multireddits. If False, and the multi name already exists, throw 409 error. If True, and the multi name already exists, use the given properties to update that multi. If True, and the multi name does not exist, create it normally.

Returns:

The newly created Multireddit object.

The additional parameters are passed directly into request_json()

delete_multireddit(name, *args, **kwargs)

Delete a Multireddit.

Any additional parameters are passed directly into request()

edit_multireddit(*args, **kwargs)

Edit a multireddit, or create one if it doesn’t already exist.

See create_multireddit() for accepted parameters.

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

Return a Multireddit object for the author and name specified.

Parameters:

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

The additional parameters are passed directly into the Multireddit constructor.

get_multireddits(redditor, *args, **kwargs)

Return a list of multireddits belonging to a redditor.

Parameters:redditor – The username or Redditor object to find multireddits from. Returns:The json response from the server

The additional parameters are passed directly into request_json()

If the requested redditor is the current user, all multireddits are visible. Otherwise, only public multireddits are returned.

rename_multireddit(current_name, new_name, *args, **kwargs)

Rename a Multireddit.

Parameters:

• current_name – The name of the multireddit to rename
• new_name – The new name to assign to this multireddit

The additional parameters are passed directly into request_json()

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

Bases: praw.__init__.AuthenticatedReddit

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

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

Initialize an AuthenticatedReddit instance.

get_my_contributions(*args, **kwargs)

Return a get_content generator of subreddits.

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

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

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.

get_my_multireddits()

Return a list of the authenticated Redditor’s Multireddits.

get_my_subreddits(*args, **kwargs)

Return a get_content generator of subreddits.

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

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

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

Bases: praw.__init__.BaseReddit

Provides functionality for obtaining reddit OAuth2 access tokens.

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

Initialize an OAuth2Reddit instance.

get_access_information(code)

Return the access information for an OAuth2 authorization grant.

Parameters:code – the code received in the request from the OAuth2 server Returns:A dictionary with the key/value pairs for access_token, refresh_token and scope. The refresh_token value will be None when the OAuth2 grant is not refreshable. The scope value will be a set containing the scopes the tokens are valid for.

get_authorize_url(state, scope=u'identity', refreshable=False)

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

Parameters:

• state – a unique string of your choice 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 when OAuth credentials are associated with the instance.

The necessary credentials are: client_id, client_secret and redirect_uri.

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.

Password grants aren’t refreshable, so use get_access_information() again, instead.

set_oauth_app_info(client_id, client_secret, redirect_uri)

Set the app information to use with OAuth2.

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

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

Parameters:

• client_id – the client_id of your application
• client_secret – the client_secret of your application
• redirect_uri – the redirect_uri of your application

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

Bases: praw.__init__.AuthenticatedReddit

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

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

Initialize an AuthenticatedReddit instance.

get_comment_replies(*args, **kwargs)

Return a get_content generator for inboxed comment replies.

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

get_inbox(*args, **kwargs)

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

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

get_mentions(*args, **kwargs)

Return a get_content generator for username mentions.

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

get_message(message_id, *args, **kwargs)

Return a Message object corresponding to the given ID.

Parameters:message_id – The ID or Fullname for a Message

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

get_messages(*args, **kwargs)

Return a get_content generator for inbox (messages only).

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

get_post_replies(*args, **kwargs)

Return a get_content generator for inboxed submission replies.

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

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.

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

Return a get_content generator for unread messages.

Parameters:

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

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

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

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

Parameters:

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

Returns:

The json response from the server.

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.

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

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

Provides access to reddit’s API.

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

Initialize an AuthenticatedReddit instance.

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

Bases: praw.__init__.AuthenticatedReddit

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

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

Initialize an AuthenticatedReddit instance.

hide(thing_id, _unhide=False)

Hide one or multiple objects in the context of the logged in user.

Parameters:

• thing_id – A single fullname or list of fullnames, representing objects which will be hidden.
• _unhide – If True, unhide the object(s) instead. Use unhide() rather than setting this manually.

Returns:

The json response from the server.

unhide(thing_id)

Unhide up to 50 objects in the context of the logged in user.

Parameters:thing_id – A single fullname or list of fullnames, representing objects which will be unhidden. Returns:The json response from the server.

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

Bases: praw.__init__.AuthenticatedReddit

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

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

Initialize an AuthenticatedReddit instance.

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

Submit a new link to the given subreddit.

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

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 – If True, inbox replies will be received when people comment on the submission. If set to None, 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.

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.

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

Bases: praw.__init__.AuthenticatedReddit

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

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

Initialize an AuthenticatedReddit instance.

subscribe(subreddit, unsubscribe=False)

Subscribe to the given subreddit.

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.

Initialize an UnauthenticatedReddit instance.

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

Register a new user.

Returns:The json response from the server.

default_subreddits(*args, **kwargs)

Return a get_content generator for the default subreddits.

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

get_comments(subreddit, gilded_only=False, *args, **kwargs)

Return a get_content generator for comments in the given subreddit.

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 https://www.reddit.com/controversial/ for the session.

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

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

Return a get_content generator for submissions by domain.

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

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, **params)

Return the flair for a user on the given 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 https://www.reddit.com/ for the session.

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

get_info(url=None, thing_id=None, *args, **kwargs)

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

Parameters:

• url – A url to lookup.
• thing_id – A single thing_id, or a list of thing_ids. A thing_id can be any one of Comment (t1_), Link (t3_), or Subreddit (t5_) to lookup by fullname.

Returns:

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

The additional parameters are passed into get_content() after the params parameter is exctracted and used to update the dictionary of url parameters this function sends. Note: the url parameter cannot be altered.

Also, if using thing_id and the limit parameter passed to get_content() is used to slice the list of retreived things before returning it to the user, for when limit > 100 and (limit % 100) > 0, to ensure a maximum of limit thigns are returned.

get_moderators(subreddit, **kwargs)

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 https://www.reddit.com/new/ for the session.

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

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.

get_popular_subreddits(*args, **kwargs)

Return a get_content generator for the most active subreddits.

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

get_random_submission(subreddit=u'all')

Return a random Submission object.

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

get_random_subreddit(nsfw=False)

Return a random Subreddit object.

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

get_redditor(user_name, *args, **kwargs)

Return a Redditor instance for the user_name specified.

The additional parameters are passed directly into the Redditor constructor.

get_rising(*args, **kwargs)

Return a get_content generator for rising submissions.

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

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

get_rules(subreddit, bottom=False)

Return the json dictionary containing rules for a subreddit.

Parameters:subreddit – The subreddit whose rules we will return.

get_sticky(subreddit, bottom=False)

Return a Submission object for the sticky of the subreddit.

Parameters:bottom – Get the top or bottom sticky. If the subreddit has only a single sticky, it is considered the top one.

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

Return a Submission object for the given url or submission_id.

Parameters:

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

get_submissions(fullnames, *args, **kwargs)

Generate Submission objects for each item provided in fullnames.

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

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

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

get_subreddit(subreddit_name, *args, **kwargs)

Return a Subreddit object for the subreddit_name specified.

The additional parameters are passed directly into the Subreddit constructor.

get_subreddit_recommendations(subreddits, omit=None)

Return a list of recommended subreddits as Subreddit objects.

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

Parameters:

• subreddits – A list of subreddits (either names or Subreddit objects) to base the recommendations on.
• omit – A list of subreddits (either names or Subreddit objects) that will be filtered out of the result.

get_top(*args, **kwargs)

Return a get_content generator for top submissions.

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

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

get_traffic(subreddit)

Return the json dictionary containing traffic stats for a subreddit.

Parameters:subreddit – The subreddit whose /about/traffic page we will collect.

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. If query is a URL only submissions which link to that URL will be returned.
• subreddit – Limit search results to the subreddit if provided.
• sort – The sort order of the results.
• syntax – The syntax of the search query.
• period – The time period of the results.

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

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

search_reddit_names(query)

Return subreddits whose display name contains the query.

objects Module

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

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

class praw.objects.Comment(reddit_session, json_dict)

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

A class that represents a reddit comments.

Construct an instance of the Comment object.

is_root

Return True when the comment is a top level comment.

replies

Return a list of the comment replies to this comment.

If the comment is not from a submission, replies() will always be an empty list unless you call refresh() before calling :meth:`replies() due to a limitation in reddit’s API.

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, uniq=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.

Returns:The json response from the server.

edit(text)

Replace the body of the object with text.

Returns:The updated object.

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

Bases: praw.objects.RedditContentObject

Interface for RedditContentObjects that can be gilded.

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

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

gild(months=None)

Gild the Redditor or author of the content.

Parameters:months – Specifies the number of months to gild. This parameter is Only valid when the instance called upon is of type Redditor. When not provided, the value defaults to 1. Returns:True on success, otherwise raises an exception.

class praw.objects.Hideable(reddit_session, json_dict=None, fetch=True, info_url=None, underscore_names=None, uniq=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.

Parameters:_unhide – If True, unhide the item instead. Use unhide() instead of setting this manually. 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, uniq=None)

Bases: praw.objects.RedditContentObject

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

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

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

mark_as_read()

Mark object as read.

Returns:The json response from the server.

mark_as_unread()

Mark object as unread.

Returns:The json response from the server.

reply(text)

Reply to object with the specified text.

Returns:A Comment object for the newly created comment (reply).

class praw.objects.LoggedInRedditor(reddit_session, user_name=None, json_dict=None, fetch=False, **kwargs)

Bases: praw.objects.Redditor

A class representing a currently logged in Redditor.

Construct an instance of the Redditor object.

get_blocked()

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

get_cached_moderated_reddits()

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

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

get_friends(**params)

Return a UserList of Redditors with whom the user is friends.

This method has been moved to praw.AuthenticatedReddit.

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

Return a get_content generator for some RedditContentObject type.

Parameters:

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

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

get_multireddit(*args, **kwargs)

Return a Multireddit object for the author and name specified.

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

get_multireddits(*args, **kwargs)

Return a list of multireddits belonging to a redditor.

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

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

Return a get_content generator for some RedditContentObject type.

Parameters:

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

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

class praw.objects.Message(reddit_session, json_dict)

Bases: praw.objects.Inboxable

A class for private messages.

Construct an instance of the Message object.

collapse()

Collapse a private message or modmail.

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

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

Parameters:

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

The additional parameters are passed directly into request_json().

mute_modmail_author(_unmute=False)

Mute the sender of this modmail message.

Parameters:_unmute – Unmute the user instead. Please use unmute_modmail_author() instead of setting this directly.

uncollapse()

Uncollapse a private message or modmail.

unmute_modmail_author()

Unmute the sender of this modmail message.

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

Bases: praw.objects.RedditContentObject

Interface for RedditContentObjects that can be messaged.

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

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

send_message(*args, **kwargs)

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

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

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

Bases: praw.objects.RedditContentObject

A moderator action.

Construct an instance of the ModAction object.

class praw.objects.Moderatable(reddit_session, json_dict=None, fetch=True, info_url=None, underscore_names=None, uniq=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.

Returns:The json response from the server.

distinguish(as_made_by=u'mod', sticky=False)

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.

sticky argument only used for top-level Comments.

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.

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.

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.

class praw.objects.MoreComments(reddit_session, json_dict)

Bases: praw.objects.RedditContentObject

A class indicating there are more comments.

Construct an instance of the MoreComment object.

comments(update=True)

Fetch and return the comments for a single MoreComments object.

class praw.objects.Multireddit(reddit_session, author=None, name=None, json_dict=None, fetch=False, **kwargs)

Bases: praw.objects.Refreshable

A class for users’ Multireddits.

Construct an instance of the Multireddit object.

add_subreddit(subreddit, _delete=False, *args, **kwargs)

Add a subreddit to the multireddit.

Parameters:subreddit – The subreddit name or Subreddit object to add

The additional parameters are passed directly into request_json().

copy(to_name)

Copy this multireddit.

Convenience function that utilizes MultiredditMixin.copy_multireddit() populating both the from_redditor and from_name parameters.

delete()

Delete this multireddit.

Convenience function that utilizes MultiredditMixin.delete_multireddit() populating the name parameter.

edit(*args, **kwargs)

Edit this multireddit.

Convenience function that utilizes MultiredditMixin.edit_multireddit() populating the name parameter.

classmethod from_api_response(reddit_session, json_dict)

Return an instance of the appropriate class from the json dict.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

remove_subreddit(subreddit, *args, **kwargs)

Remove a subreddit from the user’s multireddit.

rename(new_name, *args, **kwargs)

Rename this multireddit.

This function is a handy shortcut to rename_multireddit() of the reddit_session.

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

Bases: praw.objects.RedditContentObject

An abstract class to coerce a listing into RedditContentObjects.

Construct an instance of the PRAWListing object.

CHILD_ATTRIBUTE = None

class praw.objects.RedditContentObject(reddit_session, json_dict=None, fetch=True, info_url=None, underscore_names=None, uniq=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.

has_fetched

Return whether the object has been fully fetched from reddit.

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

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

A class representing the users of reddit.

Construct an instance of the Redditor object.

friend(note=None, _unfriend=False)

Friend the user.

Parameters:

• note – A personal note about the user. Requires reddit Gold.
• _unfriend – Unfriend the user. Please use unfriend() instead of setting this parameter manually.

Returns:

The json response from the server.

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

Return a get_content generator for some RedditContentObject type.

Parameters:

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

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

get_disliked(*args, **kwargs)

Return a listing of the Submissions the user has downvoted.

This method points to get_downvoted(), as the “disliked” name is being phased out.

get_downvoted(*args, **kwargs)

Return a listing of the Submissions the user has downvoted.

Returns:get_content generator of Submission items.

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

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

get_friend_info()

Return information about this friend, including personal notes.

The personal note can be added or overwritten with :meth:friend, but

only if the user has reddit Gold.

Returns:The json response from the server.

get_liked(*args, **kwargs)

Return a listing of the Submissions the user has upvoted.

This method points to get_upvoted(), as the “liked” name is being phased out.

get_multireddit(*args, **kwargs)

Return a Multireddit object for the author and name specified.

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

get_multireddits(*args, **kwargs)

Return a list of multireddits belonging to a redditor.

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

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

Return a get_content generator for some RedditContentObject type.

Parameters:

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

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

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

Return a get_content generator for some RedditContentObject type.

Parameters:

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

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

get_upvoted(*args, **kwargs)

Return a listing of the Submissions the user has upvoted.

Returns:get_content generator of Submission items.

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

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

mark_as_read(messages, unread=False)

Mark message(s) as read or unread.

Returns:The json response from the server.

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

Bases: praw.objects.RedditContentObject

Interface for objects that can be refreshed.

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

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

refresh()

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

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.

In the rare case of a comment being deleted or removed when it had no replies, a second request will be made, not all information will be updated and a warning will list the attributes that could not be retrieved if there were any.

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

Bases: praw.objects.RedditContentObject

Interface for RedditContentObjects that can be reported.

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

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

report(reason=None)

Report this object to the moderators.

Parameters:reason – The user-supplied reason for reporting a comment or submission. Default: None (blank reason) Returns:The json response from the server.

class praw.objects.Saveable(reddit_session, json_dict=None, fetch=True, info_url=None, underscore_names=None, uniq=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.

Returns:The json response from the server.

unsave()

Unsave the object.

Returns:The json response from the server.

class praw.objects.Submission(reddit_session, json_dict)

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

A class for submissions to reddit.

Construct an instance of the Subreddit object.

add_comment(text)

Comment on the submission using the specified text.

Returns:A Comment object for the newly created comment.

comments

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

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

static from_id(reddit_session, subreddit_id)

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

static from_json(json_response)

Return a submission object from the json response.

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

Request the url and return a Submission object.

Parameters:

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

get_duplicates(*args, **kwargs)

Return a get_content generator for the submission’s duplicates.

Returns:get_content generator iterating over Submission objects.

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

get_flair_choices(*args, **kwargs)

Return available link flair choices and current flair.

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

Returns:The json response from the server.

lock()

Lock thread.

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

Returns:The json response from the server.

mark_as_nsfw(unmark_nsfw=False)

Mark as Not Safe For Work.

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

Returns:The json response from the server.

replace_more_comments(limit=32, threshold=1)

Update the comment tree by replacing instances of MoreComments.

Parameters:

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

Returns:

A list of MoreComments objects that were not replaced.

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

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_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: https://www.reddit.com/159bww/

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.

set_suggested_sort(sort=u'blank')

Set ‘Suggested Sort’ for the comments of the submission.

Comments can be sorted in one of (confidence, top, new, hot, controversial, old, random, qa, blank).

Returns:The json response from the server.

short_link

Return a short link to the submission.

The short link points to a page on the short_domain that redirects to the main. For example http://redd.it/eorhm is a short link for https://www.reddit.com/r/announcements/comments/eorhm/reddit_30_less_typing/.

sticky(bottom=True)

Sticky a post in its subreddit.

If there is already a stickied post in the designated slot it will be unstickied.

Parameters:bottom – Set this as the top or bottom sticky. If no top sticky exists, this submission will become the top sticky regardless. Returns:The json response from the server

unlock()

Lock thread.

Requires that the currently authenticated user has the modposts oauth scope or has 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/159bww/

Returns:The json response from the server.

unsticky()

Unsticky this post.

Returns:The json response from the server

class praw.objects.Subreddit(reddit_session, subreddit_name=None, json_dict=None, fetch=False, **kwargs)

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

A class for Subreddits.

Construct an instance of the Subreddit object.

accept_moderator_invite(*args, **kwargs)

Accept a moderator invite to the given subreddit.

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

add_ban(thing, user, **kwargs)

add_contributor(thing, user, **kwargs)

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)

add_mute(thing, user, **kwargs)

add_wiki_ban(thing, user, **kwargs)

add_wiki_contributor(thing, user, **kwargs)

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.

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.

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.

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.

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.

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.

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.

get_edited(*args, **kwargs)

Return a get_content generator of edited items.

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

get_flair(*args, **kwargs)

Return the flair for a user on the given subreddit.

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

get_flair_choices(*args, **kwargs)

Return available flair choices and current flair.

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

get_flair_list(*args, **kwargs)

Return a get_content generator of flair mappings.

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

get_hot(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

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

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

Return a get_content generator for modmail-muted users.

See ModOnlyMixin.get_muted() 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.

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

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.

get_rules(*args, **kwargs)

Return the json dictionary containing rules for a subreddit.

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

get_settings(*args, **kwargs)

Return the settings for the given subreddit.

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

get_spam(*args, **kwargs)

Return a get_content generator of spam-filtered items.

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

get_sticky(*args, **kwargs)

Return a Submission object for the sticky of the subreddit.

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

get_stylesheet(*args, **kwargs)

Return the stylesheet and images for the given subreddit.

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

get_top(*args, **kwargs)

Return a get_content generator for some RedditContentObject type.

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

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.

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.

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.

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.

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.

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.

get_traffic(*args, **kwargs)

Return the json dictionary containing traffic stats for a subreddit.

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

get_unmoderated(*args, **kwargs)

Return a get_content generator of unmoderated submissions.

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.

leave_contributor(*args, **kwargs)

Abdicate approved submitter status in a subreddit. Use with care.

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

leave_moderator(*args, **kwargs)

Abdicate moderator status in a subreddit. Use with care.

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

remove_ban(thing, user, **kwargs)

remove_contributor(thing, user, **kwargs)

remove_moderator(thing, user, **kwargs)

remove_mute(thing, user, **kwargs)

remove_wiki_ban(thing, user, **kwargs)

remove_wiki_contributor(thing, user, **kwargs)

search(*args, **kwargs)

Return a generator for submissions that match the search query.

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

select_flair(*args, **kwargs)

Select user flair or link flair on subreddits.

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

set_flair(*args, **kwargs)

Set flair for the user in the given subreddit.

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

set_flair_csv(*args, **kwargs)

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

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

set_settings(*args, **kwargs)

Set the settings for the given subreddit.

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

set_stylesheet(*args, **kwargs)

Set stylesheet for the given subreddit.

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

submit(*args, **kwargs)

Submit a new link to the given subreddit.

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

subscribe(*args, **kwargs)

Subscribe to the given subreddit.

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

unsubscribe(*args, **kwargs)

Unsubscribe from the given subreddit.

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

update_settings(*args, **kwargs)

Update only the given settings for the given subreddit.

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

upload_image(*args, **kwargs)

Upload an image to the subreddit.

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

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

Bases: praw.objects.PRAWListing

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

Construct an instance of the PRAWListing object.

CHILD_ATTRIBUTE = u'children'

class praw.objects.Voteable(reddit_session, json_dict=None, fetch=True, info_url=None, underscore_names=None, uniq=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

Returns:The json response from the server.

class praw.objects.WikiPage(reddit_session, subreddit=None, page=None, json_dict=None, fetch=False, **kwargs)

Bases: praw.objects.Refreshable

An individual WikiPage object.

Construct an instance of the WikiPage object.

add_editor(username, _delete=False, *args, **kwargs)

Add an editor to this wiki page.

Parameters:

• username – The name or Redditor object of the user to add.
• _delete – If True, remove the user as an editor instead. Please use remove_editor() rather than setting it manually.

Additional parameters are passed into request_json().

edit(*args, **kwargs)

Edit the wiki page.

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

edit_settings(permlevel, listed, *args, **kwargs)

Edit the settings for this individual wiki page.

Parameters:

• permlevel – Who can edit this page? (0) use subreddit wiki permissions, (1) only approved wiki contributors for this page may edit (see add_editor()), (2) only mods may edit and view
• listed – Show this page on the listing? True - Appear in /wiki/pages False - Do not appear in /wiki/pages

Returns:

The updated settings data.

Additional parameters are passed into request_json().

classmethod from_api_response(reddit_session, json_dict)

Return an instance of the appropriate class from the json_dict.

get_settings(*args, **kwargs)

Return the settings for this wiki page.

Includes permission level, names of editors, and whether the page is listed on /wiki/pages.

Additional parameters are passed into request_json()

remove_editor(username, *args, **kwargs)

Remove an editor from this wiki page.

Parameters:username – The name or Redditor object of the user to remove.

This method points to add_editor() with _delete=True.

Additional parameters are are passed to add_editor() and subsequently into request_json().

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

Bases: praw.objects.PRAWListing

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

Construct an instance of the PRAWListing object.

CHILD_ATTRIBUTE = u'_tmp'

helpers Module

Helper functions.

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

class praw.helpers.BoundedSet(max_items)

Bases: object

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

This class does not implement the complete set interface.

Construct an instance of the BoundedSet.

add(item)

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

praw.helpers.chunk_sequence(sequence, chunk_length, allow_incomplete=True)

Given a sequence, divide it into sequences of length chunk_length.

Parameters:allow_incomplete – If True, allow final chunk to be shorter if the given sequence is not an exact multiple of chunk_length. If False, the incomplete chunk will be discarded.

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

Indefinitely yield new comments from the provided subreddit.

Comments are yielded from oldest to newest.

Parameters:

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

praw.helpers.convert_id36_to_numeric_id(id36)

Convert strings representing base36 numbers into an integer.

praw.helpers.convert_numeric_id_to_id36(numeric_id)

Convert an integer into its base36 string representation.

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

https://github.com/reddit/reddit/blob/master/r2/r2/lib/utils/_utils.pyx

https://www.reddit.com/r/redditdev/comments/n624n/submission_ids_question/

https://en.wikipedia.org/wiki/Base36

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

Return a flattened version of the passed in tree.

Parameters:

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

praw.helpers.normalize_url(url)

Return url after stripping trailing .json and trailing slashes.

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

Indefinitely yield new submissions from the provided subreddit.

Submissions are yielded from oldest to newest.

Parameters:

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

praw.helpers.submissions_between(reddit_session, subreddit, lowest_timestamp=None, highest_timestamp=None, newest_first=True, extra_cloudsearch_fields=None, verbosity=1)

Yield submissions between two timestamps.

If both highest_timestamp and lowest_timestamp are unspecified, yields all submissions in the subreddit.

Submissions are yielded from newest to oldest(like in the “new” queue).

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.
• lowest_timestamp – The lower bound for created_utc atributed of submissions. (Default: subreddit’s created_utc or 0 when subreddit == “all”).
• highest_timestamp – The upper bound for created_utc attribute of submissions. (Default: current unix time) NOTE: both highest_timestamp and lowest_timestamp are proper unix timestamps(just like created_utc attributes)
• newest_first – If set to true, yields submissions from newest to oldest. Otherwise yields submissions from oldest to newest
• extra_cloudsearch_fields – Allows extra filtering of results by parameters like author, self. Full list is available here: https://www.reddit.com/wiki/search
• verbosity – A number that controls the amount of output produced to stderr. <= 0: no output; >= 1: output the total number of submissions processed; >= 2: output debugging information regarding the search queries. (Default: 1)

praw.helpers.valid_redditors(redditors, sub)

Return a verified list of valid Redditor instances.

Parameters:

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

Note: Flair will be unset for all valid redditors in redditors on the subreddit sub. A valid redditor is defined as a redditor that is registered on reddit.

errors Module

Error classes.

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

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

Bases: praw.errors.PRAWException

Base exception class for the reddit API error message exceptions.

All exceptions of this type should have their own subclass.

Construct an APIException.

Parameters:

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

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

Bases: praw.errors.APIException

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

Construct an APIException.

Parameters:

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

ERROR_TYPE = u'ALREADY_MODERATOR'

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

Bases: praw.errors.APIException

An exception to indicate that a URL was previously submitted.

Construct an APIException.

Parameters:

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

ERROR_TYPE = u'ALREADY_SUB'

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

Bases: praw.errors.APIException

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

Construct an APIException.

Parameters:

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

ERROR_TYPE = u'BAD_CSS'

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

Bases: praw.errors.APIException

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

Construct an APIException.

Parameters:

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

ERROR_TYPE = u'BAD_CSS_NAME'

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

Bases: praw.errors.APIException

An exception to indicate an invalid username was used.

Construct an APIException.

Parameters:

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

ERROR_TYPE = u'BAD_USERNAME'

exception praw.errors.ClientException(message=None)

Bases: praw.errors.PRAWException

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

Construct a ClientException.

Parameters:message – The error message to display.

exception praw.errors.ExceptionList(errors)

Bases: praw.errors.APIException

Raised when more than one exception occurred.

Construct an ExceptionList.

Parameters:errors – The list of errors.

exception praw.errors.Forbidden(_raw, message=None)

Bases: praw.errors.HTTPException

Raised when the user does not have permission to the entity.

Construct a HTTPException.

Params _raw:The internal request library response object. This object is mapped to attribute _raw whose format may change at any time.

exception praw.errors.HTTPException(_raw, message=None)

Bases: praw.errors.PRAWException

Base class for HTTP related exceptions.

Construct a HTTPException.

Params _raw:The internal request library response object. This object is mapped to attribute _raw whose format may change at any time.

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

Bases: praw.errors.APIException

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

Construct an APIException.

Parameters:

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

ERROR_TYPE = u'INSUFFICIENT_CREDDITS'

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

Bases: praw.errors.APIException

An exception for when an incorrect captcha error is returned.

Construct an APIException.

Parameters:

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

ERROR_TYPE = u'BAD_CAPTCHA'

exception praw.errors.InvalidComment

Bases: praw.errors.PRAWException

Indicate that the comment is no longer available on reddit.

ERROR_TYPE = u'DELETED_COMMENT'

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

Bases: praw.errors.APIException

An exception for when invalid emails are provided.

Construct an APIException.

Parameters:

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

ERROR_TYPE = u'BAD_EMAILS'

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

Bases: praw.errors.APIException

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

Construct an APIException.

Parameters:

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

ERROR_TYPE = u'BAD_FLAIR_TARGET'

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

Bases: praw.errors.APIException

Raised when attempting to accept a nonexistent moderator invite.

Construct an APIException.

Parameters:

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

ERROR_TYPE = u'NO_INVITE_FOUND'

exception praw.errors.InvalidSubmission

Bases: praw.errors.PRAWException

Indicates that the submission is no longer available on reddit.

ERROR_TYPE = u'DELETED_LINK'

exception praw.errors.InvalidSubreddit

Bases: praw.errors.PRAWException

Indicates that an invalid subreddit name was supplied.

ERROR_TYPE = u'SUBREDDIT_NOEXIST'

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

Bases: praw.errors.APIException

An exception for when a user doesn’t exist.

Construct an APIException.

Parameters:

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

ERROR_TYPE = u'USER_DOESNT_EXIST'

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

Bases: praw.errors.APIException

An exception for failed logins.

Construct an APIException.

Parameters:

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

ERROR_TYPE = u'WRONG_PASSWORD'

exception praw.errors.LoginOrScopeRequired(function, scope, message=None)

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

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

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

Construct a LoginOrScopeRequired exception.

Parameters:

• function – The function that requires authentication.
• scope – The scope that is required if not logged in.
• message – A custom message to associate with the exception. Default: function requires a logged in session or the OAuth2 scope scope

exception praw.errors.LoginRequired(function, message=None)

Bases: praw.errors.ClientException

Indicates that a logged in session is required.

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

Construct a LoginRequired exception.

Parameters:

• function – The function that requires login-based authentication.
• message – A custom message to associate with the exception. Default: function requires a logged in session

exception praw.errors.ModeratorOrScopeRequired(function, scope)

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

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

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

Construct a ModeratorOrScopeRequired exception.

Parameters:

• function – The function that requires moderator authentication or a moderator scope..
• scope – The scope that is required if not logged in with moderator access..

exception praw.errors.ModeratorRequired(function)

Bases: praw.errors.LoginRequired

Indicates that a moderator of the subreddit is required.

Construct a ModeratorRequired exception.

Parameters:function – The function that requires moderator access.

exception praw.errors.NotFound(_raw, message=None)

Bases: praw.errors.HTTPException

Raised when the requested entity is not found.

Construct a HTTPException.

Params _raw:The internal request library response object. This object is mapped to attribute _raw whose format may change at any time.

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

Bases: praw.errors.APIException

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

Construct an APIException.

Parameters:

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

ERROR_TYPE = u'USER_REQUIRED'

exception praw.errors.NotModified(response)

Bases: praw.errors.APIException

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

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

Construct an instance of the NotModified exception.

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

exception praw.errors.OAuthAppRequired(message=None)

Bases: praw.errors.ClientException

Raised when an OAuth client cannot be initialized.

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

Construct a ClientException.

Parameters:message – The error message to display.

exception praw.errors.OAuthException(message, url)

Bases: praw.errors.PRAWException

Base exception class for OAuth API calls.

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

Construct a OAuthException.

Parameters:

• message – The message associated with the exception.
• url – The url that resulted in error.

exception praw.errors.OAuthInsufficientScope(message, url)

Bases: praw.errors.OAuthException

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

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

Construct a OAuthException.

Parameters:

• message – The message associated with the exception.
• url – The url that resulted in error.

exception praw.errors.OAuthInvalidGrant(message, url)

Bases: praw.errors.OAuthException

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

Construct a OAuthException.

Parameters:

• message – The message associated with the exception.
• url – The url that resulted in error.

exception praw.errors.OAuthInvalidToken(message, url)

Bases: praw.errors.OAuthException

Raised when the current OAuth access token is not valid.

Construct a OAuthException.

Parameters:

• message – The message associated with the exception.
• url – The url that resulted in error.

exception praw.errors.OAuthScopeRequired(function, scope, message=None)

Bases: praw.errors.ClientException

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

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

Contruct an OAuthScopeRequiredClientException.

Parameters:

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

exception praw.errors.PRAWException

Bases: exceptions.Exception

The base PRAW Exception class.

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

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

Bases: praw.errors.APIException

An exception for when something has happened too frequently.

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

Construct an instance of the RateLimitExceeded exception.

The parameters match that of APIException.

The sleep_time attribute is extracted from the response object.

ERROR_TYPE = u'RATELIMIT'

exception praw.errors.RedirectException(request_url, response_url, message=None)

Bases: praw.errors.PRAWException

Raised when a redirect response occurs that is not expected.

Construct a RedirectException.

Parameters:

• request_url – The url requested.
• response_url – The url being redirected to.
• message – A custom message to associate with the exception.

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

Bases: praw.errors.APIException

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

Construct an APIException.

Parameters:

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

ERROR_TYPE = u'SUBREDDIT_EXISTS'

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

Bases: praw.errors.APIException

An exception to indicate that a username is not available.

Construct an APIException.

Parameters:

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

ERROR_TYPE = u'USERNAME_TAKEN'

handlers Module

Provides classes that handle request dispatching.

class praw.handlers.DefaultHandler

Bases: praw.handlers.RateLimitHandler

Extends the RateLimitHandler to add thread-safe caching support.

Establish the HTTP session.

ca_lock = <thread.lock object>

cache = {}

cache_hit_callback = None

classmethod clear_cache()

Remove all items from the cache.

classmethod evict(urls)

Remove items from cache matching URLs.

Return the number of items removed.

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

Responsible for dispatching the request and returning the result.

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

Parameters:

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

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

timeouts = {}

static with_cache(function)

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

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

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

Bases: object

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

Construct an instance of the MultiprocessHandler.

evict(urls)

Forward the eviction to the server and return its response.

request(**kwargs)

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

class praw.handlers.RateLimitHandler

Bases: object

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

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

Establish the HTTP session.

classmethod evict(urls)

Method utilized to evict entries for the given urls.

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

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

last_call = {}

static rate_limit(function)

Return a decorator that enforces API request limit guidelines.

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

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

request(_rate_domain, _rate_delay, **kwargs)

Responsible for dispatching the request and returning the result.

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

Parameters:

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

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

rl_lock = <thread.lock object>

decorators Module

Decorators.

They mainly do two things: ensure API guidelines are followed and prevent unnecessary failed API requests by testing that the call can be made first. Also, they can limit the length of output strings and parse json response for certain errors.

praw.decorators.alias_function(function, class_name)

Create a RedditContentObject function mapped to a BaseReddit function.

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

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

Deprecate decorated method.

praw.decorators.limit_chars(func)

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

praw.decorators.oauth_generator(func)

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

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

Returned data is not modified.

praw.decorators.require_captcha(func)

Return a decorator for methods that require captchas.

praw.decorators.require_oauth(func)

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, generator_called=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.
• generator_called – Indicate that the function consists solely of exhausting one or more oauth_generator wrapped generators. This is because the oauth_generator itself will determine whether or not to use the oauth domain.

Returned data is not modified.

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

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