Submission

class praw.models.Submission(reddit: praw.Reddit, id: Optional[str] = None, url: Optional[str] = None, _data: Optional[Dict[str, Any]] = 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`.
`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).
`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.

__init__(reddit: praw.Reddit, id: Optional[str] = None, url: Optional[str] = None, _data: Optional[Dict[str, Any]] = 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.

award(*, gild_type: str = 'gid_2', is_anonymous: bool = True, message: str = None) → dict

Award the author of the item.

Parameters

gild_type – Type of award to give. See table below for currently know global award types.
is_anonymous – If True, the authenticated user’s username will not be revealed to the recipient.
message – Message to include with the award.

Returns

A dict containing info similar to what is shown below:

{
    "subreddit_balance": 85260,
    "treatment_tags": [],
    "coins": 8760,
    "gildings": {"gid_1": 0, "gid_2": 1, "gid_3": 0},
    "awarder_karma_received": 4,
    "all_awardings": [
        {
            "giver_coin_reward": 0,
            "subreddit_id": None,
            "is_new": False,
            "days_of_drip_extension": 0,
            "coin_price": 75,
            "id": "award_9663243a-e77f-44cf-abc6-850ead2cd18d",
            "penny_donate": 0,
            "coin_reward": 0,
            "icon_url": "https://www.redditstatic.com/gold/awards/icon/SnooClappingPremium_512.png",
            "days_of_premium": 0,
            "icon_height": 512,
            "tiers_by_required_awardings": None,
            "icon_width": 512,
            "static_icon_width": 512,
            "start_date": None,
            "is_enabled": True,
            "awardings_required_to_grant_benefits": None,
            "description": "For an especially amazing showing.",
            "end_date": None,
            "subreddit_coin_reward": 0,
            "count": 1,
            "static_icon_height": 512,
            "name": "Bravo Grande!",
            "icon_format": "APNG",
            "award_sub_type": "PREMIUM",
            "penny_price": 0,
            "award_type": "global",
            "static_icon_url": "https://i.redd.it/award_images/t5_q0gj4/59e02tmkl4451_BravoGrande-Static.png",
        }
    ],
}

Warning

Requires the authenticated user to own Reddit Coins. Calling this method will consume Reddit Coins.

To award the gold award anonymously do:

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

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

To award the platinum award with the message ‘Nice!’ and reveal your username to the recipient do:

comment = reddit.comment("dkk4qjd")
comment.award(gild_type="gild_3", message="Nice!", is_anonymous=False)

submission = reddit.submission("8dmv8z")
submission.award(gild_type="gild_3", message="Nice!", is_anonymous=False)

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()

property comments: praw.models.comment_forest.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: praw.models.Subreddit, *, flair_id: Optional[str] = None, flair_text: Optional[str] = None, nsfw: bool = False, send_replies: bool = True, spoiler: bool = False, title: Optional[str] = None) → praw.models.Submission

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.
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).
nsfw – Whether the submission should be marked NSFW (default: False).
send_replies – When True, messages will be sent to the created submission’s author when comments are made to the submission (default: True).
spoiler – Whether the submission should be marked as a spoiler (default: False).
title – Title of the submission. Will use this submission’s title if None (default: None).

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()

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

Example usage:

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

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

See also

upvote()

duplicates(**generator_kwargs: Union[str, int, Dict[str, str]]) → Iterator[praw.models.Submission]

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()

edit(*, body: str) → Union[praw.models.Comment, praw.models.Submission]

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 the text of an edited comment
# by appending to the old body:
edited_body = comment.body + "Edit: thanks for the gold!"
comment.edit(body=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() → praw.models.reddit.submission.SubmissionFlair

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

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.

gild(): Alias for award() to maintain backwards compatibility.

hide(*, other_submissions: Optional[List[praw.models.Submission]] = 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("5or86n")
submission.hide()

See also

unhide()

static id_from_url(url: str) → str

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/"
"https://www.reddit.com/gallery/2gmzqe"

Raises

InvalidURL 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("5or86n")
submission.mark_visited()

mod() → praw.models.reddit.submission.SubmissionModeration

Provide an instance of SubmissionModeration.

Example usage:

submission = reddit.submission("8dmv8z")
submission.mod.approve()

classmethod parse(data: Dict[str, Any], reddit: praw.Reddit) → Any

Return an instance of cls from data.

Parameters

data – The structured data.
reddit – An instance of Reddit.

reply(*, body: str)

Reply to the object.

Parameters: body – The Markdown formatted content for a comment.
Returns: A Comment object for the newly created comment 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: str)

Report this object to the moderators of its subreddit.

Parameters: reason – The reason for reporting.
Raises: RedditAPIException if reason is longer than 100 characters.

Example usage:

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

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

save(*, category: Optional[str] = None)

Save the object.

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

Example usage:

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

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

See also

unsave()

property shortlink: str

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: Optional[List[praw.models.Submission]] = 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("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()

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()