Cleaned up comments and documentation.

Author: Josh Brandoff

app.py

@@ -1,37 +1,45 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
 from flask import Flask
 from validator import MyRequestValidator
 from core import db, oauth
 from views import yoloapi
 
 
 def create_app(settings_override=None):
+     """
+        Method for creating and initializing application.
+
+        :param settings_override: Dictionary of settings to override.
+    """
     app = Flask(__name__)
 
-    # Update configuration
+    # Update configuration.
     app.config.from_object('settings')
     app.config.from_pyfile('settings.cfg', silent=True)
     app.config.from_object(settings_override)
 
-    # Initialize extensions on the application
+    # Initialize extensions on the application.
     db.init_app(app)
     oauth.init_app(app)
     oauth._validator = MyRequestValidator()
 
-    # Register views on the application
+    # Register views on the application.
     app.register_blueprint(yoloapi)
 
     return app
 
 
 if __name__ == '__main__':
 
-    # We like flask_oauthlib logging for this application
+    # Enable Flask-OAuthlib logging for this application.
     import logging
     logger = logging.getLogger('flask_oauthlib')
     logger.addHandler(logging.StreamHandler())
     logger.setLevel(logging.DEBUG)
 
-    # Create app, create SQL schemes in db and run the application
+    # Create app and SQL schemas in database, then run the application.
     app = create_app()
     db.create_all(app=app)
     app.run()

core.py

@@ -1,5 +1,8 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
 """
-The core module holds generic functions and the flask extensions
+The core module holds generic functions and the Flask extensions.
 """
 
 from flask_sqlalchemy import SQLAlchemy

models.py

@@ -1,17 +1,30 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
 from datetime import datetime, timedelta
 from werkzeug.security import gen_salt
 from core import db
 
 
 class User(db.Model):
-    """User which owns resources behind our own api"""
+    """ User which will be querying resources from the API.
 
-    id = db.Column(db.Integer, primary_key=True)
+    :param db.Model: Base class for database models.
+    """
+    id       = db.Column(db.Integer, primary_key=True)
     username = db.Column(db.String(40), unique=True)
     password = db.Column(db.String(40))
 
     @staticmethod
     def find_with_password(username, password, *args, **kwargs):
+        """ Query the User collection for a record with matching username and password.
+        If only a username is supplied, find the first matching document with that username.
+
+        :param username: Username of the user.
+        :param password: Password of the user.
+        :param *args: Variable length argument list.
+        :param **kwargs: Arbitrary keyword arguments.
+        """
         if password:
             return User.query.filter_by(
                 username=username, password=password).first()
@@ -20,25 +33,28 @@ def find_with_password(username, password, *args, **kwargs):
 
     @staticmethod
     def save(username, password):
+        """ Create a new User record with the supplied username and password.
+
+        :param username: Username of the user.
+        :param password: Password of the user.
+        """
         user = User(username=username, password=password)
         db.session.add(user)
         db.session.commit()
 
     @staticmethod
     def all():
+        """ Return all User records found in the database. """
         return User.query.all()
 
 
 class Client(db.Model):
-    """http://tools.ietf.org/html/rfc6749#section-2
-
-    RFC 6749 Section 2 describes clients.
+    """ Client application through which user is authenticating.
 
-    One thing to note is that redirection URIs are mandatory for clients. We
-    skip this requirement as this example will only allow the resource owner
-    password credentials grant(described in section 4.3).
+    RFC 6749 Section 2 (http://tools.ietf.org/html/rfc6749#section-2) 
+    describes clients:
 
-     +----------+
+    +----------+
      | Resource |
      |  Owner   |
      |          |
@@ -56,84 +72,110 @@ class Client(db.Model):
      |         |    (w/ Optional Refresh Token)   |               |
      +---------+                                  +---------------+
 
-    In this flow the Authorization Server will not redirect the user as
-    described in subsection 3.1.2 (Redirection Endpoint).
+    Redirection URIs are mandatory for clients. We skip this requirement
+    as this example only allows the resource owner password credentials
+    grant (described in Section 4.3). In this flow, the Authorization
+    Server will not redirect the user as described in subsection 3.1.2
+    (Redirection Endpoint).
 
+    :param db.Model: Base class for database models.
     """
-
-    client_id = db.Column(db.String(40), primary_key=True)
+    client_id    d= db.Column(db.String(40), primary_key=True)
     client_type = db.Column(db.String(40))
 
     @property
     def allowed_grant_types(self):
+        """ Returns allowed grant types.
+
+        Presently, only the password grant type is allowed.
+        """
         return ['password']
 
     @property
     def default_scopes(self):
+        """ Returns default scopes associated with the Client. """
         return []
 
     @staticmethod
     def find(id):
+        """ Queries the Client table and returns first client with
+            matching id.
+
+        :param id: Client id
+        """
         return Client.query.filter_by(client_id=id).first()
 
     @staticmethod
     def generate():
+        """ Generate a new public client with the ObjectID helper."""
         client = Client(client_id=gen_salt(40), client_type='public')
         db.session.add(client)
         db.session.commit()
 
     @staticmethod
     def all():
+        """ Return all Client documents found in the database. """
         return Client.query.all()
 
     def default_redirect_uri():
+        """ Return a blank default redirect URI since we are not implementing
+            redirects. 
+        """
         return ''
 
 
 class Token(db.Model):
-    """Access or refresh token
+    """ Access or refresh token 
 
-    Note that an access token is aware about to which user and client it was
-    issued, thus we can identify which user is making a request based on this
-    token.
-    """
-
-    id = db.Column(db.Integer, primary_key=True)
-
-    client_id = db.Column(db.String(40), db.ForeignKey('client.client_id'),
-                          nullable=False)
-    client = db.relationship('Client')
-
-    user_id = db.Column(db.Integer, db.ForeignKey('user.id'))
-    user = db.relationship('User')
+        Because of our current grant flow, we are able to associate tokens
+        with the users who are requesting them. This can be used to track usage
+        and potential abuse. Only bearer tokens currently supported.
 
-    # currently only bearer is supported
-    token_type = db.Column(db.String(40))
-
-    access_token = db.Column(db.String(255), unique=True)
+        :param db.Model: Base class for database models.
+    """
+    id            = db.Column(db.Integer, primary_key=True)
+    client_id     = db.Column(db.String(40), db.ForeignKey('client.client_id'), nullable=False)
+    client        = db.relationship('Client')
+    user_id       = db.Column(db.Integer, db.ForeignKey('user.id'))
+    user          = db.relationship('User')
+    token_type    = db.Column(db.String(40))
+    access_token  = db.Column(db.String(255), unique=True)
     refresh_token = db.Column(db.String(255), unique=True)
-    expires = db.Column(db.DateTime)
-    scopes = ['']
+    expires       = db.Column(db.DateTime)
+    scopes        = ['']
 
     @staticmethod
     def find(access_token=None, refresh_token=None):
+        """ Retrieve a token record using submitted access token or 
+        refresh token.
+
+        :param access_token: User access token.
+        :param refresh_token: User refresh token.
+        """
         if access_token:
             return Token.query.filter_by(access_token=access_token).first()
         elif refresh_token:
             return Token.query.filter_by(refresh_token=refresh_token).first()
 
     @staticmethod
     def save(token, request, *args, **kwargs):
+        """ Save a new token to the database.
+
+        :param token: Token dictionary containing access and refresh tokens, plus token type.
+        :param request: Request dictionary containing information about the client and user.
+        :param *args: Variable length argument list.
+        :param **kwargs: Arbitrary keyword arguments.  
+        """
         toks = Token.query.filter_by(
             client_id=request.client.client_id,
             user_id=request.user.id)
 
-        # Make sure that there is only one Grant Token for every
+        # Make sure that there is only one grant token for every
         # (client, user) combination.
         [db.session.delete(t) for t in toks]
 
         expires_in = token.pop('expires_in')
-        expires = datetime.utcnow() + timedelta(seconds=expires_in)
+        expires    = datetime.utcnow() + timedelta(seconds=expires_in)
 
         tok = Token(
             access_token=token['access_token'],

validator.py

@@ -1,13 +1,16 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
 from flask_oauthlib.provider import OAuth2RequestValidator
 from models import User, Client, Token
 
 
 class MyRequestValidator(OAuth2RequestValidator):
-    """
-    To understand the reason purpose of this class read
-    http://flask-oauthlib.readthedocs.org/en/latest/api.html#flask_oauthlib.provider.OAuth2RequestValidator
-    """
+    """ Defines a custom OAuth2 Request Validator based on the Client, User
+	and Token models.
 
+	:param OAuth2RequestValidator: Overrides the OAuth2RequestValidator.
+	"""
     def __init__(self):
         self._clientgetter = Client.find
         self._usergetter = User.find_with_password

views.py

@@ -1,32 +1,35 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
 from flask import Blueprint, render_template, request
 from models import Client, User
 from core import oauth
 
 yoloapi = Blueprint('yoloApi', __name__)
 
-
-# set endpoint for token handler
 @yoloapi.route('/oauth/token', methods=['POST'])
 @oauth.token_handler
 def access_token(*args, **kwargs):
-    # Returns a dictionary or None as the extra credentials
-    # for creating the token response.
-    return None
+    """ This endpoint is for exchanging/refreshing an access token.
 
+    Returns a dictionary or None as the extra credentials for creating the token response.
+
+    :param *args: Variable length argument list.
+    :param **kwargs: Arbitrary keyword arguments.
+    """
+    return None
 
-# This is our little mangement interface for creating test users and clients
 @yoloapi.route('/', methods=['GET', 'POST'])
 def management():
+    """ This endpoint is for vieweing and adding users and clients. """
     if request.method == 'POST' and request.form['submit'] == 'adduser':
         User.save(request.form['username'], request.form['password'])
     if request.method == 'POST' and request.form['submit'] == 'addclient':
         Client.generate()
-    return render_template('management.html', users=User.all(),
-                           clients=Client.all())
-
+    return render_template('management.html', users=User.all(), clients=Client.all())
 
-# The resource we are trying to protect
 @yoloapi.route('/yolo')
 @oauth.require_oauth()
 def yolo():
-    return "YOLO!!! You made it through and accessed the protected resource"
+    """ This is an example endpoint we are trying to protect. """
+    return "YOLO! Congraulations, you made it through and accessed the protected resource!"