Minor documentation updates

Author: Landon Gilbert-Bland

README.md

@@ -1,13 +1,13 @@
 # Flask-JWT-Extended
 
 ### Features
-Flask-JWT-Extended not only adds support for using JSON Web Tokens (JWT) to Flask for protecting views,
+Flask-JWT-Extended not only adds support for using JSON Web Tokens (JWT) to Flask for protecting routes,
 but also many helpful (and **optional**) features  built in to make working with JSON Web Tokens
 easier. These include:
 
 * Adding custom claims to JSON Web Tokens
-* Custom claims validation on received tokens
 * Automatic user loading (`current_user`).
+* Custom claims validation on received tokens
 * [Refresh tokens](https://auth0.com/blog/refresh-tokens-what-are-they-and-when-to-use-them/)
 * First class support for fresh tokens for making sensitive changes.
 * Token revoking/blocklisting

docs/v4_upgrade_guide.rst

@@ -3,11 +3,10 @@
 This release includes a lot of breaking changes that have been a long time coming,
 and will require some manual intervention to upgrade your application. Breaking
 changes are never fun, but I really believe they are for the best. As a result
-of all these breaking changes, this extension should be simpiler to use,
-provide more flexibility, and allow for easier additions to the API without
-introducing further breaking changes in the future. Here are all the breaking
-changes that might affect your flask application when upgrading to 4.0.0.
-
+of all these changes, this extension should be simpler to use, provide more
+flexibility, and allow for easier additions to the API without introducing
+further breaking changes. Here is everything you will need to be aware of when
+upgrading to 4.0.0.
 
 Encoded JWT Changes (IMPORTANT)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -125,3 +124,11 @@ API Changes
   will now always be put in the JWT regardless of if it is an access or refresh
   tokens. If you don't want additional claims in your refresh tokens, do not
   include any additional claims when creating the refresh token.
+
+New Stuff
+~~~~~~~~~
+- Add ``locations`` argument to ``@jwt_required()`` and ``verify_jwt_in_request``.
+  This will allow you to override the ``JWT_LOCATIONS`` option on a per route basis.
+- Revamped and cleaned up documentation. It should be clearer how to work with this
+  extension both on the backend and frontend now.
+- Lots of code cleanup behind the scenes.

flask_jwt_extended/jwt_manager.py

@@ -207,7 +207,7 @@ def additional_claims_loader(self, callback):
         """
         This decorator sets the callback function used to add additional claims
         when creating a JWT. The claims returned by this function will be merged
-        with any claims passed in via the `additional_claims` argument to
+        with any claims passed in via the ``additional_claims`` argument to
         :func:`~flask_jwt_extended.create_access_token` or
         :func:`~flask_jwt_extended.create_refresh_token`.
 
@@ -224,7 +224,7 @@ def additional_headers_loader(self, callback):
         """
         This decorator sets the callback function used to add additional headers
         when creating a JWT. The headers returned by this function will be merged
-        with any headers passed in via the `additional_headers` argument to
+        with any headers passed in via the ``additional_headers`` argument to
         :func:`~flask_jwt_extended.create_access_token` or
         :func:`~flask_jwt_extended.create_refresh_token`.
 
@@ -311,7 +311,7 @@ def needs_fresh_token_loader(self, callback):
         """
         This decorator sets the callback function for returning a custom
         response when a valid and non-fresh token is used on an endpoint
-        that is marked as `fresh=True`.
+        that is marked as ``fresh=True``.
 
         The decorated function must take **two** arguments.
 
@@ -351,8 +351,8 @@ def token_in_blocklist_loader(self, callback):
 
         The second argument is a dictionary containing the payload data of the JWT.
 
-        The decorated function must be return `True` if the token has been
-        revoked, `False` otherwise.
+        The decorated function must be return ``True`` if the token has been
+        revoked, ``False`` otherwise.
         """
         self._token_in_blocklist_callback = callback
         return callback
@@ -384,8 +384,8 @@ def token_verification_loader(self, callback):
 
         The second argument is a dictionary containing the payload data of the JWT.
 
-        The decorated function must return `True` if the token is valid, or
-        `False` otherwise.
+        The decorated function must return ``True`` if the token is valid, or
+        ``False`` otherwise.
         """
         self._token_verification_callback = callback
         return callback
@@ -439,7 +439,7 @@ def user_lookup_loader(self, callback):
 
         The decorated function can return any python object, which can then be
         accessed in a protected endpoint. If an object cannot be loaded, for
-        example if a user has been deleted from your database, `None` must be
+        example if a user has been deleted from your database, ``None`` must be
         returned to indicate that an error occurred loading the user.
         """
         self._user_lookup_callback = callback

flask_jwt_extended/utils.py

@@ -14,7 +14,7 @@ def get_jwt():
     """
     In a protected endpoint, this will return the python dictionary which has
     the payload of the JWT that is accessing the endpoint. If no JWT is present
-    due to `jwt_required(optional=True)`, an empty dictionary is returned.
+    due to ``jwt_required(optional=True)``, an empty dictionary is returned.
 
     :return:
         The payload (claims) of the JWT in the current request
@@ -32,7 +32,7 @@ def get_jwt_header():
     """
     In a protected endpoint, this will return the python dictionary which has
     the header of the JWT that is accessing the endpoint. If no JWT is present
-    due to `jwt_required(optional=True)`, an empty dictionary is returned.
+    due to ``jwt_required(optional=True)``, an empty dictionary is returned.
 
     :return:
         The headers of the JWT in the current request
@@ -50,7 +50,7 @@ def get_jwt_identity():
     """
     In a protected endpoint, this will return the identity of the JWT that is
     accessing the endpoint. If no JWT is present due to
-    `jwt_required(optional=True)`, `None` is returned.
+    ``jwt_required(optional=True)``, ``None`` is returned.
 
     :return:
         The identity of the JWT in the current request
@@ -67,7 +67,7 @@ def get_current_user():
     is configured. If the user loader callback is not being used, this will
     raise an error.
 
-    If no JWT is present due to `jwt_required(optional=True)`, `None` is returned.
+    If no JWT is present due to ``jwt_required(optional=True)``, ``None`` is returned.
 
     :return:
         The current user object for the JWT in the current request
@@ -97,7 +97,7 @@ def decode_token(encoded_token, csrf_value=None, allow_expired=False):
         Expected CSRF double submit value (optional).
 
     :param allow_expired:
-        If `True`, do not raise an error if the JWT is expired.  Defaults to `False`
+        If ``True``, do not raise an error if the JWT is expired.  Defaults to ``False``
 
     :return:
         Dictionary containing the payload of the JWT decoded JWT.
@@ -124,15 +124,15 @@ def create_access_token(
 
     :param fresh:
         If this token should be marked as fresh, and can thus access endpoints
-        protected with `@jwt_required(fresh=True)`. Defaults to `False`.
+        protected with ``@jwt_required(fresh=True)``. Defaults to ``False``.
 
-        This value can also be a `datetime.timedelta`, which indicate
+        This value can also be a ``datetime.timedelta``, which indicate
         how long this token will be considered fresh.
 
     :param expires_delta:
-        A `datetime.timedelta` for how long this token should last before it
+        A ``datetime.timedelta`` for how long this token should last before it
         expires. Set to False to disable expiration. If this is None, it will use
-        the 'JWT_ACCESS_TOKEN_EXPIRES` config value (see :ref:`Configuration Options`)
+        the ``JWT_ACCESS_TOKEN_EXPIRES`` config value (see :ref:`Configuration Options`)
 
     :param additional_claims:
         Optional. A hash of claims to include in the access token.  These claims are
@@ -173,9 +173,9 @@ def create_refresh_token(
         serializable format.
 
     :param expires_delta:
-        A `datetime.timedelta` for how long this token should last before it expires.
+        A ``datetime.timedelta`` for how long this token should last before it expires.
         Set to False to disable expiration. If this is None, it will use the
-        'JWT_REFRESH_TOKEN_EXPIRES` config value (see :ref:`Configuration Options`)
+        ``JWT_REFRESH_TOKEN_EXPIRES`` config value (see :ref:`Configuration Options`)
 
     :param additional_claims:
         Optional. A hash of claims to include in the refresh token. These claims are
@@ -246,7 +246,7 @@ def get_csrf_token(encoded_token):
 def set_access_cookies(response, encoded_access_token, max_age=None):
     """
     Modifiy a Flask Response to set a cookie containing the access JWT.
-    Also sets the corresponding CSRF cookies if `JWT_CSRF_IN_COOKIES` is `True`
+    Also sets the corresponding CSRF cookies if ``JWT_CSRF_IN_COOKIES`` is ``True``
     (see :ref:`Configuration Options`)
 
     :param response:
@@ -257,8 +257,8 @@ def set_access_cookies(response, encoded_access_token, max_age=None):
 
     :param max_age:
         The max age of the cookie. If this is None, it will use the
-        `JWT_SESSION_COOKIE` option (see :ref:`Configuration Options`). Otherwise,
-        it will use this as the cookies `max-age` and the JWT_SESSION_COOKIE option
+        ``JWT_SESSION_COOKIE`` option (see :ref:`Configuration Options`). Otherwise,
+        it will use this as the cookies ``max-age`` and the JWT_SESSION_COOKIE option
         will be ignored. Values should be the number of seconds (as an integer).
     """
     response.set_cookie(
@@ -288,7 +288,7 @@ def set_access_cookies(response, encoded_access_token, max_age=None):
 def set_refresh_cookies(response, encoded_refresh_token, max_age=None):
     """
     Modifiy a Flask Response to set a cookie containing the refresh JWT.
-    Also sets the corresponding CSRF cookies if `JWT_CSRF_IN_COOKIES` is `True`
+    Also sets the corresponding CSRF cookies if ``JWT_CSRF_IN_COOKIES`` is ``True``
     (see :ref:`Configuration Options`)
 
     :param response:
@@ -299,8 +299,8 @@ def set_refresh_cookies(response, encoded_refresh_token, max_age=None):
 
     :param max_age:
         The max age of the cookie. If this is None, it will use the
-        `JWT_SESSION_COOKIE` option (see :ref:`Configuration Options`). Otherwise,
-        it will use this as the cookies `max-age` and the JWT_SESSION_COOKIE option
+        ``JWT_SESSION_COOKIE`` option (see :ref:`Configuration Options`). Otherwise,
+        it will use this as the cookies ``max-age`` and the JWT_SESSION_COOKIE option
         will be ignored. Values should be the number of seconds (as an integer).
     """
     response.set_cookie(

flask_jwt_extended/view_decorators.py

@@ -35,25 +35,25 @@ def _verify_token_is_fresh(jwt_header, jwt_data):
 
 def verify_jwt_in_request(optional=False, fresh=False, refresh=False, locations=None):
     """
-    Verify that a valid JWT is present in the request, unless `optional=True` in
+    Verify that a valid JWT is present in the request, unless ``optional=True`` in
     which case no JWT is also considered valid.
 
     :param optional:
-        If `True`, do not raise an error if no JWT is present in the request.
-        Defaults to `False`.
+        If ``True``, do not raise an error if no JWT is present in the request.
+        Defaults to ``False``.
 
     :param fresh:
-        If `True`, require a JWT marked as `fresh` in order to be verified.
-        Defaults to `False`.
+        If ``True``, require a JWT marked as ``fresh`` in order to be verified.
+        Defaults to ``False``.
 
     :param refresh:
-        If `True`, require a refresh JWT to be verified. If `False` require an access
-        JWT to be verified. Defaults to `False`.
+        If ``True``, require a refresh JWT to be verified. If ``False`` require an access
+        JWT to be verified. Defaults to ``False``.
 
     :param locations:
         A list of locations to look for the JWT in this request, for example:
-        `['headers', 'cookies']`. Defaluts to `None` which indicates that JWTs
-        will be looked for in the locations defined by the `JWT_TOKEN_LOCATION`
+        ``['headers', 'cookies']``. Defaluts to ``None`` which indicates that JWTs
+        will be looked for in the locations defined by the ``JWT_TOKEN_LOCATION``
         configuration option.
     """
     if request.method in config.exempt_methods:
@@ -90,21 +90,21 @@ def jwt_required(optional=False, fresh=False, refresh=False, locations=None):
     endpoint can be called.
 
     :param optional:
-        If `True`, allow the decorated endpoint to be if no JWT is present in the
-        request. Defaults to `False`.
+        If ``True``, allow the decorated endpoint to be if no JWT is present in the
+        request. Defaults to ``False``.
 
     :param fresh:
-        If `True`, require a JWT marked with `fresh` to be able to access this
-        endpoint. Defaults to `False`.
+        If ``True``, require a JWT marked with ``fresh`` to be able to access this
+        endpoint. Defaults to ``False``.
 
     :param refresh:
-        If `True`, requires a refresh JWT to access this endpoint. If `False`,
-        requires an access JWT to access this endpoint. Defaults to `False`.
+        If ``True``, requires a refresh JWT to access this endpoint. If ``False``,
+        requires an access JWT to access this endpoint. Defaults to ``False``.
 
     :param locations:
         A list of locations to look for the JWT in this request, for example:
-        `['headers', 'cookies']`. Defaluts to `None` which indicates that JWTs
-        will be looked for in the locations defined by the `JWT_TOKEN_LOCATION`
+        ``['headers', 'cookies']``. Defaluts to ``None`` which indicates that JWTs
+        will be looked for in the locations defined by the ``JWT_TOKEN_LOCATION``
         configuration option.
     """