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:
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')
- 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))
-
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
.
-
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
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')
-
filters
¶ Provide an instance of
SubredditFilters
.
-
flair
¶ Provide an instance of
SubredditFlair
.Provides the interface 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)
-
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 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)¶ 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
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.
-
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='cloudsearch', 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: cloudsearch – will be lucene in PRAW 5).
- time_filter – Can be one of: all, day, hour, month, week, year (default: all).
Warning
(Deprecation) The default search syntax is changing to
lucene
in PRAW 5. For forward compatibility please explicitly provide the search syntax.- 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
andend
.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 thanend
(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 thanstart
(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: If 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.
- start – A UNIX timestamp indicating the earliest creation time of
submission yielded during the call. A value of
-
submit
(title, selftext=None, url=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. - 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
orurl
can be provided, but not both.For example to submit a URL to
/r/reddit_api_test
do:url = 'https://praw.readthedocs.io' reddit.subreddit('reddit_api_test').submit(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
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 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)
-