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.c
         om/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()"

   shortlink

      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_typin
      g/.

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