# 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.org/en/latest/pages/configuration_files.html for more details.

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

    Evict url(s) from the cache.

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

  `get_content`(url, params=None, limit=0, place_holder=None, root_field=u'data', thing_field=u'children', after_field=u'after', 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.

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

    Return the short domain of the reddit 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, **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 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.

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

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

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

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

    Parameters:

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

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

  `get_moderators`(subreddit, **kwargs)

    Return the list of moderators for the given subreddit.

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

  `permalink`

    Return a permalink to the 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 :class:`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()`.

  `uncollapse`()

    Uncollapse a private message or modmail.

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

    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.

    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 submissions’s comment[0] being deleted or removed in between its original retrieval and refresh, or inconsistencies between different endpoints resulting in this, an IndexError will be thrown.

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.

  `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

  `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_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_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_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_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_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.``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.``valid_redditors`(redditors, sub)

  Return a verified list of valid Redditor instances.

  Parameters:

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

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

## `errors` Module

Error classes.

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

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

  Bases: `praw.errors.PRAWException`

  Base exception class for the reddit API error message exceptions.

  All exceptions of this type should have their own subclass.

  Construct an APIException.

  Parameters:

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

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

  Bases: `praw.errors.APIException`

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

  Construct an APIException.

  Parameters:

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

  `ERROR_TYPE` = u'ALREADY_MODERATOR'

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

  Bases: `praw.errors.APIException`

  An exception to indicate that a URL was previously submitted.

  Construct an APIException.

  Parameters:

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

  `ERROR_TYPE` = u'ALREADY_SUB'

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

  Bases: `praw.errors.APIException`

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

  Construct an APIException.

  Parameters:

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

  `ERROR_TYPE` = u'BAD_CSS'

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

  Bases: `praw.errors.APIException`

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

  Construct an APIException.

  Parameters:

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

  `ERROR_TYPE` = u'BAD_CSS_NAME'

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

  Bases: `praw.errors.APIException`

  An exception to indicate an invalid username was used.

  Construct an APIException.

  Parameters:

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

  `ERROR_TYPE` = u'BAD_USERNAME'

exception `praw.errors.``ClientException`(message=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`(function)

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

`praw.decorators.``oauth_generator`(function)

  Set the _use_oauth keyword argument to True when appropriate.

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

  Returned data is not modified.

`praw.decorators.``raise_api_exceptions`(function)

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

  Returned data is not modified.

`praw.decorators.``require_captcha`(function)

  Return a decorator for methods that require captchas.

`praw.decorators.``require_oauth`(function)

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

  Returned data is not modified.

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

  Restrict function access unless the user has the necessary permissions.

  Raises one of the following exceptions when appropriate:
    - LoginRequired
    - LoginOrOAuthRequired * the scope attribute will provide the necessary scope name
    - ModeratorRequired
    - ModeratorOrOAuthRequired * the scope attribute will provide the necessary scope name

  Parameters:

  - scope – Indicate the scope that is required for the API call. None or False must be passed to indicate that no scope handles the API call. All scopes save for read imply login=True. Scopes with ‘mod’ in their name imply mod=True.
  - mod – Indicate that a moderator is required. Implies login=True.
  - login – Indicate that a login is required.
  - oauth_only – Indicate that only OAuth is supported for the function.

  Returned data is not modified.

  This decorator assumes that all mod required functions fit one of 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