Subreddit
*********

class praw.models.Subreddit(reddit, display_name=None, _data=None)

   A class for Subreddits.

   To obtain an instance of this class for subreddit "/r/redditdev"
   execute:

      subreddit = reddit.subreddit('redditdev')

   While "/r/all" is not a real subreddit, it can still be treated
   like one. The following outputs the titles of the 25 hottest
   submissions in "/r/all":

      for submission in reddit.subreddit('all').hot(limit=25):
          print(submission.title)

   Multiple subreddits can be combined like so:

      for submission in reddit.subreddit('redditdev+learnpython').top('all'):
          print(submission)

   Subreddits can be filtered from combined listings as follows. Note
   that these filters are ignored by certain methods, including
   "comments", "gilded()", and "SubredditStream.comments()".

      for submission in reddit.subreddit('all-redditdev').new():
          print(submission)

   **Typical Attributes**

   This table describes attributes that typically belong to objects of
   this class. Since attributes are dynamically provided (see
   Determine Available Attributes of an Object), there is not a
   guarantee that these attributes will always be present, nor is this
   list comprehensive in any way.

   +-------------------------+-----------------------------------------------------+
   | Attribute               | Description                                         |
   +=========================+=====================================================+
   | "created_utc"           | Time the subreddit was created, represented in Unix |
   |                         | Time.                                               |
   +-------------------------+-----------------------------------------------------+
   | "description"           | Subreddit description, in Markdown.                 |
   +-------------------------+-----------------------------------------------------+
   | "description_html"      | Subreddit description, in HTML.                     |
   +-------------------------+-----------------------------------------------------+
   | "display_name"          | Name of the subreddit.                              |
   +-------------------------+-----------------------------------------------------+
   | "over18"                | Whether or not the subreddit is NSFW.               |
   +-------------------------+-----------------------------------------------------+
   | "public_description"    | Description of the subreddit, shown in searches and |
   |                         | on the "You must be invited to visit this           |
   |                         | community" page (if applicable).                    |
   +-------------------------+-----------------------------------------------------+
   | "subscribers"           | Count of subscribers to the subreddit.              |
   +-------------------------+-----------------------------------------------------+

   __init__(reddit, display_name=None, _data=None)

      Initialize a Subreddit instance.

      Parameters:
         * **reddit** -- An instance of "Reddit".

         * **display_name** -- The name of the subreddit.

      Note: This class should not be initialized directly. Instead
        obtain an instance via: "reddit.subreddit('subreddit_name')"

   banned

      Provide an instance of "SubredditRelationship".

      For example to ban a user try:

         reddit.subreddit('SUBREDDIT').banned.add('NAME', ban_reason='...')

      To list the banned users along with any notes, try:

         for ban in reddit.subreddit('SUBREDDIT').banned():
             print('{}: {}'.format(ban, ban.note))

   comments

      Provide an instance of "CommentHelper".

      For example, to output the author of the 25 most recent comments
      of "/r/redditdev" execute:

         for comment in reddit.subreddit('redditdev').comments(limit=25):
             print(comment.author)

   contributor

      Provide an instance of "ContributorRelationship".

      Contributors are also known as approved submitters.

      To add a contributor try:

         reddit.subreddit('SUBREDDIT').contributor.add('NAME')

   controversial(time_filter='all', **generator_kwargs)

      Return a ListingGenerator for controversial submissions.

      Parameters:
         **time_filter** -- Can be one of: all, day, hour, month,
         week, year (default: all).

      Raise "ValueError" if "time_filter" is invalid.

      Additional keyword arguments are passed in the initialization of
      "ListingGenerator".

      This method can be used like:

         reddit.domain('imgur.com').controversial('week')
         reddit.multireddit('samuraisam', 'programming').controversial('day')
         reddit.redditor('spez').controversial('month')
         reddit.redditor('spez').comments.controversial('year')
         reddit.redditor('spez').submissions.controversial('all')
         reddit.subreddit('all').controversial('hour')

   emoji

      Provide an instance of "SubredditEmoji".

      This attribute can be used to discover all emoji for a
      subreddit:

         for emoji in reddit.subreddit('iama').emoji:
             print(emoji)

      A single emoji can be lazily retrieved via:

         reddit.subreddit('blah').emoji['emoji_name']

      Note: Attempting to access attributes of an nonexistent emoji
        will result in a "ClientException".

   filters

      Provide an instance of "SubredditFilters".

   flair

      Provide an instance of "SubredditFlair".

      Use this attribute for interacting with a subreddit's flair. For
      example to list all the flair for a subreddit which you have the
      "flair" moderator permission on try:

         for flair in reddit.subreddit('NAME').flair():
             print(flair)

      Flair templates can be interacted with through this attribute
      via:

         for template in reddit.subreddit('NAME').flair.templates:
             print(template)

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

   gilded(**generator_kwargs)

      Return a ListingGenerator for gilded items.

      Additional keyword arguments are passed in the initialization of
      "ListingGenerator".

   hot(**generator_kwargs)

      Return a ListingGenerator for hot items.

      Additional keyword arguments are passed in the initialization of
      "ListingGenerator".

      This method can be used like:

         reddit.domain('imgur.com').hot()
         reddit.multireddit('samuraisam', 'programming').hot()
         reddit.redditor('spez').hot()
         reddit.redditor('spez').comments.hot()
         reddit.redditor('spez').submissions.hot()
         reddit.subreddit('all').hot()

   message(subject, message, from_subreddit=None)

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

      Parameters:
         * **subject** -- The subject of the message.

         * **message** -- The message content.

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

      For example, to send a private message to "/u/spez", try:

         reddit.redditor('spez').message('TEST', 'test message from PRAW')

      To send a message to "u/spez" from the moderators of "r/test"
      try:

         reddit.redditor('spez').message('TEST', 'test message from r/test',
                                         from_subreddit='test')

      To send a message to the moderators of "/r/test", try:

         reddit.subreddit('test').message('TEST', 'test PM from PRAW')

   mod

      Provide an instance of "SubredditModeration".

   moderator

      Provide an instance of "ModeratorRelationship".

      For example to add a moderator try:

         reddit.subreddit('SUBREDDIT').moderator.add('NAME')

      To list the moderators along with their permissions try:

         for moderator in reddit.subreddit('SUBREDDIT').moderator():
             print('{}: {}'.format(moderator, moderator.mod_permissions))

   modmail

      Provide an instance of "Modmail".

   muted

      Provide an instance of "SubredditRelationship".

   new(**generator_kwargs)

      Return a ListingGenerator for new items.

      Additional keyword arguments are passed in the initialization of
      "ListingGenerator".

      This method can be used like:

         reddit.domain('imgur.com').new()
         reddit.multireddit('samuraisam', 'programming').new()
         reddit.redditor('spez').new()
         reddit.redditor('spez').comments.new()
         reddit.redditor('spez').submissions.new()
         reddit.subreddit('all').new()

   classmethod parse(data, reddit)

      Return an instance of "cls" from "data".

      Parameters:
         * **data** -- The structured data.

         * **reddit** -- An instance of "Reddit".

   quaran

      Provide an instance of "SubredditQuarantine".

      This property is named "quaran" because "quarantine" is a
      Subreddit attribute returned by Reddit to indicate whether or
      not a Subreddit is quarantined.

   random()

      Return a random Submission.

   random_rising(**generator_kwargs)

      Return a ListingGenerator for random rising submissions.

      Additional keyword arguments are passed in the initialization of
      "ListingGenerator".

   rising(**generator_kwargs)

      Return a ListingGenerator for rising submissions.

      Additional keyword arguments are passed in the initialization of
      "ListingGenerator".

   rules()

      Return rules for the subreddit.

      For example to show the rules of "/r/redditdev" try:

         reddit.subreddit('redditdev').rules()

   search(query, sort='relevance', syntax='lucene', time_filter='all', **generator_kwargs)

      Return a ListingGenerator for items that match "query".

      Parameters:
         * **query** -- The query string to search for.

         * **sort** -- Can be one of: relevance, hot, top, new,
           comments. (default: relevance).

         * **syntax** -- Can be one of: cloudsearch, lucene, plain
           (default: lucene).

         * **time_filter** -- Can be one of: all, day, hour, month,
           week, year (default: all).

      For more information on building a search query see:
         https://www.reddit.com/wiki/search

      For example to search all subreddits for "praw" try:

         for submission in reddit.subreddit('all').search('praw'):
             print(submission.title)

   sticky(number=1)

      Return a Submission object for a sticky of the subreddit.

      Parameters:
         **number** -- Specify which sticky to return. 1 appears at
         the top (default: 1).

      Raises "prawcore.NotFound" if the sticky does not exist.

   stream

      Provide an instance of "SubredditStream".

      Streams can be used to indefinitely retrieve new comments made
      to a subreddit, like:

         for comment in reddit.subreddit('iama').stream.comments():
             print(comment)

      Additionally, new submissions can be retrieved via the stream.
      In the following example all submissions are fetched via the
      special subreddit "all":

         for submission in reddit.subreddit('all').stream.submissions():
             print(submission)

   stylesheet

      Provide an instance of "SubredditStylesheet".

   submit(title, selftext=None, url=None, flair_id=None, flair_text=None, resubmit=True, send_replies=True)

      Add a submission to the subreddit.

      Parameters:
         * **title** -- The title of the submission.

         * **selftext** -- The markdown formatted content for a
           "text" submission. Use an empty string, "''", to make a
           title-only submission.

         * **url** -- The URL for a "link" submission.

         * **flair_id** -- The flair template to select (default:
           None).

         * **flair_text** -- If the template's "flair_text_editable"
           value is True, this value will set a custom text (default:
           None).

         * **resubmit** -- When False, an error will occur if the
           URL has already been submitted (default: True).

         * **send_replies** -- When True, messages will be sent to
           the submission author when comments are made to the
           submission (default: True).

      Returns:
         A "Submission" object for the newly created submission.

      Either "selftext" or "url" can be provided, but not both.

      For example to submit a URL to "/r/reddit_api_test" do:

         title = 'PRAW documentation'
         url = 'https://praw.readthedocs.io'
         reddit.subreddit('reddit_api_test').submit(title, url=url)

      Note: For submitting images, videos, and videogifs, see
        "submit_image()" and "submit_video()".

   submit_image(title, image_path, flair_id=None, flair_text=None, resubmit=True, send_replies=True)

      Add an image submission to the subreddit.

      Parameters:
         * **title** -- The title of the submission.

         * **image_path** -- The path to an image, to upload and
           post.

         * **flair_id** -- The flair template to select (default:
           None).

         * **flair_text** -- If the template's "flair_text_editable"
           value is True, this value will set a custom text (default:
           None).

         * **resubmit** -- When False, an error will occur if the
           URL has already been submitted (default: True).

         * **send_replies** -- When True, messages will be sent to
           the submission author when comments are made to the
           submission (default: True).

      Note: Reddit's API uses WebSockets to respond with the link of
        the newly created post. If this fails, the method will raise
        "ClientException". Occasionally, the Reddit post will still be
        created. More often, there is an error with the image file.

      Returns:
         A "Submission" object for the newly created submission.

      For example to submit an image to "/r/reddit_api_test" do:

         title = 'My favorite picture'
         image = '/path/to/image.png'
         reddit.subreddit('reddit_api_test').submit_image(title, image)

   submit_video(title, video_path, videogif=False, thumbnail_path=None, flair_id=None, flair_text=None, resubmit=True, send_replies=True)

      Add a video or videogif submission to the subreddit.

      Parameters:
         * **title** -- The title of the submission.

         * **video_path** -- The path to a video, to upload and
           post.

         * **videogif** -- A "bool" value. If "True", the video is
           uploaded as a videogif, which is essentially a silent video
           ( default: "False").

         * **thumbnail_path** -- (Optional) The path to an image, to
           be uploaded and used as the thumbnail for this video. If
           not provided, the PRAW logo will be used as the thumbnail.

         * **flair_id** -- The flair template to select (default:
           "None").

         * **flair_text** -- If the template's "flair_text_editable"
           value is True, this value will set a custom text (default:
           "None").

         * **resubmit** -- When False, an error will occur if the
           URL has already been submitted (default: "True").

         * **send_replies** -- When True, messages will be sent to
           the submission author when comments are made to the
           submission (default: "True").

      Note: Reddit's API uses WebSockets to respond with the link of
        the newly created post. If this fails, the method will raise
        "ClientException". Occasionally, the Reddit post will still be
        created. More often, there is an error with the video file.

      Returns:
         A "Submission" object for the newly created submission.

      For example to submit a video to "/r/reddit_api_test" do:

         title = 'My favorite movie'
         video = '/path/to/video.mp4'
         reddit.subreddit('reddit_api_test').submit_video(title, video)

   subscribe(other_subreddits=None)

      Subscribe to the subreddit.

      Parameters:
         **other_subreddits** -- When provided, also subscribe to the
         provided list of subreddits.

   top(time_filter='all', **generator_kwargs)

      Return a ListingGenerator for top submissions.

      Parameters:
         **time_filter** -- Can be one of: all, day, hour, month,
         week, year (default: all).

      Raise "ValueError" if "time_filter" is invalid.

      Additional keyword arguments are passed in the initialization of
      "ListingGenerator".

      This method can be used like:

         reddit.domain('imgur.com').top('week')
         reddit.multireddit('samuraisam', 'programming').top('day')
         reddit.redditor('spez').top('month')
         reddit.redditor('spez').comments.top('year')
         reddit.redditor('spez').submissions.top('all')
         reddit.subreddit('all').top('hour')

   traffic()

      Return a dictionary of the subreddit's traffic statistics.

      Raises "prawcore.NotFound" when the traffic stats aren't
      available to the authenticated user, that is, they are not
      public and the authenticated user is not a moderator of the
      subreddit.

   unsubscribe(other_subreddits=None)

      Unsubscribe from the subreddit.

      Parameters:
         **other_subreddits** -- When provided, also unsubscribe to
         the provided list of subreddits.

   widgets

      Provide an instance of "SubredditWidgets".

      **Example usage**

      Get all sidebar widgets:

         for widget in reddit.subreddit('redditdev').widgets.sidebar:
             print(widget)

      Get ID card widget:

         print(reddit.subreddit('redditdev').widgets.id_card)

   wiki

      Provide an instance of "SubredditWiki".

      This attribute can be used to discover all wikipages for a
      subreddit:

         for wikipage in reddit.subreddit('iama').wiki:
             print(wikipage)

      To fetch the content for a given wikipage try:

         wikipage = reddit.subreddit('iama').wiki['proof']
         print(wikipage.content_md)
