Flask on App Engine Project Template

Boilerplate project template for running a Flask-based application on Google App Engine (Python)

Python 2.7 Runtime Support

• Support for the Python 2.7 runtime was added to this project in May 2012.
• The profiler (gae_mini_profiler) and debugger (werkzeug_debugger_appengine) have been disabled until the libraries are updated to support the Python 2.7 runtime.

About Flask

Flask is a BSD-licensed microframework for Python based on Werkzeug, Jinja2 and good intentions.

See http://flask.pocoo.org for more info.

Setup/Configuration

1. Download this repository via git clone [email protected]:kamalgill/flask-appengine-template.git or download the tarball at http://github.com/kamalgill/flask-appengine-template/tarball/master
2. Copy the src/ folder to your application's root folder
3. Set the application id in src/app.yaml
4. Configure datastore models at src/application/models.py
5. Configure application views at src/application/views.py
6. Configure URL routes at src/application/urls.py
7. Configure forms at src/application/forms.py
8. Add the secret keys for CSRF protection by running the generate_keys.py script at src/application/generate_keys.py, which will generate the secret keys module at src/application/secret_keys.py

Note: Copy the .gitignore file from the tarball folder's root to your git repository root to keep the secret_keys module out of version control.

Or, add the following to your .(git|hg|bzr)ignore file

  # Keep secret keys out of version control
  secret_keys.py

Front-end Customization

1. Customize the main HTML template at src/application/static/templates/base.html
2. Customize CSS styles at src/application/static/css/main.css
3. Add custom JavaScript code at src/application/static/js/main.js
4. Customize favicon at src/application/static/img/favicon.ico
5. Customize 404 page at src/application/templates/404.html

Previewing the Application

To preview the application using App Engine's development server, use dev_appserver.py

  dev_appserver.py src/

Assuming the latest App Engine SDK is installed, the test environment is available at http://localhost:8080

Running Unit Tests

To run unit tests, use

    python testrunner.py APPENGINE_SDK_PATH

Deploying the Application

To deploy the application to App Engine, use appcfg.py update

  appcfg.py update src/

The application should be visible at http://{YOURAPPID}.appspot.com

Folder structure

The App Engine app's root folder is located at src/.

  src/
  |-- app.yaml (App Engine config file)
  |-- application (application code)
  |-- blinker/ (library for event/signal support)
  |-- flask/ (Flask core)
  |-- flaskext/ (Flask extensions go here; wtforms and gae_mini_profiler are provided)
  |-- index.yaml (App Engine query index definitions)
  |-- tests/ (unit tests)
  |-- werkzeug/ (WSGI utilities for Python-based web development)
  `-- wtforms/ (Jinja2-compatible web form utility)

The application code is located at src/application.

  application/
  |-- __init__.py (initializes Flask app)
  |-- decorators.py (decorators for URL handlers)
  |-- forms.py (web form models and validators)
  |-- models.py (App Engine datastore models)
  |-- settings.py (settings for Flask app)
  |-- static
  | |-- css
  | | `-- main.css (custom styles)
  | |-- img
  | | |-- favicon.ico
  | | `-- favicon.png
  | `-- js
  |   |-- main.js (site-wide JS)
  |   `-- lib/ (third-party JS libraries)
  |     |--bootstrap-*.js (Bootstrap jQuery plugins
  |     `--modernizer-*.js (HTML5 detection library)
  |-- templates
  | |-- 404.html (not found page)
  | |-- 500.html (server error page)
  | |-- base.html (master template)
  | |-- list_examples.html (example list-based template)
  | `-- new_example.html (example form-based template)
  |-- urls.py (URL dispatch routes)
  `-- views.py (Handlers for URL routes defined at urls.py)

Removing Extended Attributes (@ flag)

A few of the files in the source tree were uploaded (with apologies) to GitHub with extended attributes (notice the '@' symbol when running ls -al).

To remove the extended attributes, use xattr -rd at the root of the src/ folder.

  xattr -rd com.apple.quarantine .
  xattr -rd com.macromates.caret .

Note: Windows users may safely ignore the xattr fix

Licenses

See licenses/ folder

Package Versions

• Blinker: 1.1
• Bootstrap: 2.0.3
• Flask: 0.8
• Flask-WTF: 0.6
• Jinja2: 2.6 (included in GAE)
• Modernizr: 2.5.3
• Werkzeug: 0.8.3
• WTForms: 1.0.1

Credits

Project template layout was heavily inspired by Francisco Souza's gaeseries Flask project

Layout, form, table, and button styles provided by Bootstrap

HTML5 detection provided by Modernizr 2 (configured with all features)