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 inr/all
:for submission in reddit.subreddit('all').hot(limit=25): print(submission.title)
Multiple subreddits can be combined with a
+
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()
, andSubredditStream.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 can_assign_link_flair
Whether users can assign their own link flair. can_assign_user_flair
Whether users can assign their own user flair. 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. id
ID of the subreddit. name
Fullname of the subreddit. over18
Whether 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). spoilers_enabled
Whether the spoiler tag feature is enabled. subscribers
Count of subscribers. user_is_banned
Whether the authenticated user is banned. user_is_moderator
Whether the authenticated user is a moderator. user_is_subscriber
Whether the authenticated user is subscribed. -
__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')
- reddit – An instance of
-
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))
-
collections
¶ Provide an instance of
SubredditCollections
.To see the permalinks of all
Collection
s that belong to a subreddit, try:for collection in reddit.subreddit('SUBREDDIT').collections: print(collection.permalink)
To get a specific
Collection
by its UUID or permalink, use one of the following:collection = reddit.subreddit('SUBREDDIT').collections('some_uuid') collection = reddit.subreddit('SUBREDDIT').collections( permalink='https://reddit.com/r/SUBREDDIT/collection/some_uuid')
-
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: str = 'all', **generator_kwargs) → Generator[[Any, None], None]¶ Return a
ListingGenerator
for controversial submissions.Parameters: time_filter – Can be one of: all, day, hour, month, week, year (default: all). Raise
ValueError
iftime_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) → Generator[[Any, None], None]¶ Return a
ListingGenerator
for gilded items.Additional keyword arguments are passed in the initialization of
ListingGenerator
.
-
hot
(**generator_kwargs) → Generator[[Any, None], None]¶ 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 themail
moderator permission.
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 ofr/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))
-
muted
¶ Provide an instance of
SubredditRelationship
.
-
new
(**generator_kwargs) → Generator[[Any, None], None]¶ 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: Dict[str, Any], reddit: Reddit) → Any¶ Return an instance of
cls
fromdata
.Parameters: - data – The structured data.
- reddit – An instance of
Reddit
.
-
quaran
¶ Provide an instance of
SubredditQuarantine
.This property is named
quaran
becausequarantine
is a Subreddit attribute returned by Reddit to indicate whether or not a Subreddit is quarantined.
-
random
()¶ Return a random Submission.
Returns
None
on subreddits that do not support the random feature. One example, at the time of writing, isr/wallpapers
.
-
random_rising
(**generator_kwargs) → Generator[[Submission, None], None]¶ Return a
ListingGenerator
for random rising submissions.Additional keyword arguments are passed in the initialization of
ListingGenerator
.
-
rising
(**generator_kwargs) → Generator[[Submission, None], None]¶ 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 matchquery
.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
r/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, nsfw=False, spoiler=False, collection_id=None)¶ 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. - collection_id – The UUID of a
Collection
to add the newly-submitted post to. - 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).
- nsfw – Whether or not the submission should be marked NSFW (default: False).
- spoiler – Whether or not the submission should be marked as a spoiler (default: False).
Returns: A
Submission
object for the newly created submission.Either
selftext
orurl
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()
andsubmit_video()
.
-
submit_image
(title, image_path, flair_id=None, flair_text=None, resubmit=True, send_replies=True, nsfw=False, spoiler=False, timeout=10, collection_id=None, without_websockets=False)¶ 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.
- collection_id – The UUID of a
Collection
to add the newly-submitted post to. - 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).
- nsfw – Whether or not the submission should be marked NSFW (default: False).
- spoiler – Whether or not the submission should be marked as a spoiler (default: False).
- timeout – Specifies a particular timeout, in seconds. Use to avoid “Websocket error” exceptions (default: 10).
- without_websockets – Set to
True
to disable use of WebSockets (see note below for an explanation). IfTrue
, this method doesn’t return anything. (default:False
).
Returns: A
Submission
object for the newly created submission, unlesswithout_websockets
isTrue
.If
image_path
refers to a file that is not an image, PRAW will raise aClientException
.Note
Reddit’s API uses WebSockets to respond with the link of the newly created post. If this fails, the method will raise
WebSocketException
. Occasionally, the Reddit post will still be created. More often, there is an error with the image file. If you frequently get exceptions but successfully created posts, try setting thetimeout
parameter to a value above 10.To disable the use of WebSockets, set
without_websockets=True
. This will make the method returnNone
, though the post will still be created. You may wish to do this if you are running your program in a restricted network environment, or using a proxy that doesn’t support WebSockets connections.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, nsfw=False, spoiler=False, timeout=10, collection_id=None, without_websockets=False)¶ 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. IfTrue
, 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.
- collection_id – The UUID of a
Collection
to add the newly-submitted post to. - 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
). - nsfw – Whether or not the submission should be marked NSFW (default: False).
- spoiler – Whether or not the submission should be marked as a spoiler (default: False).
- timeout – Specifies a particular timeout, in seconds. Use to avoid “Websocket error” exceptions (default: 10).
- without_websockets – Set to
True
to disable use of WebSockets (see note below for an explanation). IfTrue
, this method doesn’t return anything. (default:False
).
Returns: A
Submission
object for the newly created submission, unlesswithout_websockets
isTrue
.If
video_path
refers to a file that is not a video, PRAW will raise aClientException
.Note
Reddit’s API uses WebSockets to respond with the link of the newly created post. If this fails, the method will raise
WebSocketException
. Occasionally, the Reddit post will still be created. More often, there is an error with the image file. If you frequently get exceptions but successfully created posts, try setting thetimeout
parameter to a value above 10.To disable the use of WebSockets, set
without_websockets=True
. This will make the method returnNone
, though the post will still be created. You may wish to do this if you are running your program in a restricted network environment, or using a proxy that doesn’t support WebSockets connections.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: str = 'all', **generator_kwargs) → Generator[[Any, None], None]¶ Return a
ListingGenerator
for top submissions.Parameters: time_filter – Can be one of: all, day, hour, month, week, year (default: all). Raise
ValueError
iftime_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 from 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)
-
Note
This list of attributes is not complete. PRAW dynamically provides the attributes that Reddit returns via the API. Because those attributes are subject to change on Reddit’s end, PRAW makes no effort to document them, other than to instruct you on how to discover what is available. See Determine Available Attributes of an Object for detailed information.