Submission
**********

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

   +-----------------------------+----------------------------------------------------------+
   | 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, or None if not flaired.             |
   +-----------------------------+----------------------------------------------------------+
   | "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: 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: Optional[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",
                    }
                ],
            }

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

      Example usage:

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

         comment = reddit.comment(id="dxolpyc")
         comment.clear_vote()

   property comments

      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.reddit.subreddit.Subreddit, title: Optional[str] = None, send_replies: bool = True, flair_id: Optional[str] = None, flair_text: Optional[str] = None, nsfw: bool = False, spoiler: bool = False) -> praw.models.reddit.submission.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.

         * **title** -- Title of the submission. Will use this
           submission's title if *None* (default: None).

         * **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).

         * **send_replies** -- When True, messages will be sent to the
           submission author when comments are made to the submission
           (default: True).

         * **nsfw** -- Whether or not the submission should be marked
           NSFW (default: False).

         * **spoiler** -- Whether or not the submission should be
           marked as a spoiler (default: False).

      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: Union[str, int, Dict[str, str]]) -> Iterator[Submission]

      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: str)

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

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

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

      Alias for "award()" to maintain backwards compatibility.

   hide(other_submissions: Optional[List[praw.models.reddit.submission.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(id="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_ht
           tps/

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

   mod()

      Provide an instance of "SubmissionModeration".

      Example usage:

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

   classmethod parse(data: Dict[str, Any], reddit: 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.

      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.

      Note:

        Some items, such as locked submissions/comments or non-
        replyable messages will throw "prawcore.exceptions.Forbidden"
        when attempting to reply to them.

      Example usage:

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

         comment = reddit.comment(id="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(id="5or86n")
         submission.report("report reason")

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

   save(category: Optional[str] = None)

      Save the object.

      Parameters:
         **category** -- (Premium) The category to save to. If your
         user does not have Reddit Premium 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()"

   property shortlink

      Return a shortlink to the submission.

      For example, https://redd.it/eorhm is a shortlink for https://w
      ww.reddit.com/r/announcements/comments/eorhm/reddit_30_less_typ
      ing/.

   unhide(other_submissions: Optional[List[praw.models.reddit.submission.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(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()"
