Working on the docs

Author: vimalloc

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "docs/_themes"]
+	path = docs/_themes
+	url = https://github.com/pallets/flask-sphinx-themes.git

docs/_themes

@@ -1,53 +1,16 @@
 Adding Custom Data (Claims) to the Access Token
 ===============================================
 
-You may want to store additional information in the access token. Perhaps you want to save the access roles this user has so you can access them in the view functions (without having to make a database call each time). This can be done with the user_claims_loader decorator, and accessed later with the 'get_jwt_claims()' method (in a protected endpoint).
-
-
-.. code-block:: python
-
-  from flask import Flask, jsonify, request
-  from flask_jwt_extended import JWTManager, jwt_required, create_access_token, \
-      get_jwt_claims
-
-  app = Flask(__name__)
-  app.secret_key = 'super-secret'  # Change this!
-  jwt = JWTManager(app)
-
-
-  # Using the user_claims_loader, we can specify a method that will be called
-  # when creating access tokens, and add these claims to the said token. This
-  # method is passed the identity of who the token is being created for, and
-  # must return data that is json serializable
-  @jwt.user_claims_loader
-  def add_claims_to_access_token(identity):
-      return {
-          'hello': identity,
-          'foo': ['bar', 'baz']
-      }
-
-
-  @app.route('/login', methods=['POST'])
-  def login():
-      username = request.json.get('username', None)
-      password = request.json.get('password', None)
-      if username != 'test' and password != 'test':
-          return jsonify({"msg": "Bad username or password"}), 401
-
-      ret = {'access_token': create_access_token(username)}
-      return jsonify(ret), 200
-
-
-  # In a protected view, get the claims you added to the jwt with the
-  # get_jwt_claims() method
-  @app.route('/protected', methods=['GET'])
-  @jwt_required
-  def protected():
-      claims = get_jwt_claims()
-      return jsonify({
-          'hello_is': claims['hello'],
-          'foo_is': claims['foo']
-      }), 200
-
-  if __name__ == '__main__':
-      app.run()
+You may want to store additional information in the access token. Perhaps you
+want to save the permissions this user has so you can access them in the view
+functions, without having to make a database call each time. This can be done
+with the user_claims_loader decorator, and accessed later with the
+'get_jwt_claims()' method (in a protected endpoint).
+
+.. literalinclude:: ../examples/additional_data_in_access_token.py
+
+Storing data in an access token can be good for performance. If you store data
+in the token, you wont need to look it up from disk next time you need it in
+a protected endpoint. But be warned, any data in the access token can be easily
+viewed with anyone who has access to said token, so refrain from storing
+critical data there!

docs/add_custom_data_claims.rst

@@ -5,45 +5,10 @@ Basic Usage
 In its simplest form, there is not much to using flask_jwt_extended.
 
 
-.. code-block :: python
-
-  from flask import Flask, jsonify, request
-  from flask_jwt_extended import JWTManager, jwt_required, create_access_token
-
-  app = Flask(__name__)
-  app.secret_key = 'super-secret'  # Change this!
-
-  # Setup the Flask-JWT-Extended extension
-  jwt = JWTManager(app)
-
-
-  # Provide a method to create access tokens. The create_access_token() function
-  # is used to actually generate the token
-  @app.route('/login', methods=['POST'])
-  def login():
-    username = request.json.get('username', None)
-    password = request.json.get('password', None)
-    if username != 'test' and password != 'test':
-        return jsonify({"msg": "Bad username or password"}), 401
-
-    ret = {'access_token': create_access_token(username)}
-    return jsonify(ret), 200
-
-
-  # Protect a view with jwt_required, which requires a valid access token in the
-  # request to access.
-  @app.route('/protected', methods=['GET'])
-  @jwt_required
-  def protected():
-    return jsonify({'hello': 'world'}), 200
-
-  if __name__ == '__main__':
-    app.run()
-
+.. literalinclude:: ../examples/simple.py
 
 To access a jwt_required protected view, all we have to do is send an authorization head with the request that include the token. The header looks like this:
 
-
 .. code-block :: bash
 
   Authorization: Bearer <access_token>
@@ -53,22 +18,20 @@ We can see this in action using CURL:
 
 .. code-block :: bash
 
-  $ curl --write-out "%{http_code}\n"  http://localhost:5000/protected
+  $ curl http://localhost:5000/protected
   {
     "msg": "Missing Authorization Header"
   }
-  401
 
-  $ curl --write-out "%{http_code}\n" -H "Content-Type: application/json" -X POST -d '{"username":"test","password":"test"}' http://localhost:5000/login
+  $ curl -H "Content-Type: application/json" -X POST \
+    -d '{"username":"test","password":"test"}' http://localhost:5000/login
   {
     "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmcmVzaCI6dHJ1ZSwianRpIjoiZjhmNDlmMjUtNTQ4OS00NmRjLTkyOWUtZTU2Y2QxOGZhNzRlIiwidXNlcl9jbGFpbXMiOnt9LCJuYmYiOjE0NzQ0NzQ3OTEsImlhdCI6MTQ3NDQ3NDc5MSwiaWRlbnRpdHkiOiJ0ZXN0IiwiZXhwIjoxNDc0NDc1NjkxLCJ0eXBlIjoiYWNjZXNzIn0.vCy0Sec61i9prcGIRRCbG8e9NV6_wFH2ICFgUGCLKpc"
   }
-  200
 
   $ export ACCESS="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmcmVzaCI6dHJ1ZSwianRpIjoiZjhmNDlmMjUtNTQ4OS00NmRjLTkyOWUtZTU2Y2QxOGZhNzRlIiwidXNlcl9jbGFpbXMiOnt9LCJuYmYiOjE0NzQ0NzQ3OTEsImlhdCI6MTQ3NDQ3NDc5MSwiaWRlbnRpdHkiOiJ0ZXN0IiwiZXhwIjoxNDc0NDc1NjkxLCJ0eXBlIjoiYWNjZXNzIn0.vCy0Sec61i9prcGIRRCbG8e9NV6_wFH2ICFgUGCLKpc"
 
-  $ curl --write-out "%{http_code}\n" -H "Authorization: Bearer $ACCESS" http://localhost:5000/protected
+  $ curl -H "Authorization: Bearer $ACCESS" http://localhost:5000/protected
   {
     "hello": "world"
   }
-  200

docs/basic_usage.rst

@@ -1,60 +1,36 @@
 Changing Default Behaviors
 ==========================
 
-
-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 returned in these situations. We can do that with the jwt_manager _loader functions.
-
-
-.. code-block:: python
-
-  from flask import Flask, jsonify, request
-  from flask_jwt_extended import JWTManager, jwt_required, create_access_token
-
-  app = Flask(__name__)
-  app.secret_key = 'super-secret'  # Change this!
-  jwt = JWTManager(app)
-
-
-  # Use the expired_token_loader to call this function whenever an expired but
-  # otherwise valid access token tries to access an endpoint
-  @jwt.expired_token_loader
-  def my_expired_token_callback():
-      return jsonify({
-          'status': 401,
-          'sub_status': 101,
-          'msg': 'The token has expired'
-      }), 200
-
-
-  @app.route('/login', methods=['POST'])
-  def login():
-      username = request.json.get('username', None)
-      password = request.json.get('password', None)
-      if username != 'test' and password != 'test':
-          return jsonify({"msg": "Bad username or password"}), 401
-
-      ret = {'access_token': create_access_token(username)}
-      return jsonify(ret), 200
-
-
-  @app.route('/protected', methods=['GET'])
-  @jwt_required
-  def protected():
-      return jsonify({'hello': 'world'}), 200
-
-  if __name__ == '__main__':
-      app.run()
-
-
-
-************************************
-Loader functions are:
-************************************
-
-.. autoclass:: flask_jwt_extended.jwt_manager.JWTManager
-  :members:
-..
-.. .. literalinclude:: ../flask_jwt_extended/jwt_manager.py
-..   :language: python
-..   :emphasize-lines: 60-122
-..   :linenos:
+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 returned in
+these situations. We can do that with the jwt_manager loader functions.
+
+
+.. literalinclude:: ../examples/loaders.py
+
+Possible loader functions are:
+
+.. list-table::
+    :header-rows: 1
+
+    * - Decorator
+      - Description
+      - Callback Function Arguments
+    * - expired_token_loader
+      - Function to call when an expired token accesses a protected view
+      - None
+    * - invalid_token_loader
+      - Function to call when an invalid token accesses a protected view
+      - One argument: error string of why it is invalid
+    * - unauthorized_loader
+      - Function to call when a request with no JWT accesses a protected view
+      - None
+    * - needs_fresh_token_loader
+      - Function to call when a non-fresh token tries to access a **fresh_jwt_required** view
+      - None
+    * - revoked_token_loader
+      - Function to call when a revoked token accesses a protected view
+      - None

docs/changing_default_behavior.rst

@@ -1,6 +1,5 @@
 # -*- coding: utf-8 -*-
 #
-import sphinx_rtd_theme
 import sys, os
 # flask-jwt-extended documentation build configuration file, created by
 # sphinx-quickstart on Thu Oct  6 13:07:36 2016.
@@ -20,12 +19,9 @@
 #
 
 
-# sys.path.insert(0, os.path.abspath('.'))
 sys.path.insert(0, os.path.abspath('../../..'))
 sys.path.insert(0, os.path.abspath('../flask_jwt_extended/'))
-# sys.path.insert(0, os.path.abspath('../../flask-jwt-extended/flask_jwt_extended/'))
-
-print sys.path
+sys.path.append(os.path.join(os.path.dirname(__file__), '_themes'))
 
 # -- General configuration ------------------------------------------------
 
@@ -114,7 +110,7 @@
 # show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+# pygments_style = 'sphinx'
 
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
@@ -131,7 +127,8 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+#html_theme = 'sphinx_rtd_theme'
+html_theme = 'flask'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/conf.py

@@ -1,5 +1,5 @@
 Configuration Options
-======================
+=====================
 
 .. literalinclude:: ../flask_jwt_extended/config.py
   :language: python

docs/options.rst

@@ -1,56 +1,12 @@
 Refresh Tokens
 ==============
 
-Flask-JWT-Extended supports refresh tokens out of the box. These are longer lived token which cannot access a jwt_required protected endpoint, but can be used to create new access tokens once an old access token has expired. By setting the access tokens to a shorter lifetime (see Options below), and utilizing fresh tokens for critical views (see Fresh Tokens below) we can help reduce the damage done if an access token is stolen. Here is an example of how you might use them in your application:
+Flask-JWT-Extended supports refresh tokens out of the box. These are longer
+lived token which cannot access a jwt_required protected endpoint, but can be
+used to create new access tokens once an old access token has expired.
 
+.. literalinclude:: ../examples/refresh_tokens.py
 
-.. code-block:: python
-
-  from flask import Flask, jsonify, request
-  from flask_jwt_extended import JWTManager, jwt_required, create_access_token, \
-      jwt_refresh_token_required, create_refresh_token, get_jwt_identity
-
-  app = Flask(__name__)
-  app.secret_key = 'super-secret'  # Change this!
-  jwt = JWTManager(app)
-
-
-  @app.route('/login', methods=['POST'])
-  def login():
-      username = request.json.get('username', None)
-      password = request.json.get('password', None)
-      if username != 'test' and password != 'test':
-          return jsonify({"msg": "Bad username or password"}), 401
-
-      # Use create_access_token() and create_refresh_token() to create our
-      # access and refresh tokens
-      ret = {
-          'access_token': create_access_token(identity=username),
-          'refresh_token': create_refresh_token(identity=username)
-      }
-      return jsonify(ret), 200
-
-
-  # The jwt_refresh_token_required decorator insures a valid refresh token is
-  # present in the request before calling this endpoint. We can use the
-  # get_jwt_identity() function to get the identity of the refresh toke, and use
-  # the create_access_token() function again to make a new access token for this
-  # identity.
-  @app.route('/refresh', methods=['POST'])
-  @jwt_refresh_token_required
-  def refresh():
-      current_user = get_jwt_identity()
-      ret = {
-          'access_token': create_access_token(identity=current_user)
-      }
-      return jsonify(ret), 200
-
-
-  @app.route('/protected', methods=['GET'])
-  @jwt_required
-  def protected():
-      username = get_jwt_identity()
-      return jsonify({'hello': 'from {}'.format(username)}), 200
-
-  if __name__ == '__main__':
-      app.run()
+By setting the access tokens to a shorter lifetime (see Configuration Options),
+and utilizing fresh tokens for critical views (see Token Freshness next) we can
+help reduce the damage done if an access token is stolen.