Finish updating existing documentation

Author: Landon Gilbert-Bland

docs/changing_default_behavior.rst

@@ -1,90 +1,15 @@
 Changing Default Behaviors
 ==========================
 
-NOTE: THIS DOCUMENTATION HAS NOT YET BEEN UPDATED
-
-
-Changing callback functions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-We provide what we think are sensible behaviors when attempting to access a
-protected endpoint. If the access token is not valid for any reason (missing,
-expired, tampered with, etc) we will return json in the format of {'msg': 'why
-accessing endpoint failed'} along with an appropriate http status code
-(generally 401 or 422). However, you may want to customize what you return in
-some situations. We can do that with the jwt_manager loader functions.
-
+This extension provides sensible default behaviors. For example, if an expired
+token attempts to access a protected endpoint, you will get a JSON response back
+like ``{"msg": "Token has expired"}`` and a 401 status code. However there may
+be various behaviors of this extension that you want to customize to your
+application's needs. We can do that with the various loader functions. Here is
+an example of how to do that.
 
 .. literalinclude:: ../examples/loaders.py
 
-Here are the possible loader functions. Click on the links for a more
-more details about what arguments your callback functions should expect
-and what the return values of your callback functions need to be.
-
-.. list-table::
-    :header-rows: 1
-
-    * - Loader Decorator
-      - Description
-    * - :meth:`~flask_jwt_extended.JWTManager.token_verification_loader`
-      - Function that is called to do additional verifcations on the jwt data. Must return True or False
-    * - :meth:`~flask_jwt_extended.JWTManager.token_verification_failed_loader`
-      - Function that is called when the user claims verification callback returns False
-    * - :meth:`~flask_jwt_extended.JWTManager.decode_key_loader`
-      - Function that is called to get the decode key before verifying a token
-    * - :meth:`~flask_jwt_extended.JWTManager.encode_key_loader`
-      - Function that is called to get the encode key before creating a token
-    * - :meth:`~flask_jwt_extended.JWTManager.expired_token_loader`
-      - Function to call when an expired token accesses a protected endpoint
-    * - :meth:`~flask_jwt_extended.JWTManager.invalid_token_loader`
-      - Function to call when an invalid token accesses a protected endpoint
-    * - :meth:`~flask_jwt_extended.JWTManager.needs_fresh_token_loader`
-      - Function to call when a non-fresh token accesses a :func:`~flask_jwt_extended.jwt_required` endpoint
-    * - :meth:`~flask_jwt_extended.JWTManager.revoked_token_loader`
-      - Function to call when a revoked token accesses a protected endpoint
-    * - :meth:`~flask_jwt_extended.JWTManager.token_in_blocklist_loader`
-      - Function that is called to check if a token has been revoked
-    * - :meth:`~flask_jwt_extended.JWTManager.unauthorized_loader`
-      - Function to call when a request with no JWT accesses a protected endpoint
-    * - :meth:`~flask_jwt_extended.JWTManager.user_lookup_loader`
-      - Function to call to load a user object when token accesses a protected endpoint
-    * - :meth:`~flask_jwt_extended.JWTManager.user_lookup_error_loader`
-      - Function that is called when the user_lookup callback function returns `None`
-
-Dynamic token expires time
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can also change the expires time for a token via the `expires_delta` kwarg
-in the :func:`~flask_jwt_extended.create_refresh_token` and
-:func:`~flask_jwt_extended.create_access_token` functions. This takes
-a `datetime.timedelta` and overrides the `JWT_REFRESH_TOKEN_EXPIRES` and
-`JWT_ACCESS_TOKEN_EXPIRES` settings (see :ref:`Configuration Options`).
-
-This can be useful if you have different use cases for different tokens.
-For example, you might use short lived access tokens used in your web
-application, but you allow the creation of long lived access tokens that other
-developers can generate and use to interact with your api in their programs.
-You could accomplish this like such:
-
-.. code-block:: python
-
-  @app.route('/create-dev-token', methods=['POST'])
-  @jwt_required
-  def create_dev_token():
-      username = get_jwt_identity()
-      expires = datetime.timedelta(days=365)
-      token = create_access_token(username, expires_delta=expires)
-      return jsonify({'token': token}), 201
-
-You can even disable expiration by setting `expires_delta` to `False`:
-
-.. code-block:: python
-
-  @app.route('/create-api-token', methods=['POST'])
-  @jwt_required
-  def create_api_token():
-      username = get_jwt_identity()
-      token = create_access_token(username, expires_delta=False)
-      return jsonify({'token': token}), 201
-
-Note that in this case, you should enable token revoking (see :ref:`Blocklist and Token Revoking`).
+There are all sorts of callbacks that can be defined to customize the behaviors
+of this extension. See the :ref:`Configuring Flask-JWT-Extended` API Documentation
+for a full list of callback functions that are available in this extension.

docs/index.rst

@@ -6,31 +6,6 @@
 Flask-JWT-Extended's Documentation
 ==================================
 
-..
-    - Installation
-    - Basic Usage
-    - Automatic User Loading
-    - Adding claims to JWTs
-    - Optional Endpoints
-    - Token Locations
-      - Headers
-      - Cookies
-      - JSON Body
-      - Query String
-      - locations kwarg for decorator
-    - Refresh Tokens
-      - Implict refreshing with cookies
-        - Prefered for browsers
-      - Explict refreshing with refresh tokesn
-        - Prefered for non-browsers
-    - Fresh Token pattern
-      - Here or coupled with refresh tokens?
-    - Blocklist and Token Revoking
-    - Configuratino Options
-    - Modifying Behaviors with Callback Functions
-    - Custom Decorators
-    - API Documentation
-
 .. toctree::
    :maxdepth: 2
 

docs/options.rst

@@ -36,6 +36,9 @@ General Options:
     If set to ``False`` tokens will never expire. **This is dangerous and should
     be avoided in most case**
 
+    This can be overridden on a per token basis by passing the ``expires_delta``
+    argument to :func:`flask_jwt_extended.create_access_token`
+
     Default: ``datetime.timedelta(minutes=15)``
 
 
@@ -49,6 +52,9 @@ General Options:
     If set to ``False`` tokens will never expire. **This is dangerous and should
     be avoided in most case**
 
+    This can be overridden on a per token basis by passing the ``expires_delta``
+    argument to :func:`flask_jwt_extended.create_refresh_token`
+
     Default: ``datetime.timedelta(days=30)``
 
 

examples/loaders.py

@@ -1,6 +1,5 @@
 from flask import Flask
 from flask import jsonify
-from flask import request
 
 from flask_jwt_extended import create_access_token
 from flask_jwt_extended import jwt_required
@@ -12,39 +11,26 @@
 jwt = JWTManager(app)
 
 
-# Using the expired_token_loader decorator, we will now call
-# this function whenever an expired but otherwise valid access
-# token attempts to access an endpoint
+# Set a callback function to return a custom response whenever an expired
+# token attempts to access a protected route. This particular callback function
+# takes the jwt_header and jwt_payload as arguments, and must return a Flask
+# response. Check the API documentation to see the required argument and return
+# values for other callback functions.
 @jwt.expired_token_loader
-def my_expired_token_callback(expired_token):
-    token_type = expired_token["type"]
-    return (
-        jsonify(
-            {
-                "status": 401,
-                "sub_status": 42,
-                "msg": "The {} token has expired".format(token_type),
-            }
-        ),
-        401,
-    )
+def my_expired_token_callback(jwt_header, jwt_payload):
+    return jsonify(code="dave", err="I can't let you do that"), 401
 
 
 @app.route("/login", methods=["POST"])
 def login():
-    username = request.json.get("username", None)
-    password = request.json.get("password", None)
-    if username != "test" or password != "test":
-        return jsonify({"msg": "Bad username or password"}), 401
-
-    ret = {"access_token": create_access_token(username)}
-    return jsonify(ret), 200
+    access_token = create_access_token("example_user")
+    return jsonify(access_token=access_token)
 
 
 @app.route("/protected", methods=["GET"])
 @jwt_required
 def protected():
-    return jsonify({"hello": "world"}), 200
+    return jsonify(hello="world")
 
 
 if __name__ == "__main__":