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)