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)

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

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

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

   submissions(start=None, end=None, extra_query=None)

      Yield submissions created between timestamps "start" and "end".

      Parameters:
         * **start** – A UNIX timestamp indicating the earliest
           creation time of submission yielded during the call. A
           value of "None" will consider all submissions older than
           "end" (default: None).

         * **end** – A UNIX timestamp indicating the latest creation
           time of a submission yielded during the call. A value of
           "None" will consider all submissions newer than "start"
           (default: None).

         * **extra_query** – A cloudsearch query that will be
           combined via "(and timestamp:start..end EXTRA_QUERY)" to
           further filter results (default: None).

      Submissions are yielded newest first.

      **Example**: Suppose you want to obtain all submissions to
      "/r/politics" on November 8, 2016 PST. First, you need to
      determine the start and end dates as UNIX timestamps. Using
      http://www.epochconverter.com/, those timestamps are 1478592000
      and 1478678400, respectively. The following outputs all such
      submissions’ titles:

         subreddit = reddit.subreddit('politics')
         for submission in subreddit.submissions(1478592000, 1478678400):
             print(submission.title)

      As of this writing there are 809 results.

      Note: The results are only as reliable as reddit’s search.
        Submissions may be missing from the results.

   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)

   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.

   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)
