v8.0.0

Added

• Add support for Python 3.13.
• Add support for Python 3.14.
• Add support for optional Markdown-formatted selftext when submitting link, image,
  gallery, and video posts.
• Add a :ref:migration guide <praw8_migration> covering all breaking changes in PRAW
  8.
• Add :class:.Media and its subclasses :class:.EmojiMedia, :class:.PostMedia,
  :class:.StylesheetAsset, :class:.StylesheetImage, and :class:.WidgetMedia to
  consolidate media uploads. Media can be constructed from a file path, or from
  bytes content along with a name, so media no longer has to be written to disk
  before uploading.
• :class:.Announcement and :class:.AnnouncementHelper, exposed as
  :attr:.Reddit.announcements, for listing, hiding, and marking the currently
  authenticated user's announcements as read. Provides :meth:.Announcement.hide,
  :meth:.Announcement.mark_read, :meth:.AnnouncementHelper.hide,
  :meth:.AnnouncementHelper.mark_read, and :meth:.AnnouncementHelper.mark_all_read.
  :attr:.Announcement.sent_datetime and :attr:.Announcement.read_datetime return the
  announcement's sent_at and read_at timestamps as timezone-aware
  :class:datetime.datetime objects (read_datetime is None for unread
  announcements).
• :meth:.Redditor.overview to iterate over a Redditor's combined comments and
  submissions, mirroring the user overview page on Reddit.
• An exception_handler keyword argument to :func:.stream_generator (and thus all
  stream methods) that is invoked with any exception raised while fetching items,
  allowing the stream to resume rather than terminate. Re-raise from the handler to stop
  the stream.
• :attr:~.Comment.created_datetime to objects with a creation time (for example
  :class:.Comment, :class:.Submission, :class:.Redditor, :class:.Subreddit,
  :class:.Collection, and :class:.ModNote), returning a timezone-aware
  :class:datetime.datetime.
• :attr:~.Collection.updated_datetime to :class:.Collection,
  :attr:~.PollData.voting_end_datetime to :class:.PollData, and
  :attr:~.Comment.edited_datetime to :class:.Comment and :class:.Submission
  (None when the object has not been edited), all returning timezone-aware
  :class:datetime.datetime objects.
• Warn when a praw.ini in the current working directory sets the oauth_url or
  reddit_url endpoint, as such a file can redirect credentials to an untrusted host.
  The warning can be silenced by setting the PRAW_ALLOW_ENDPOINT_OVERRIDE
  environment variable.
• A py.typed marker (:PEP:561) so that downstream projects can type check against
  PRAW's inline annotations.

Changed

• Bumped prawcore to 3.0.2.

• Drop support for Python 3.8, which was end-of-life on 2024-10-07.

• Drop support for Python 3.9, which was end-of-life on 2025-10-31.

• Change Reddit.user.me to raise :class:.ReadOnlyException when called in
  :attr:.read_only mode.

• The subreddit attribute of :class:.Redditor is a :class:.UserSubreddit
  instance.

• The data argument to Objector.objectify must now be passed by keyword.

• The mark_read argument to subreddit.modmail (:class:.ModmailConversation)
  must now be passed by keyword.

• The flair_type argument to :class:.SubredditFlairTemplates must be passed by
  keyword.

• The selftext and url arguments to :meth:.Subreddit.submit are no longer
  mutually exclusive. When url is provided selftext will be used as optional
  body text to accompany the link submission. An exception is raised when trying to use
  inline_media with selftext for a url submission because Reddit does not
  support inline media in body text for link submissions.

• Subreddit.submit_video, Subreddit.submit_gallery, and
  Subreddit.submit_image now accept an optional Markdown-formatted selftext
  parameter.

• The reason_id argument to :class:.RemovalReason has been renamed to id.

• Media upload methods now accept :class:.Media instances instead of file paths:

  • The image_path argument to :meth:.SubredditEmoji.add has been replaced by
    media, which takes an :class:.EmojiMedia instance.
  • The image_path arguments to the :class:.SubredditStylesheet upload_*
    methods have been replaced by media, which must be passed positionally.
    :meth:.SubredditStylesheet.upload, :meth:.upload_header,
    :meth:.upload_mobile_header, and :meth:.upload_mobile_icon take a
    :class:.StylesheetImage instance, while :meth:.upload_banner,
    :meth:.upload_banner_additional_image, :meth:.upload_banner_hover_image, and
    :meth:.upload_mobile_banner take a :class:.StylesheetAsset instance.
  • The file_path argument to :meth:.SubredditWidgetsModeration.upload_image has
    been replaced by media, which takes a :class:.WidgetMedia instance and must be
    passed positionally.
  • The path argument to :class:.InlineMedia (:class:.InlineGif,
    :class:.InlineImage, and :class:.InlineVideo) has been replaced by media,
    which takes a :class:.PostMedia instance.

• An unknown media type now raises :class:.ClientException when uploading media,
  instead of falling back to JPEG.

• Media uploads to Reddit's S3 buckets now respect the configured timeout and raise
  prawcore.RequestException on transport errors, consistent with all other requests,
  instead of having no timeout and raising raw requests exceptions.

• Subreddit.submit_gallery, Subreddit.submit_image, Subreddit.submit_poll,
  and Subreddit.submit_video have been merged into :meth:.Subreddit.submit. The
  kind of submission is selected with the gallery, image, poll, url, or
  video keyword argument. At least one of those, or selftext, must be provided,
  and they are mutually exclusive, while selftext may accompany any of them as
  optional Markdown-formatted body text. image takes a :class:.PostMedia instance;
  gallery takes a list of :class:.PostMedia instances or dict\ s with a
  media key; video takes a :class:.PostMedia instance or a dict with a
  media key and optional gif and thumbnail keys; and poll takes a
  dict with duration and options keys. selftext is no longer required
  for poll submissions.

• Require prawcore >=3.2, <4 for its public :class:!Session and authorizer
  accessors and the widened :meth:!Session.request annotations, which let PRAW drop a
  number of internal cast\ s and type-checker suppressions.

• Constrain the websocket-client dependency to <2 to avoid silently adopting a
  future, potentially breaking, major release.

• Require update_checker >=1.0, <2.0 and call update_check with keyword
  arguments. The 1.0 release is dependency-free.

• :meth:.Submission.add_fetch_param now raises :class:.ClientException when called
  on a submission that has already been fetched, rather than logging a warning, since
  the added parameters would have no effect.

• The comment_sort and comment_limit attributes of a :class:.Submission must
  now be set before the submission is fetched; setting either after the submission has
  been fetched raises :class:.ClientException instead of logging a warning.

• Require prawcore >=4, <5.

• Split praw/models/reddit/subreddit.py into a praw.models.reddit.subreddit
  package, with :class:.Subreddit and each of its helper classes (:class:.Modmail,
  :class:.SubredditFilters, :class:.SubredditFlair, :class:.SubredditModeration,
  :class:.SubredditQuarantine, :class:.SubredditRelationship,
  :class:.SubredditStream, :class:.SubredditStylesheet, :class:.SubredditWiki, and
  their related classes) moved to dedicated modules. All classes remain importable from
  praw.models.reddit.subreddit and praw.models for backwards compatibility. See
  the :ref:migration guide <praw8_migration> for the full mapping.

Fixed

• Fix API endpoint for :meth:.Submission.hide and :meth:.Submission.unhide.
• Fix TypeError when objectifying a response whose json.errors field is null
  rather than an empty list (e.g. api/hide).

Removed

• Remove Reddit.random_subreddit, Subreddit.random, and
  Subreddit.random_rising.
• Remove APIException class.
• Remove Comment.award and Submission.award methods.
• Remove Comment.gild, Redditor.gild, and Submission.gild methods.
• Remove Redditor.gilded and Subreddit.gilded methods.
• Remove Redditor.gildings method.
• Remove Subreddit.mod.inbox, Subreddit.mod.unread, and
  Subreddit.mod.stream.unread methods.
• Remove Subreddits.search_by_topic method.
• Remove Subreddits.gold method.
• Remove :class:.Reddit keyword argument token_manager and all associated token
  managers.
• Remove Reddit.validate_on_submit configuration attribute.
• Remove WebSocketException.original_exception method.
• Remove the after argument for :meth:.conversations.
• Remove key reset_timestamp from :meth:.limits.
• Remove SubredditMessage.mute and SubredditMessage.unmute methods.
• Remove InboxableMixin.unblock_subreddit method.
• The warn_additional_fetch_params configuration option, which is obsolete now that
  adding fetch parameters to an already-fetched submission raises
  :class:.ClientException.
• The warn_comment_sort configuration option, which is obsolete now that setting
  comment_sort or comment_limit after the comments have been fetched raises
  :class:.ClientException.