Praw

------------------

**Added**

- ``.Subreddit.rules`` to get the rules of a subreddit.
- :class:`.LiveContributorRelationship`, which can be obtained through
:attr:`.LiveThread.contributor`, to interact with live threads' contributors.
- :meth:`~.ModeratorRelationship.remove_invite` to remove a moderator invite.
- :meth:`.LiveContributorRelationship.invite` to send a contributor invitation.
- :meth:`.LiveContributorRelationship.remove_invite` to remove the contributor
invitation.

**Deprecated**

- Return values from :meth:`.Comment.block`, :meth:`.Message.block`,
:meth:`.SubredditMessage.block`, :meth:`.SubredditFlair.delete`, :meth:`.friend`,
:meth:`.Redditor.message`, :meth:`.Subreddit.message`, :meth:`.select`, and
:meth:`.unfriend` will be removed in PRAW 5 as they do not provide any useful
information.

**Fixed**

- :meth:`.hide` and :meth:`.unhide` now accept a list of additional submissions.
- :meth:`.replace_more` is now recoverable. Previously, when an exception was raised
during the work done by :meth:`.replace_more`, all unreplaced :class:`.MoreComments`
instances were lost. Now :class:`.MoreComments` instances are only removed once their
children have been added to the :class:`.CommentForest` enabling callers of
:meth:`.replace_more` to call the method as many times as required to complete the
replacement.
- Working with contributors on :class:`.SubredditWiki` is done consistently through
``contributor`` not ``contributors``.
- ``Subreddit.moderator()`` works.
- ``live_thread.contributor()`` now returns :class:`.RedditorList` correctly.

**Removed**

- ``validate_time_filter`` is no longer part of the public interface.

------------------

**Added**

- :meth:`.Subreddits.search_by_topic` to search subreddits by topic. (see:
https://www.reddit.com/dev/api/#GET_api_subreddits_by_topic).
- :meth:`.LiveHelper.__call__` to provide interface to
``praw.models.LiveThread.__init__``.
- :class:`.SubredditFilters` to work with filters for special subreddits, like
``r/all``.
- Added callables for :class:`.SubredditRelationship` and :class:`.SubredditFlair` so
that ``limit`` and other parameters can be passed.
- Add :meth:`.Message.reply` to :class:`.Message` which was accidentally missed
previously.
- Add ``sticky`` parameter to :meth:`.CommentModeration.distinguish` to sticky comments.
- :meth:`.Submission.flair` to add a submission's flair from an instance of
:class:`.Submission`.
- :meth:`.Comment.parent` to obtain the parent of a :class:`.Comment`.
- :meth:`.opt_in` and :meth:`.opt_out` to :class:`.Subreddit` to permit working with
quarantined subreddits.
- :class:`.LiveUpdate` to represent an individual update in a :class:`.LiveThread`.
- Ability to access an individual :class:`.LiveUpdate` via
``reddit.live("THREAD_ID")["UPDATE_ID"]``.
- :meth:`.LiveThread.updates` to iterate the updates of the thread.

**Changed**

- :meth:`.me` now caches its result in order to reduce redundant requests for methods
that depend on it. Set ``use_cache=False`` when calling to bypass the cache.
- :meth:`.replace_more` can be called on :class:`.Comment` ``replies``.

**Deprecated**

- ``validate_time_filter`` will be removed from the public interface in PRAW 4.2 as it
was never intended to be part of it to begin with.
- Iterating directly over :class:`.SubredditRelationship` (e.g., ``subreddit.banned``,
``subreddit.contributor``, ``subreddit.moderator``, etc) and :class:`.SubredditFlair`
will be removed in PRAW 5. Iterate instead over their callables, e.g.
``subreddit.banned()`` and ``subreddit.flair()``.
- The following methods are deprecated to be removed in PRAW 5 and are replaced with
similar ``Comment.mod...`` and ``Submission.mod...`` alternatives:
``Subreddit.mod.approve``, ``Subreddit.mod.distinguish``,
``Subreddit.mod.ignore_reports``, ``Subreddit.mod.remove``,
``Subreddit.mod.undistinguish``, ``Subreddit.mod.unignore_reports``.
- Support for passing a :class:`.Submission` to :meth:`.SubredditFlair.set` will be
removed in PRAW 5. Use :meth:`.Submission.flair` instead.
- The ``thing`` argument to :meth:`.SubredditFlair.set` is replaced with ``redditor``
and will be removed in PRAW 5.

**Fixed**

- :meth:`.SubredditModeration.update` accurately updates ``exclude_banned_modqueue``,
``header_hover_text``, ``show_media`` and ``show_media_preview`` values.
- Instances of :class:`.Comment` obtained through the inbox (including mentions) are now
refreshable.
- Searching ``r/all`` should now work as intended for all users.
- Accessing an invalid attribute on an instance of :class:`.Message` will raise
:py:class:`AttributeError` instead of :class:`.PRAWException`.

------------------

**Fixed**

- Fix bug where ipython tries to access attribute
``_ipython_canary_method_should_not_exist_`` resulting in a useless fetch.
- Fix bug where :class:`.Comment` replies becomes ``[]`` after attempting to access an
invalid attribute on the Comment.
- Reddit.wiki[...] converts the passed in page name to lower case as pages are only
saved in lower case and non-lower case page names results in a Redirect exception
(thanks pcjonathan).

---------------------

**Added**

- ``implicit`` parameter to :meth:`.url` to support the implicit flow for **installed**
applications (see:
https://github.com/reddit/reddit/wiki/OAuth2#authorization-implicit-grant-flow)
- :meth:`.scopes` to discover which scopes are available to the current authentication
- Lots of documentation: https://praw.readthedocs.io/

---------------------

**Fixed**

- :meth:`.Auth.authorize` properly sets the session's Authentication (thanks
williammck).

---------------------

PRAW 4 introduces significant breaking changes. The numerous changes are not listed
here, only the feature removals. Please read through :doc:`/getting_started/quick_start`
to help with updating your code to PRAW 4. If you require additional help please ask on
`r/redditdev <https://www.reddit.com/r/redditdev>`_ or via Slack.

**Added**

- :meth:`.Comment.block`, :meth:`.Message.block`, and :meth:`.SubredditMessage.block` to
permit blocking unwanted user contact.
- :meth:`.LiveHelper.create` to create new live threads.
- :meth:`.Redditor.unblock` to undo a block.
- :meth:`.Subreddits.gold` to iterate through gold subreddits.
- :meth:`.Subreddits.search` to search for subreddits by name and description.
- :meth:`.Subreddits.stream` to obtain newly created subreddits in near realtime.
- :meth:`.User.karma` to retrieve the current user's subreddit karma.
- ``praw.models.reddit.submission.SubmissionModeration.lock`` and
``praw.models.reddit.submission.SubmissionModeration.unlock`` to change a Submission's
lock state.
- :meth:`.SubredditFlairTemplates.delete` to delete a single flair template.
- :meth:`.SubredditModeration.unread` to iterate over unread moderation messages.
- :meth:`.ModeratorRelationship.invite` to invite a moderator to a subreddit.
- :meth:`.ModeratorRelationship.update` to update a moderator's permissions.
- :meth:`.ModeratorRelationship.update_invite` to update an invited moderator's
permissions.
- :meth:`.Front.random_rising`, :meth:`.Subreddit.random_rising` and
:meth:`.Multireddit.random_rising`.
- :class:`.WikiPage` supports a revision argument.
- :meth:`.SubredditWiki.revisions` to obtain a list of recent revisions to a subreddit.
- :meth:`.WikiPage.revisions` to obtain a list of revisions for a wiki page.
- Support installed-type OAuth apps.
- Support read-only OAuth for all application types.
- Support script-type OAuth apps.

**Changed**

.. note::

Only prominent changes are listed here.

- ``helpers.comments_stream`` is now :meth:`.SubredditStream.comments`
- ``helpers.submissions_between`` is now ``Subreddit.submissions``. This new method now
only iterates through newest submissions first and as a result makes approximately 33%
fewer requests.
- ``helpers.submission_stream`` is now :meth:`.SubredditStream.submissions`

**Removed**

- Removed :class:`.Reddit`'s ``login`` method. Authentication must be done through
OAuth.
- Removed ``praw-multiprocess`` as this functionality is no longer needed with PRAW 4.
- Removed non-oauth functions ``Message.collapse`` and ``Message.uncollapse``
``is_username_available``.
- Removed captcha related functions.

For changes prior to version 4.0 please see: `3.6.2 changelog
<https://praw.readthedocs.io/en/v3.6.2/pages/changelog.html>`_