Submission

class praw.models.Submission(reddit, id=None, url=None, _data=None)

A class for submissions to reddit.

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
author Provides an instance of Redditor.
clicked Whether or not the submission has been clicked by the client.
comments Provides an instance of CommentForest.
created_utc Time the submission was created, represented in Unix Time.
distinguished Whether or not the submission is distinguished.
edited Whether or not the submission has been edited.
id The ID of the submission.
is_video Whether or not the submission is a Reddit-hosted video.
link_flair_css_class The CSS class for the submissions’ flair.
link_flair_text The flair text for the submissions’ flair.
locked Whether or not the submission has been locked.
num_comments The number of comments on the submission.
over_18 Whether or not the submission has been marked as NSFW.
permalink A permalink for the submission.
score The number of upvotes for the submission.
selftext The submissions’ selftext.
stickied Whether or not the submission is stickied.
subreddit Provides an instance of Subreddit.
subreddit_id The ID of the subreddit that the submission belongs to.
title The title of the submission.
upvote_ratio The percentage of upvotes from all votes on the submission.
__init__(reddit, id=None, url=None, _data=None)

Initialize a Submission instance.

Parameters:
  • reddit – An instance of Reddit.
  • id – A reddit base36 submission ID, e.g., 2gmzqe.
  • url – A URL supported by id_from_url().

Either id or url can be provided, but not both.

clear_vote()

Clear the authenticated user’s vote on the object.

Note

Votes must be cast by humans. That is, API clients proxying a human’s action one-for-one are OK, but bots deciding how to vote on content or amplifying a human’s vote are not. See the reddit rules for more details on what constitutes vote cheating. [Ref]

Example usage:

submission = reddit.submission(id='5or86n')
submission.clear_vote()

comment = reddit.comment(id='dxolpyc')
comment.clear_vote()
comment_sort = None

Specify the sort order for comments

comments

Provide an instance of CommentForest.

This attribute can use used, for example, to obtain a flat list of comments, with any MoreComments removed:

submission.comments.replace_more(limit=0)
comments = submission.comments.list()

Sort order and comment limit can be set with the comment_sort and comment_limit attributes before comments are fetched, including any call to replace_more():

submission.comment_sort = 'new'
comments = submission.comments.list()

See Extracting comments with PRAW for more on working with a CommentForest.

crosspost(subreddit, title=None, send_replies=True)

Crosspost the submission to a subreddit.

Note

Be aware you have to be subscribed to the target subreddit.

Parameters:
  • subreddit – Name of the subreddit or Subreddit object to crosspost into.
  • title – Title of the submission. Will use this submission’s title if None (default: None).
  • 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.

Example usage:

submission = reddit.submission(id='5or86n')
cross_post = submission.crosspost(subreddit="learnprogramming",
                                  send_replies=False)

See also hide()

delete()

Delete the object.

Example usage:

comment = reddit.comment('dkk4qjd')
comment.delete()

submission = reddit.submission('8dmv8z')
submission.delete()
disable_inbox_replies()

Disable inbox replies for the item.

Example usage:

comment = reddit.comment('dkk4qjd')
comment.disable_inbox_replies()

submission = reddit.submission('8dmv8z')
submission.disable_inbox_replies()

See also enable_inbox_replies()

downvote()

Downvote the object.

Note

Votes must be cast by humans. That is, API clients proxying a human’s action one-for-one are OK, but bots deciding how to vote on content or amplifying a human’s vote are not. See the reddit rules for more details on what constitutes vote cheating. [Ref]

Example usage:

submission = reddit.submission(id='5or86n')
submission.downvote()

comment = reddit.comment(id='dxolpyc')
comment.downvote()

See also upvote()

duplicates(**generator_kwargs)

Return a ListingGenerator for the submission’s duplicates.

Additional keyword arguments are passed in the initialization of ListingGenerator.

Example usage:

submission = reddit.submission(id='5or86n')

for duplicate in submission.duplicates():
    # process each duplicate

See also upvote()

edit(body)

Replace the body of the object with body.

Parameters:body – The markdown formatted content for the updated object.
Returns:The current instance after updating its attributes.

Example usage:

comment = reddit.comment('dkk4qjd')

#construct edited comment text by appending to old body
edited_body = comment.body + "Edit: thanks for the gold!"
comment.edit(edited_body)
enable_inbox_replies()

Enable inbox replies for the item.

Example usage:

comment = reddit.comment('dkk4qjd')
comment.enable_inbox_replies()

submission = reddit.submission('8dmv8z')
submission.enable_inbox_replies()

See also disable_inbox_replies()

flair

Provide an instance of SubmissionFlair.

This attribute is used to work with flair as a regular user of the subreddit the submission belongs to. Moderators can directly use flair().

For example, to select an arbitrary editable flair text (assuming there is one) and set a custom value try:

choices = submission.flair.choices()
template_id = next(x for x in choices
                   if x['flair_text_editable'])['flair_template_id']
submission.flair.select(template_id, 'my custom value')
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.

gild()

Gild the author of the item.

Note

Requires the authenticated user to own reddit gold creddits. Calling this method will consume one reddit gold creddit.

Example usage:

comment = reddit.comment('dkk4qjd')
comment.gild()

submission = reddit.submission('8dmv8z')
submission.gild()
hide(other_submissions=None)

Hide Submission.

Parameters:other_submissions – When provided, additionally hide this list of Submission instances as part of a single request (default: None).

Example usage:

submission = reddit.submission(id='5or86n')
submission.hide()

See also unhide()

static id_from_url(url)

Return the ID contained within a submission URL.

Parameters:url – A url to a submission in one of the following formats (http urls will also work): * https://redd.it/2gmzqe * https://reddit.com/comments/2gmzqe/ * https://www.reddit.com/r/redditdev/comments/2gmzqe/praw_https/

Raise ClientException if URL is not a valid submission URL.

mark_visited()

Mark submission as visited.

This method requires a subscription to reddit premium.

Example usage:

submission = reddit.submission(id='5or86n')
submission.mark_visited()
mod

Provide an instance of SubmissionModeration.

classmethod parse(data, reddit)

Return an instance of cls from data.

Parameters:
  • data – The structured data.
  • reddit – An instance of Reddit.
reply(body)

Reply to the object.

Parameters:body – The markdown formatted content for a comment.
Returns:A Comment object for the newly created comment.

Example usage:

submission = reddit.submission(id='5or86n')
submission.reply('reply')

comment = reddit.comment(id='dxolpyc')
comment.reply('reply')
report(reason)

Report this object to the moderators of its subreddit.

Parameters:reason – The reason for reporting.

Example usage:

submission = reddit.submission(id='5or86n')
submission.report('report reason')

comment = reddit.comment(id='dxolpyc')
comment.report('report reason')
save(category=None)

Save the object.

Parameters:category – (Gold) The category to save to. If your user does not have gold this value is ignored by Reddit (default: None).

Example usage:

submission = reddit.submission(id='5or86n')
submission.save(category="view later")

comment = reddit.comment(id='dxolpyc')
comment.save()

See also unsave()

Return a shortlink to the submission.

For example http://redd.it/eorhm is a shortlink for https://www.reddit.com/r/announcements/comments/eorhm/reddit_30_less_typing/.

unhide(other_submissions=None)

Unhide Submission.

Parameters:other_submissions – When provided, additionally unhide this list of Submission instances as part of a single request (default: None).

Example usage:

submission = reddit.submission(id='5or86n')
submission.unhide()

See also hide()

unsave()

Unsave the object.

Example usage:

submission = reddit.submission(id='5or86n')
submission.unsave()

comment = reddit.comment(id='dxolpyc')
comment.unsave()

See also save()

upvote()

Upvote the object.

Note

Votes must be cast by humans. That is, API clients proxying a human’s action one-for-one are OK, but bots deciding how to vote on content or amplifying a human’s vote are not. See the reddit rules for more details on what constitutes vote cheating. [Ref]

Example usage:

submission = reddit.submission(id='5or86n')
submission.upvote()

comment = reddit.comment(id='dxolpyc')
comment.upvote()

See also downvote()