Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# 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`.
  `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).
  `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.

  _edit_experimental(body: str, *, preserve_inline_media=False, inline_media: Optional[Dict[str, praw.models.InlineMedia]] = None) → praw.models.Submission

    Replace the body of the object with `body`.

    Parameters:

      - body – The Markdown formatted content for the updated object.

      - preserve_inline_media –

        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 – A dict of `InlineMedia` objects where the key is the placeholder name in `body`.

    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 – The key of the fetch parameter.

      - value – The value of the fetch parameter.

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

        submission = reddit.submission("mcqjl8")
        submission.add_fetch_param("rtj", "all")
        print(submission.rtjson)

  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: 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(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() → 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() → dict

    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() → 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) → Optional[Union[praw.models.Comment, praw.models.Message]]

    Reply to the object.

    Parameters:

      body – The Markdown formatted content for a comment.

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