Removed the TokenUpdated exception.

It was redundant. There is no reason why any code that must react to the
exception couldn't just use token_updater.

docs/api.rst

@@ -26,9 +26,6 @@ OAuth 2.0
 .. autoclass:: OAuth2
     :members:
 
-.. autoclass:: TokenUpdated
-    :members:
-
 
 OAuth 2.0 Session
 -----------------

docs/oauth2_workflow.rst

@@ -257,29 +257,27 @@ is necessary but refreshing is done manually.
     >>> client = OAuth2Session(client_id, token=token)
     >>> r = client.get(protected_url)
 
-(Second) Define automatic token refresh automatic but update manually
+(Second) Define automatic token refresh; no external update required.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This is the, arguably awkward, middle between the basic and convenient refresh
-methods in which a token is automatically refreshed, but saving the new token
-is done manually.
+Use this when the application does not need to take any action when the token
+is updated. It requires no exception catching and results in clean code.
+Remember however that you still need to update ``expires_in`` to trigger the
+refresh. And be sure to save ``client.token`` before destroying the handler.
 
 .. code-block:: pycon
 
-    >>> from requests_oauthlib import OAuth2Session, TokenUpdated
-    >>> try:
-    ...     client = OAuth2Session(client_id, token=token,
-    ...             auto_refresh_kwargs=extra, auto_refresh_url=refresh_url)
-    ...     r = client.get(protected_url)
-    >>> except TokenUpdated as e:
-    ...     token_saver(e.token)
+    >>> from requests_oauthlib import OAuth2Session
+    >>> client = OAuth2Session(client_id, token=token,
+    ...         auto_refresh_kwargs=extra, auto_refresh_url=refresh_url)
+    >>> r = client.get(protected_url)
 
-(Third, Recommended) Define automatic token refresh and update
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+(Third) Define automatic token refresh with external update
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The third and recommended method will automatically fetch refresh tokens and
-save them. It requires no exception catching and results in clean code. Remember
-however that you still need to update ``expires_in`` to trigger the refresh.
+The third method is the same as the second, only with a custom token update
+handler. Use this if your application needs to react immediately to a change in
+access token.
 
 .. code-block:: pycon
 

requests_oauthlib/__init__.py

@@ -3,7 +3,7 @@
 from .oauth1_auth import OAuth1
 from .oauth1_session import OAuth1Session
 from .oauth2_auth import OAuth2
-from .oauth2_session import OAuth2Session, TokenUpdated
+from .oauth2_session import OAuth2Session
 
 __version__ = "1.3.1"
 

requests_oauthlib/oauth2_session.py

@@ -11,12 +11,6 @@
 log = logging.getLogger(__name__)
 
 
-class TokenUpdated(Warning):
-    def __init__(self, token):
-        super(TokenUpdated, self).__init__()
-        self.token = token
-
-
 class OAuth2Session(requests.Session):
     """Versatile OAuth 2 extension to :class:`requests.Session`.
 
@@ -68,10 +62,7 @@ def __init__(
         :auto_refresh_kwargs: Extra arguments to pass to the refresh token
                               endpoint.
         :token_updater: Method with one argument, token, to be used to update
-                        your token database on automatic token refresh. If not
-                        set a TokenUpdated warning will be raised when a token
-                        has been refreshed. This warning will carry the token
-                        in its token argument.
+                        your token database on automatic token refresh.
         :param kwargs: Arguments to pass to the Session constructor.
         """
         super(OAuth2Session, self).__init__(**kwargs)
@@ -534,11 +525,9 @@ def request(
                             "Updating token to %s using %s.", token, self.token_updater
                         )
                         self.token_updater(token)
-                        url, headers, data = self._client.add_token(
-                            url, http_method=method, body=data, headers=headers
-                        )
-                    else:
-                        raise TokenUpdated(token)
+                    url, headers, data = self._client.add_token(
+                        url, http_method=method, body=data, headers=headers
+                    )
                 else:
                     raise
 

tests/test_oauth2_session.py

@@ -18,7 +18,7 @@
 from oauthlib.oauth2 import MismatchingStateError
 from oauthlib.oauth2 import WebApplicationClient, MobileApplicationClient
 from oauthlib.oauth2 import LegacyApplicationClient, BackendApplicationClient
-from requests_oauthlib import OAuth2Session, TokenUpdated
+from requests_oauthlib import OAuth2Session
 import requests
 
 from requests.auth import _basic_auth_str
@@ -142,16 +142,6 @@ def fake_refresh(r, **kwargs):
             sess = OAuth2Session(client=client, token=self.expired_token)
             self.assertRaises(TokenExpiredError, sess.get, "https://i.b")
 
-        # Auto refresh but no auto update
-        for client in self.clients:
-            sess = OAuth2Session(
-                client=client,
-                token=self.expired_token,
-                auto_refresh_url="https://i.b/refresh",
-            )
-            sess.send = fake_refresh
-            self.assertRaises(TokenUpdated, sess.get, "https://i.b")
-
         # Auto refresh and auto update
         def token_updater(token):
             self.assertEqual(token, self.token)