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