Flask Foundation

A solid foundation for your flask app

Project maintained by JackStouffer Hosted on GitHub Pages — Theme by mattgraham

Flask Foundation is a solid, production environment agnostic, foundation for flask applications, built with best practices, that you can easily construct your website/webapp off of.

While there are many other flask templates out there, far too many are either structured poorly or are tied down to a specific method of deployment, or both. Flask Foundation however, is constructed along community considered best practices and does not assume anything about your production environment.

Flask Foundation is built off of the bootstrapy project

If you are a cookiecutter user, there is a cookiecutter fork at this repo.

Best practices were learned from

What Is Included

What Is Not Included

Some items which you may need for your setup but are not included to keep this framework agnostic

Usage And Structure

Using Make To Setup Our Environment

First, lets use the included make file to setup our dev environment. To see all of the available commands, just type make.

$ make

        env         create a development environment using virtualenv
        deps        install dependencies
        clean       remove unwanted stuff
        lint        check style with flake8
        test        run all your tests using py.test

If you are ever confused about what each command does, take a look at the makefile, it is very straight forward.

So to setup the dev environment, let's type 

$ make env

This will install virtualenv if you don't have it and setup a local python instance. Then it installs all of the needed libs from the requirements.txt file. Now we have our setup with all of the needed 3rd party libs.

Tests are done through py.test, and reside in the tests directory. To run the tests, just type 

$ make test

You can check you PEP8 compliance by typing 

$ make lint

Documentation for your project can be created with Sphinx in the docs directory. For more information, refer to the Sphinx documentation.

Using The Manage.py File

Simply type

./manage.py

and you will get a list of commands that you can use to manage the project. For example, to run the server, use 

./manage.py server

and if the installation when well, you should have a working server on http://localhost:5000

This management script was created with Flask-Script and is fairly easy to add your own commands, simply refer to their docs.

The Application Structure

Before going to far into this, you should at least skim the documentation of all of the thrid party libraries listed above so you have a better understanding of what is going on here.

The flask application itself lives in the appname directory. Obviously, you should change this to the name of your application. Once you do though, you must go through and fix all of the imports where it uses the appname name. The easiest way to find them all is to type

grep -R appname *

To make things organized, this project is in a pseudo MVC setup. With the controllers as flask blueprints, the models as SQLAlchemy models, and the views as the templates.

The main logic of the application is in the __init__.py. This is done so that the application is treated as a module by python which helps later when importing things. Here, we setup all of the third party libs and load in our configuration in an application factory, which is a function that creates and returns an instance of our application. This is done for easier testing purposes and modularity. The function create_app takes the path of the config file that you want to use and the type of environment that the server is running in. Most of the library initialization is self explanatory, but let me explain the configuration loading. In your shell's startup script (if you are using bash, its .bash_profile), you must enter this line:

APPNAME_ENV = 'dev'

or

APPNAME_ENV = 'prod'

This tells the application which class, located in settings.py, to load in for the configuration. To see the different configs, take a look at the settings.py file. This is explained more in depth in the flask docs here.

After everything is initialized, the application loads in the main blueprint from the controllers file. If you don't know how flask blueprints work, check out this page in the flask documentation. The controllers/main.py file is where we have our current example logic, with a homepage and a example WTForms page.

WTForm classes are held in a separate file called forms.py and imported when needed.

The templates are stored in the templates directory for the main blueprint. It is encouraged, but not required, that every new blueprint has its own templates directory inside of the main templates directory. Blueprints have a special variable to make this easy:

simple_page = Blueprint('simple_page', __name__, template_folder='simple')

and now when you have a function 

@simple_page.route('/')
def function()
    return render_template('index.html')

it will return simple/index.html

As you can see, the example code uses bootstrap. You are quite able to rip it out and use your own framework if you wish.

All of the templates inherit from the base.html template to avoid repeating yourself and to avoid discrepancies between pages. Also, as you can see in base.html, it is encouraged that you make use of Flask-Assets when ever possible. Using this to your advantage will dramatically speed up load times.

The models in this application are SQLAlchemy models in the models.py file, an example User model has been provided.

If you are still confused about how this project is structured, I encourage you to read the blog posts listed at the top of the README file.

Need help implementing some common features like user login or ajax? For a full blown tutorial covering almost every flask topic that you can think of, I recommend The Flask Mega-Tutorial.

Testing

To run your tests use the provided make command:

make test

The tests are located in the tests/ directory, and the tests are run with py.test. Nothing is too fancy in the test_config.py tests, but in the rest we see some special initialization with the database, this is due to flask not actually running and Flask-SQLAlechmy not being initialized properly, so we pass in the app using 

db.app = app

Also, we see here the use of app.test_client(), which means we can use functions to send GET and POST requests from our tests. This is how we test our forms and if the urls are returning correctly.

Sending post and get requests is all well and good, but if you want to get really advanced, check out webtest.

Production

First off, it is very, very important that if you ever open source a flask application based upon this, to not include the settings.py file in your repo. Obviously, your database password is in it, but your secret key as well, which is used to cryptographically sign all of flask's session data.

When going into production there are several things that you should do. First, look at your options for deploying on an actual server here.

Using the flask development server is NOT recommended for production for several good reasons, including the ability for anyone who can touch it to run arbitrary python on the server.

Deploying to the server manually is tedious, so you might want to look into deploying with fabric or distribute.

This isn't php, so logging errors doesn't come out of the box, here is a great resource on the subject.

Also, there are several awesome plug-ins available for flask that add in functionality that you might need for your application, they can be found on the flask website here, or just searching "flask" on github.

Licenses

The original bootstrapy project and the added code from this project are licensed under the BSD license.