Submission

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

A class for submissions to Reddit.

Typical Attributes

Note

This table describes attributes that typically belong to objects of this class. PRAW dynamically provides the attributes that Reddit returns via the API. Since those attributes are subject to change on Reddit’s end, PRAW makes no effort to document any new/removed/changed attributes, other than to instruct you on how to discover what is available. As a result, this table of attributes may not be complete. See Determine Available Attributes of an Object for detailed information.

If you would like to add an attribute to this table, feel free to open a pull request.

Attribute

Description

author

Provides an instance of Redditor.

author_flair_text

The text content of the author’s flair, or None if not flaired.

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

ID of the submission.

is_original_content

Whether or not the submission has been set as original content.

is_self

Whether or not the submission is a selfpost (text-only).

likes

The user’s current vote status on the submission: True if upvoted, False if downvoted, and None if not voted or not logged in.

link_flair_template_id

The link flair’s ID.

link_flair_text

The link flair’s text content, or None if not flaired.

locked

Whether or not the submission has been locked.

name

Fullname of the submission.

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.

poll_data

A PollData object representing the data of this submission, if it is a poll submission.

saved

Whether or not the submission is saved.

score

The number of upvotes for the submission.

selftext

The submissions’ selftext - an empty string if a link post.

spoiler

Whether or not the submission has been marked as a spoiler.

stickied

Whether or not the submission is stickied.

subreddit

Provides an instance of Subreddit.

title

The title of the submission.

upvote_ratio

The percentage of upvotes from all votes on the submission.

url

The URL the submission links to, or the permalink if a selfpost.
Parameters:
__init__(reddit, id=None, url=None, _data=None)

Initialize a Submission instance.

Parameters:
Return type:

None

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

_edit_experimental(body, *, preserve_inline_media=False, inline_media=None)

Replace the body of the object with body.

Parameters:

  • body (str) – The Markdown formatted content for the updated object.

  • preserve_inline_media (bool) –

    Attempt to preserve inline media in body.

    Danger

    This method is experimental. It is reliant on undocumented API endpoints and may result in existing inline media not displaying correctly and/or creating a malformed body. Use at your own risk. This method may be removed in the future without warning.

  • inline_media (dict[str, InlineMedia] | None) – A dict of InlineMedia objects where the key is the placeholder name in body.

Return type:

Submission

Returns:

The current instance after updating its attributes.

Example usage:

from praw.models import InlineGif, InlineImage, InlineVideo

submission = reddit.submission("5or86n")
gif = InlineGif(path="path/to/image.gif", caption="optional caption")
image = InlineImage(path="path/to/image.jpg", caption="optional caption")
video = InlineVideo(path="path/to/video.mp4", caption="optional caption")
body = "New body with a gif {gif1} an image {image1} and a video {video1} inline"
media = {"gif1": gif, "image1": image, "video1": video}
submission._edit_experimental(submission.selftext + body, inline_media=media)
add_fetch_param(key, value)

Add a parameter to be used for the next fetch.

Parameters:

  • key (str) – The key of the fetch parameter.

  • value (str) – The value of the fetch parameter.

Return type:

None

For example, to fetch a submission with the rtjson attribute populated:

submission = reddit.submission("mcqjl8")
submission.add_fetch_param("rtj", "all")
print(submission.rtjson)
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 manipulation. [Ref]

Example usage:

submission = reddit.submission("5or86n")
submission.clear_vote()

comment = reddit.comment("dxolpyc")
comment.clear_vote()
Return type:

None

property comments: CommentForest

Provide an instance of CommentForest.

This attribute can be 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()

Note

The appropriate values for "comment_sort" include "confidence", "controversial", "new", "old", "q&a", and "top"

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

crosspost(subreddit, *, flair_id=None, flair_text=None, nsfw=False, send_replies=True, spoiler=False, title=None)

Crosspost the submission to a subreddit.

Note

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

Parameters:

  • subreddit (Subreddit) – Name of the subreddit or Subreddit object to crosspost into.

  • flair_id (str | None) – The flair template to select (default: None).

  • flair_text (str | None) – If the template’s flair_text_editable value is True, this value will set a custom text (default: None).

  • nsfw (bool) – Whether the submission should be marked NSFW (default: False).

  • send_replies (bool) – When True, messages will be sent to the created submission’s author when comments are made to the submission (default: True).

  • spoiler (bool) – Whether the submission should be marked as a spoiler (default: False).

  • title (str | None) – Title of the submission. Will use this submission’s title if None (default: None).

Return type:

Submission

Returns:

A Submission object for the newly created submission.

Example usage:

submission = reddit.submission("5or86n")
cross_post = submission.crosspost("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()
Return type:

None

disable_inbox_replies()

Disable inbox replies for the item.

Note

This can only apply to items created by the authenticated user.

Example usage:

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

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

See also

enable_inbox_replies()

Return type:

None

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 manipulation. [Ref]

Example usage:

submission = reddit.submission("5or86n")
submission.downvote()

comment = reddit.comment("dxolpyc")
comment.downvote()

See also

upvote()

Return type:

None

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("5or86n")

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

See also

upvote()

Return type:

Iterator[Submission]

Parameters:

generator_kwargs (str | int | dict[str, str])

edit(body)

Replace the body of the object with body.

Parameters:

body (str) – The Markdown formatted content for the updated object.

Return type:

Comment | Submission

Returns:

The current instance after updating its attributes.

Example usage:

comment = reddit.comment("dkk4qjd")

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

Enable inbox replies for the item.

Note

This can only apply to items created by the authenticated user.

Example usage:

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

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

See also

disable_inbox_replies()

Return type:

None

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, text="my custom value")
Return type:

SubmissionFlair

property fullname: str

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.

hide(*, other_submissions=None)

Hide Submission.

Parameters:

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

Return type:

None

Example usage:

submission = reddit.submission("5or86n")
submission.hide()

See also

unhide()

static id_from_url(url)

Return the ID contained within a submission URL.

Parameters:

url (str) –

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/"

  • "https://www.reddit.com/gallery/2gmzqe"

Raises:

InvalidURL if url is not a valid submission URL.

Return type:

str

mark_visited()

Mark submission as visited.

This method requires a subscription to reddit premium.

Example usage:

submission = reddit.submission("5or86n")
submission.mark_visited()
Return type:

None

mod()

Provide an instance of SubmissionModeration.

Example usage:

submission = reddit.submission("8dmv8z")
submission.mod.approve()
Return type:

SubmissionModeration

classmethod parse(data, reddit)

Return an instance of cls from data.

Parameters:
Return type:

PRAWBase

reply(body)

Reply to the object.

Parameters:

body (str) – The Markdown formatted content for a comment.

Return type:

Comment | Message | None

Returns:

A Comment or Message object for the newly created comment or message or None if Reddit doesn’t provide one.

Raises:

prawcore.exceptions.Forbidden when attempting to reply to some items, such as locked submissions/comments or non-replyable messages.

A None value can be returned if the target is a comment or submission in a quarantined subreddit and the authenticated user has not opt-ed into viewing the content. When this happens the comment will be successfully created on Reddit and can be retried by drawing the comment from the user’s comment history.

Example usage:

submission = reddit.submission("5or86n")
submission.reply("reply")

comment = reddit.comment("dxolpyc")
comment.reply("reply")
report(reason)

Report this object to the moderators of its subreddit.

Parameters:

reason (str) – The reason for reporting.

Raises:

RedditAPIException if reason is longer than 100 characters.

Return type:

None

Example usage:

submission = reddit.submission("5or86n")
submission.report("report reason")

comment = reddit.comment("dxolpyc")
comment.report("report reason")
save(*, category=None)

Save the object.

Parameters:

category (str | None) – The category to save to. If the authenticated user does not have Reddit Premium this value is ignored by Reddit (default: None).

Return type:

None

Example usage:

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

comment = reddit.comment("dxolpyc")
comment.save()

See also

unsave()

Return a shortlink to the submission.

For example, https://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 (list[Submission] | None) – When provided, additionally unhide this list of Submission instances as part of a single request (default: None).

Return type:

None

Example usage:

submission = reddit.submission("5or86n")
submission.unhide()

See also

hide()

unsave()

Unsave the object.

Example usage:

submission = reddit.submission("5or86n")
submission.unsave()

comment = reddit.comment("dxolpyc")
comment.unsave()

See also

save()

Return type:

None

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 manipulation. [Ref]

Example usage:

submission = reddit.submission("5or86n")
submission.upvote()

comment = reddit.comment("dxolpyc")
comment.upvote()

See also

downvote()

Return type:

None