Routing (Account Routes)

This guide will be explaining the concept of routing by going through a file. We will be using `app/account/views.py`

All routes are decorated with the name of the associated Blueprint along

with the .route prop with attributes of (name, methods=[]). For example

`@account.route('/login', method=['GET', 'POST'])` creates a route accessible

at `yourdomain.com/account/login`.

This route can accept either `POST` or `GET`

requests which is appropriate since there is a form associated with the

login process. This form is loaded from the forms.py file (in this case

the `LoginForm()` is loaded) and we then check if the form is valid

(`validate_on_submit`) in that it is a valid POST request.

We grab the form field named 'email' and query the User database for the

user that has that email. Then we call the `verify_password` method

from the User class for this specific user instance and check the hashed

password in the database against the password provided by the user which

is hashed with the SECRET_KEY. If everything is fine, the Flask-login

extendion performs a login_user action and sets the `SESSION['user_id']`

equivalent to the user id provided from the user instance. If the

form has remember_me set to True (ie checked) then that is passed along

as a parameter in login_user.

If it was redirected to this /login page, their URL will have a parameter

called `next` containing the URL they need to be directed to after they

login. Otherwise, they will just be sent to the main.index route

This is true for the admin as well. It is best to edit this functionality

since index pages should differ by user type. There is a flash sent as well

if the request is successful.

If there is an error in the user checking process, then the user is kicked

back to the account/login page with a flashed form error.

If this is a GET request, only the account/login page is rendered

The Flask-login Manager has a built in logout_user function that

removes the SESSION variables from the user's browser and logs out

the user completely

(refer to `flask-base/app/assets.py`)

See app/__init__.py for details on this

context is set as the assets/styles and

assetts/scripts folders

filter = scss -> convers .scss to css

filter = jsmin -> converts to minified

javascript

Bundle is just the plugin that helps us

do this task.

def permission_required(permission):

"""Restrict a view to users with the given permission."""

def decorator(f):

@wraps(f)

def decorated_function(*args, **kwargs):

if not current_user.can(permission):

abort(403)

return f(*args, **kwargs)

return decorated_function

return decorator

This is a rather complicated function, but the general idea

is that it will allow is to create a decorator that will

kick users to a 403 page if they dont have a certain permission

or let them continue. First there is a permission_required

method which takes in a permission e.g. Permission.ADMINISTER

Then it create a function called 'decorator' which performs

the check in a separate function itself decorates called

'decorated_function'. It returns the result from

'decorate_function' as well as the results from a specified

parameter f that serves as an extra function call. The

@wraps(f) decorator is itself used to give context for the

decorated function and actually point that context towards

the fully decorated function when the permission_required()

decorator is invoked. Tl;dr it does some complicated stuff

you don't really need to know about

This is a decorator created by the permission required decorator

It checks if the current_user is an admin or not. It takes in a

function f as the next action to occur after the check happens

however in practice, we only use the decorator @admin_required

on routes.

So lets go through each of the configuring variables.

APP_NAME is the name of the app. This is used in templating

to make sure that all the pages at least have the same html

title

SECRET_KEY is a alpha-numeric string that is used for crypto

related things in some parts of the application. Set it as an

environment variable or default to our insecure one. This is

used in password hashing see app/models/user.py for more info.

YOU SHOULD SET THIS AS A CONFIG VAR IN PRODUCTION!!!!

SQLALCHEMY_COMMIT_ON_TEARDOWN is used to auto-commit any sessions

that are open at the end of the 'app context' or basically the

current request on the application. But it is best practice

to go ahead and commit after any db.session is created

SSL_DISABLE I unfortunately do not know much about ;(. But something

realated to https

MAIL_... is used for basic mailing server connectivity throug the

SMTP protocol. This is further described in email.py.

See [the Github repository](http://github.com/hack4impact/flask-base)

This guide is meant to be a mix between formal and explanatory documentation.

A Flask application template with the boilerplate code already done for you.

* Blueprints

* User and permissions management

* Flask-SQLAlchemy for databases

* Flask-WTF for forms

* Flask-Assets for asset management and SCSS compilation

* Flask-Mail for sending emails

* gzip compression

* gulp autoreload for quick static page debugging

Before you submit changes to flask-base, you may want to auto format your code with `python manage.py format`.

See [the Github repository](http://github.com/hack4impact/flask-base)

[MIT License](http://github.com/hack4impact/flask-base/blob/master/LICENSE.md)

Note about CSRF protection. This basically prevents hackers

from being able to post to our POST routes without having actually

loaded a form on our website. E.g. they could potentially create

users if they found out the URL for our register routes and

the params we expect (its fairly easy to do). But with

CSRF protection, all forms have a hidden field that is verified on

our end. This is a bit low level, but there is a SESSION object

stored on the flask server in memory. Each user has their

own session containing things like their username, password, etc

When a form created, a random string called a CSRF token is

created and is sent along with the form in a hidden field.

Simultaneously, this string is added to the user session

stored on the server. When the user submits a form, then

the server will check to see if the hidden form field with the

CSRF token matches the CSRF token stored in the user's session

on the server. If it does, then everything is fine and the

POST request can proceed normally. If not, then the POST request

is aborted as a 403 (i think) error is thrown...basically

the user is not able to POST. This is great for forms, but

if you want to create a public API that does not require a session,

then you'll want to include a decorator on your route `@csrf.exempt`

login_manager = LoginManager()

login_manager.session_protection = 'strong'

login_manager.login_view = 'account.login'

Flask-login provides us with a bunch of easy ways to do secure and

simple login techniques. LoginManager() is the main class that

will handle all of this. Session protection makes sure the

user session is very secure and login_manager.login_view

Is the view that the a non-authenticated user will get redirected

to. Otherwise it is a 401 error.

mail.init_app(app)

db.init_app(app)

login_manager.init_app(app)

csrf.init_app(app)

compress.init_app(app)

RQ(app)

init_app(app) are methods in each of these packages

More on init_app. It binds each instance of the respective

application to the flask app. However, we do need to specify

an application context while using things like db, mail,

login_manager, and compress since they are not bound to our

application _exclusively_.

This one is a bit complex. First an Environment instance is created

that holds references to a single path to the 'static' folder. We don't

really care about that since the url_for() method allows us to specify

access to resources in the static/ directory. But we then append all the

folders and files within the 'dirs' array to the environment. This

action provides context for the subsequence set of register actions.

Looking in app/assets.py there are some Bundle instances created with

3 parameters mainly: what type of file(s) to bundle, a type of filter/

transpiler to apply, and then a final output file. E.g. for the

app_css bundle, it looks within assets/styles, assets/scripts for any

*.scss files, converts them to css with the scss transpiler and then

outputs it to the styles/app.css file.

See the templates/partials/_head.html

file for more information on how to actually include the file.

from account import account as account_blueprint

from admin import admin as admin_blueprint

from main import main as main_blueprint

app.register_blueprint(main_blueprint)

app.register_blueprint(account_blueprint, url_prefix='/account')

app.register_blueprint(admin_blueprint, url_prefix='/admin')

Blueprints allow us to set up url prefixes for routes contained

within the views file of each of the divisions we specify to be

registered with a blueprint. Blueprints are meant to distinguish between

the variable different bodies within a large application.

In the case of flask-base, we have 'main', 'account', and 'admin'

sections. The 'main' section contains error handling and views.

The other sections contain mainly just views. The folders for each of

these sections also contain an __init__ file which actually creates the

Blueprint itself with a name and a default __name__ param as well.

After that, the views file and any other files that depend upon the

blueprint are imported and can use the variable name assigned to the

blueprint to reference things like decorators for routes. e.g. if my

blueprint is name 'first_component', I would use the following as

a decorator for my routes '@first_component.route'. By specifying

the url_prefix, all of the functions and routes etc of the blueprint

will be read with the base url_prefix specified. E.g. if I wanted

to access the '/blah' route within the 'acount' blueprint, I need only

specify @account.router('/blah') def ... as my method in views.py under

the account/ directory. But I would be able to access it in the

browser with yourdomain.com/accounts/blah

A note on why we are importing here: Because stuff will break...and for

a good reason! The account import in turn imports the views.py file under

the account/ directory. The views.py in turn references db

db is the database instance which was created after the import statements

If we had included these import statements at the very top, views.py

under account would have refered to a db instance which was not created!

hence errors...all the errors (at least in files relying upon a created

db instance...and any instance created beyond that.