v8.0.0

Added

• :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).
• :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.
• 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.
• 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.
• :meth:.Redditor.overview to iterate over a Redditor's combined comments and
  submissions, mirroring the user overview page on Reddit.
• 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 :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.
• Support delayed session creation in asyncprawcore 2.5.0+.
• Add parameter fetch to :meth:.get_rule to control whether to fetch the rule data
  when initializing the rule object.
• A py.typed marker (:PEP:561) so that downstream projects can type check against
  Async PRAW's inline annotations.

Changed

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

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

• Require update_checker[async] >=1.0, <2.0 and perform the update check using its
  native async API on the first request, instead of a blocking call during Reddit
  initialization. The 1.0 release is dependency-free, dropping requests from Async
  PRAW's transitive dependencies.

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

• 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_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.

• 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:.SubredditStylesheet.upload_header,
    :meth:.SubredditStylesheet.upload_mobile_header, and
    :meth:.SubredditStylesheet.upload_mobile_icon take a :class:.StylesheetImage
    instance, while :meth:.SubredditStylesheet.upload_banner,
    :meth:.SubredditStylesheet.upload_banner_additional_image,
    :meth:.SubredditStylesheet.upload_banner_hover_image, and
    :meth:.SubredditStylesheet.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
  asyncprawcore.RequestException on transport errors, consistent with all other
  requests, instead of bypassing the configured timeout and raising raw aiohttp
  exceptions.

• :meth:.CommentForest.list no longer needs to be awaited.

• The keyword argument lazy has been replace by fetch to consolidate the keyword
  argument used to explicitly perform a fetch when initializing an object.

• The argument reason_id in :meth:.RemovalReason.__init__ has been replaced with
  id and is now a positional-only argument.

• The name argument in :meth:.get_emoji is now a positional-only argument.

• The reason_id argument in :meth:.get_reason has been replaced with id and is
  now a positional-only argument.

• The short_name argument in :meth:.get_rule is now a positional-only argument.

• The update_id argument in :meth:.get_update has been replaced with id and is
  now a positional-only argument.

• The page_name argument in :meth:.get_page is now a positional-only argument.

• The fetch argument in the following methods is now a keyword-only argument:

  • :meth:.get_emoji
  • :meth:.get_reason
  • :meth:.get_update
  • :meth:.DraftHelper.__call__
  • :meth:.LiveHelper.__call__
  • :meth:.Modmail.__call__
  • :meth:.SubredditCollections.__call__
  • :meth:.SubredditHelper.__call__

• :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. Because
  reddit.submission() fetches by default, initialize the submission with
  fetch=False, set the attributes, then call :meth:~.Submission.load.

• Require asyncprawcore >=4, <5.

• Split asyncpraw/models/reddit/subreddit.py into an
  asyncpraw.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
  asyncpraw.models.reddit.subreddit and asyncpraw.models for backwards
  compatibility. See the :ref:migration guide <asyncpraw8_migration> for the full
  mapping.

Fixed

• An issue where submitting a gallery post with websockets enabled would fail.
• Fix API endpoint for :meth:.Submission.hide and :meth:.Submission.unhide, which
  returned a 404 due to a trailing slash.
• Fix TypeError when objectifying a response whose json.errors field is null
  rather than an empty list (e.g. api/hide).

Removed

• 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.
• Remove Reddit.random_subreddit, Subreddit.random, and
  Subreddit.random_rising.
• Remove APIException class.
• Remove PRAWException class rename handler.
• 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 ability to use :class:.CommentForest as an asynchronous iterator.
• Remove ability to use :class:.Reddit as an synchronous context manager.
• Remove key reset_timestamp from :meth:.limits.
• Remove SubredditMessage.mute and SubredditMessage.unmute methods.
• Remove InboxableMixin.unblock_subreddit method.