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)