Large app how to

This document is an attempt to describe the first step of a large project structure with flask and some basic modules:

• SQLAlchemy
• WTF (What The Form)

Please feel free to fix and add you own tips.

Installation

Flask

[http://flask.pocoo.org/docs/installation/](Flask Installation) I recommend using virtual env: easy and allow multiple environment on the same machine and doesn't even require you to have super user right on the machine (as the libs are localy installed).

Flask-SQLAlchemy

SQL provide an easy and advanced way to serialize your object to different type of relational database. In your virutal env, install SQLAlchemy from pip:

pip install flask-sqlalchemy

[http://packages.python.org/Flask-SQLAlchemy/](More here about SQL Alchemy flask package)

Flask-WTF

WTF (What the Form) Provides a easy way to handle user's data submission.

pip install Flask-WTF

[http://packages.python.org/Flask-WTF/](More here about What The Form flask package)

Overview

Ok, so from now, we should have all the libs ready. Here the folder structures:

config.py
run.py
shell.py 
app.db
app/__init__.py
app/constants.py
app/static/

For every module (or sub app... ) well have this file structure (here for the users module)

app/users/__init__.py
app/users/views.py
app/users/forms.py
app/users/constants.py
app/users/models.py
app/users/decorators.py

for every module that need templating (jinja) we store those in the templates folder + module directory.

app/templates/404.html
app/templates/users/login.html
app/templates/users/register.html
...

for the static file you should serve them with a dedicated http server, but being in at a dev stage, we'll let flask serve them. Flask will automagically serve static files from this static folder. If you want to use another folder... you can read about that here: http://flask.pocoo.org/docs/api/#application-object

app/static/js/main.js
app/static/css/reset.css
app/static/img/header.png

We'll create 4 modules, a user module (manage user's registration, login, password lost, profile edit and maybe Third party Login/Registration) an emails module intended to be used by a queuing server, and a posts and comments modules

Config

run.py will be used to launch the web server.

from tol import app
app.run(debug=True)

shell.py will allow you to get a console and enter commands within your flask environment. Maybe not as nice as debugging with pdb, but always usefull (when you will initialize your database)

#!/usr/bin/env python
import os
import readline
from pprint import pprint

from flask import *
from app import *

os.environ['PYTHONINSPECT'] = 'True'

config.py will be storing all the module configurations. Here, the database is setup to use SQLite, because it's a very convenient dev env database. Most likely config.py won't be a part of your repository and will be different on your test and production servers.

import os
_basedir = os.path.abspath(os.path.dirname(__file__))

DEBUG = False

ADMINS = frozenset(['youremail@yourdomain.com'])
SECRET_KEY = 'SecretKeyForSessionSigning'

SQLALCHEMY_DATABASE_URI = 'sqlite:///' + os.path.join(_basedir, 'app.db')
DATABASE_CONNECT_OPTIONS = {}

THREADS_PER_PAGE = 8

CSRF_ENABLED=True
CSRF_SESSION_KEY="somethingimpossibletoguess"

RECAPTCHA_USE_SSL = False
RECAPTCHA_PUBLIC_KEY = 'blahblahblahblahblahblahblahblahblah'
RECAPTCHA_PRIVATE_KEY = 'blahblahblahblahblahblahprivate'
RECAPTCHA_OPTIONS = {'theme': 'white'}

del os

• _basedir is a trick for you to get the folder where the script runs
• DEBUG indicate that it is a dev environment, you'll get the very helpful error page from flask when an error occur.
• SECRET_KEY will be use to sign the cookies. Change it and all your user will have to login again.
• ADMINS
• SQLALCHEMY_DATABASE_URI and DATABASE_CONNECT_OPTIONS are SQLAlchemy connection options (hard to guess )
• THREAD_PAGE my understanding was 2/core... might be wrong :)
• CSRF_ENABLED CSRF_SESSION_KEY is protecting against form post fraud
• WTF comes with REPCAPTCHA field ready to use... just need to go to repcatcha website and get your public and private key.

First module

We'll start with the users modules. In order, we'll define the models, the constants linked to this model, the form and finally the first view and it's template.

First model (and it's constants.py)

The models.py

from app import db
from app.users import constants as USER

class User(db.Model):

    __tablename__ = 'users_user'
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(50), unique=True)
    email = db.Column(db.String(120), unique=True)
    password = db.Column(db.String(20))
    role = db.Column(db.Integer, default=USER.USER)
    status = db.Column(db.Integer, default=USER.NEW)

    def __init__(self, name=None, email=None, password=None):
      self.name = name
      self.email = email
      self.password = password

    def getStatus(self):
      return USER.STATUS[self.status]

    def getRole(self):
      return USER.ROLE[self.role]

    def __repr__(self):
        return '<User %r>' % (self.name)

and it's constants in the constants.py file:

# User role
ADMIN = 0
STAFF = 1
USER = 2
ROLE = {
  ADMIN: 'admin',
  STAFF: 'staff',
  USER: 'user',
}

# user status
INACTIVE = 0
NEW = 1
ACTIVE = 2
STATUS = {
  INACTIVE: 'inactive',
  NEW: 'new',
  ACTIVE: 'active',
}

First about the constants file, I like to have my constants their own file and inside my module for 2 main reasons. Your constants will probably be used in your models, forms and views. The second reason is that it's a better organization for you to find them. Also, importing your constants as the module in uppercase indicate the constant type and the module name (like USER for users.constants) will avoid you name conflicts.

First form

First view