
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_fil
   es.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/_util
   s.pyx

   https://www.reddit.com/r/redditdev/comments/n624n/submission_ids_q
   uestion/

   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
