#Flask Foundation a

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

Built off of the bootstrapy project

Best practices were learned from Creating Websites With Flask and Getting Bigger With Flask, and most importantly Larger Applications With Flask.

##What Is Included

• Best Practices setup with blueprints and SQLAlchemy models that will allow you to grow cleanly
• A helpful makefile
• An awesome management script
• Bootstrap is included but easily replaceable
• Typeplate: some nice typographic defaults, also easily replaceable
• py.test tests
• Sphinx: Helps you create some awesome docs for your users, or your internal team
• Flask-Assets: A library that packages css and js files and applies filters to them like the closure complier
• Flask-Cache: A simple library that adds the ability to cache specified views
• Flask-SQLAlchemy: Flask integration with SQLAlchemy
• Flask-Script: Allows one to create awesome management scripts
• Flask-WTF: Integrates WTForms into flask

##What Is Not Included

• A WSGI setup. This is largely based off of ones individual production setup, so it is not included.
• A Redis or a Memcached setup for Flask-Cache.
• A database migration tool, like South. This is not included due to the fact that for 99.9% of people this is overkill.
• A database backend for SQLAlchemy. SQLAlchemy does not come with a way to connect to the database and must be provided. These backends can be found on the SQLAlchemy documentation.
• A admin interface tool. Some like the library Flask-Admin, others want to build their own. I don't include it because I believe that it is no where close to being as customizable as it should be.
• A publishing tool like fabric. Which tool you use is totally up to your personal preference as well as your production environment, which is why it is not included.
• A vagrant setup. For most people vagrant is overkill, but the vagrant setup is entirely based of off your production setup so it is not included here.

##Usage

###The Makefile

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.

###The Management 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 Flask 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 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.

Lets talk about the tests. All of the tests are in the tests/ directory, and the tests are run with py.test. Nothing is to 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. 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.