Deprecate token managers

Author: LilSpazJoekp

CHANGES.rst

@@ -14,6 +14,13 @@ Unreleased
 - :meth:`.Inbox.mark_all_read` to mark all messages as read with one API call.
 - :meth:`~.InboxableMixin.unblock_subreddit` to unblock a subreddit.
 - :meth:`.update_crowd_control_level` to update the crowd control level of a post.
+- The configuration setting ``refresh_token`` has been added back. See
+  https://www.reddit.com/r/redditdev/comments/olk5e6/followup_oauth2_api_changes_regarding_refresh/
+  for more info.
+
+**Deprecated**
+
+- :class:`.Reddit` keyword argument ``token_manager``.
 
 7.3.0 (2021/06/17)
 ------------------

docs/getting_started/authentication.rst

@@ -249,3 +249,29 @@ such as in installed applications where the end user could retrieve the ``client
     from each other (as the supplied device id *should* be a unique string per both
     device (in the case of a web app, server) and user (in the case of a web app,
     browser session).
+
+.. _using_refresh_tokens:
+
+Using a Saved Refresh Token
+---------------------------
+
+A saved refresh token can be used to immediately obtain an authorized instance of
+:class:`.Reddit` like so:
+
+.. code-block:: python
+
+    reddit = praw.Reddit(
+        client_id="SI8pN3DSbt0zor",
+        client_secret="xaxkj7HNh8kwg8e5t4m6KvSrbTI",
+        refresh_token="WeheY7PwgeCZj4S3QgUcLhKE5S2s4eAYdxM",
+        user_agent="testscript by u/fakebot3",
+    )
+    print(reddit.auth.scopes())
+
+The output from the above code displays which scopes are available on the
+:class:`.Reddit` instance.
+
+.. note::
+
+    Observe that ``redirect_uri`` does not need to be provided in such cases. It is only
+    needed when :meth:`.url` is used.

docs/tutorials/refresh_token.rst

@@ -3,14 +3,6 @@
 Working with Refresh Tokens
 ===========================
 
-.. note::
-
-    The process for using refresh tokens is in the process of changing on Reddit's end.
-    This documentation has been updated to be aligned with the future of how Reddit
-    handles refresh tokens, and will be the only supported method in PRAW 8+. For more
-    information please see:
-    https://old.reddit.com/r/redditdev/comments/kvzaot/oauth2_api_changes_upcoming/
-
 Reddit OAuth2 Scopes
 --------------------
 
@@ -82,33 +74,3 @@ The following program can be used to obtain a refresh token with the desired sco
 
 .. literalinclude:: ../examples/obtain_refresh_token.py
     :language: python
-
-.. _using_refresh_tokens:
-
-Using and Updating Refresh Tokens
----------------------------------
-
-Reddit refresh tokens can be used only once. When an authorization is refreshed the
-existing refresh token is consumed and a new access token and refresh token will be
-issued. While PRAW automatically handles refreshing tokens when needed, it does not
-automatically handle the storage of the refresh tokens. However, PRAW provides the
-facilities for you to manage your refresh tokens via custom subclasses of
-:class:`.BaseTokenManager`. For trivial examples, PRAW provides the
-:class:`.FileTokenManager`.
-
-The following program demonstrates how to prepare a file with an initial refresh token,
-and configure PRAW to both use that refresh token, and keep the file up-to-date with a
-valid refresh token.
-
-.. literalinclude:: ../examples/use_file_token_manager.py
-    :language: python
-
-.. _sqlite_token_manager:
-
-SQLiteTokenManager
-~~~~~~~~~~~~~~~~~~
-
-For more complex examples, PRAW provides the :class:`.SQLiteTokenManager`.
-
-.. literalinclude:: ../examples/use_sqlite_token_manager.py
-    :language: python

praw/config.py

@@ -4,7 +4,6 @@
 import sys
 from threading import Lock
 from typing import Optional
-from warnings import warn
 
 from .exceptions import ClientException
 
@@ -85,21 +84,11 @@ def __init__(
         self.custom = dict(Config.CONFIG.items(site_name), **settings)
 
         self.client_id = self.client_secret = self.oauth_url = None
-        self.reddit_url = self.redirect_uri = None
+        self.reddit_url = self.refresh_token = self.redirect_uri = None
         self.password = self.user_agent = self.username = None
 
         self._initialize_attributes()
 
-        self._do_not_use_refresh_token = self._fetch_or_not_set("refresh_token")
-        if self._do_not_use_refresh_token != self.CONFIG_NOT_SET:
-            warn(
-                "The ``refresh_token`` configuration setting is deprecated and will be"
-                " removed in PRAW 8. Please use ``token_manager`` to manage your"
-                " refresh tokens.",
-                category=DeprecationWarning,
-                stacklevel=2,
-            )
-
     def _fetch(self, key):
         value = self.custom[key]
         del self.custom[key]

praw/models/auth.py

@@ -105,20 +105,13 @@ def url(
             whom the URL was generated for.
         :param duration: Either ``permanent`` or ``temporary`` (default: permanent).
             ``temporary`` authorizations generate access tokens that last only 1 hour.
-            ``permanent`` authorizations additionally generate a single-use refresh
-            token with a significantly longer expiration (~1 year) that is to be used to
-            fetch a new set of tokens. This value is ignored when ``implicit=True``.
+            ``permanent`` authorizations additionally generate a refresh token that
+            expires 1 year after the last use and can be used indefinitely to generate
+            new hour-long access tokens. This value is ignored when ``implicit=True``.
         :param implicit: For **installed** applications, this value can be set to use
             the implicit, rather than the code flow. When True, the ``duration``
             argument has no effect as only temporary tokens can be retrieved.
 
-        .. note::
-
-            Reddit's ``refresh_tokens`` currently are reusable, and do not expire.
-            However, that behavior is likely to change in the near future so it's best
-            to no longer rely upon it:
-            https://old.reddit.com/r/redditdev/comments/kvzaot/oauth2_api_changes_upcoming/
-
         """
         authenticator = self._reddit._read_only_core._authorizer._authenticator
         if authenticator.redirect_uri is self._reddit.config.CONFIG_NOT_SET:

praw/reddit.py

@@ -420,9 +420,16 @@ def _check_for_update(self):
 
     def _prepare_common_authorizer(self, authenticator):
         if self._token_manager is not None:
-            if self.config._do_not_use_refresh_token != self.config.CONFIG_NOT_SET:
+            warn(
+                "Token managers have been depreciated and will be removed in the near"
+                " future. See https://www.reddit.com/r/redditdev/comments/olk5e6/"
+                "followup_oauth2_api_changes_regarding_refresh/ for more details.",
+                category=DeprecationWarning,
+                stacklevel=2,
+            )
+            if self.config.refresh_token:
                 raise TypeError(
-                    "legacy ``refresh_token`` setting cannot be provided when providing"
+                    "``refresh_token`` setting cannot be provided when providing"
                     " ``token_manager``"
                 )
 
@@ -432,9 +439,9 @@ def _prepare_common_authorizer(self, authenticator):
                 post_refresh_callback=self._token_manager.post_refresh_callback,
                 pre_refresh_callback=self._token_manager.pre_refresh_callback,
             )
-        elif self.config._do_not_use_refresh_token != self.config.CONFIG_NOT_SET:
+        elif self.config.refresh_token != self.config.CONFIG_NOT_SET:
             authorizer = Authorizer(
-                authenticator, refresh_token=self.config._do_not_use_refresh_token
+                authenticator, refresh_token=self.config.refresh_token
             )
         else:
             self._core = self._read_only_core

praw/util/token_manager.py

@@ -6,7 +6,9 @@
 A few proof of concept token manager classes are provided here, but it is expected that
 PRAW users will create their own token manager classes suitable for their needs.
 
-See :ref:`using_refresh_tokens` for examples on how to leverage these classes.
+.. deprecated:: 7.3.0
+
+    Tokens managers have been depreciated and will be removed in the near future.
 
 """
 import sqlite3
@@ -100,7 +102,6 @@ class SQLiteTokenManager(BaseTokenManager):
     Unlike, :class:`.FileTokenManager`, the initial database need not be created ahead
     of time, as it'll automatically be created on first use. However, initial
     ``refresh_tokens`` will need to be registered via :meth:`.register` prior to use.
-    See :ref:`sqlite_token_manager` for an example of use.
 
     .. warning::
 

tests/unit/test_deprecations.py

@@ -5,6 +5,7 @@
 from praw import Reddit
 from praw.exceptions import APIException, WebSocketException
 from praw.models.reddit.user_subreddit import UserSubreddit
+from praw.util.token_manager import FileTokenManager
 
 from . import UnitTest
 
@@ -59,20 +60,20 @@ def test_gild_method(self):
             self.reddit.submission("1234").gild()
             assert excinfo.value.args[0] == "`.gild` has been renamed to `.award`."
 
-    def test_reddit_user_me_read_only(self):
-        with pytest.raises(DeprecationWarning):
-            self.reddit.user.me()
-
-    def test_reddit_refresh_token(self):
+    def test_reddit_token_manager(self):
         with pytest.raises(DeprecationWarning):
             Reddit(
                 client_id="dummy",
                 client_secret=None,
                 redirect_uri="dummy",
-                refresh_token="dummy",
                 user_agent="dummy",
+                token_manager=FileTokenManager("name"),
             )
 
+    def test_reddit_user_me_read_only(self):
+        with pytest.raises(DeprecationWarning):
+            self.reddit.user.me()
+
     def test_user_subreddit_as_dict(self):
         user_subreddit = UserSubreddit(None, display_name="test")
         with pytest.deprecated_call() as warning_info:

tests/unit/test_reddit.py

@@ -88,7 +88,7 @@ def test_conflicting_settings(self):
             )
         assert (
             str(excinfo.value)
-            == "legacy ``refresh_token`` setting cannot be provided when providing ``token_manager``"
+            == "``refresh_token`` setting cannot be provided when providing ``token_manager``"
         )
 
     def test_context_manager(self):