flask-bluebone

flask-bluebone is a REST-ish (it manages session state using cookies) API with CORS support and endpoints for authentication, authorization, registration, profile edit, and password reset/change. Components are loosely coupled. This includes packages (thanks Blueprints!), extensions, web assets, and templates.

Project Structure

app                      → Application sources
 └ meta                  → Home package
 └ session               → Session package
 └ static                → Asset sources
    └ css                → Typically LESS CSS sources
       └ email           → Email styles
       └ error           → Error styles
    └ public             → Public assets
       └ css             → CSS files
 └ templates             → Templates
 └ translations          → Translation template and translation files
 └ user                  → User package
  __init__.py            → App initialization
  assets.py              → Flask-Assets config
  babel.cfg              → Flask-Babel config
  constants.py           → Global constants
  extensions.py          → Flask extensions instantiated here
  utils.py               → Global utilities
.gitignore               → Untracked files that git should ignore
.slugignore              → Untracked files that heroku should ignore
Procfile                 → Command to executed by Heroku to start a web dyno
README.md                → Used for Readme Driven Development
config.py                → Flask configuration module
fabfile.py               → Fabric tasks
manage.py                → Flask-Script tasks
setup.py                 → Fabric setup code
tests.py                 → Tests module

Flask

kennethreitz's flasky-goodness presentation is a good explanation of why Flask rules.

Flask-Assets

Transactional emails and error pages are styled with CSS. These assets are compiled and minified with Flask-Assets. cssmin is used for minifying. Source stylesheet categorization, naming convention, and formatting follows SMACSS.

Flask-Babel

i18n and l10n support is provided by Flask-Babel.

Flask-Login

User session management built on top of Flask-Login and passlib. This includes authentication, registration, and password reset/change.

Flask-Mail

Gmail doesn't support style tags in HTML emails. Inline style attributes must be defined on the DOM element. The premailer package parses an HTML page containing style blocks, parses the CSS, and yields an HTML string with inline style attributes. This is used for transactional emails. The emails are sent using Flask-Mail's SMTP support.

Flask-SQLAlchemy

There's not out of the box support for any database with Flask. The Flask-SQLAlchemy extension provides an excellent database toolkit and ORM.

Flask-Script

Flask-Script provides commands to run the Flask development server, open a Python shell, create DB, drop DB, init DB) from the terminal.

Flask-WTF

Flask-WTF offers integration with WTForms. This API uses WTForms for validating AJAX POST and PUT requests. Flask-WTF also includes CSRF protection. An API precludes CSRF, because its purpose is generally to allow 3rd-party entities to access and manipulate data on your site (the "cross-site" in CSRF). Therefore, CSRF protection is disabled.

Testing

Unit tests are written using unittest + Flask-Testing. Tests are run with nose and its coverage plugin.

Workflows

Install

• Git

    $ sudo apt-get install git-core
  

• pip

• Python and Virtualenv

• fabric

    $ pip install fabric
  

• s3cmd for syncing web assets with Amazon S3

    $ sudo apt-get install s3cmd
    $ s3cmd --configure
  

• cloc for counting LOC

    $ sudo apt-get install cloc
  

1. Clone this repo

    $ git clone git://github.com/vovantics/flask-bluebone.git
    $ cd flask-bluebone
   

2. Create and activate virtual environment

    $ virtualenv venv --distribute --no-site-packages
    $ source venv/bin/activate
   

3. Setup

    $ fab setup
   

Development process

1. Build web assets

    $ ./manage.py assets build
   

2. Set app environment to dev (do this once)

    $ export APP_ENV=dev
   

3. Start Flask server

    $ fab run
   

4. Open the app in your browser

   http://127.0.0.1:5000/users/me/

Test process

$ fab test

Deployment process

Deploying with Fabric.

Based on the Getting Started with Python on Heroku.

Anything written to standard out (stdout) or standard error (stderr) is captured into your heroku logs. Error mails are sent the second the exception happens using Flask's native logging handlers

Prerequisites:

1. Install the Heroku Toolbelt on your local workstation

2. Login to the Heroku CLI tool

    $ heroku login
   

3. Create a new application on Heroku.

    $ heroku create -s cedar
   

4. Deploy your code

    $ git push heroku master
   

5. Create database schema

    $ heroku run "python manage.py initdb"
   

6. Open the app in your browser

    $ heroku open
   

7. Verify that it works

8. Set the concurrency level to one web dyno

    $ heroku ps:scale web=1
   

TODO

• Dynamic documentation using Sphinx

Acknowledgements

• Armin Ronacher's how-to large project structure with flask and some basic modules
• The traveling coder's guide on Building websites in Python with Flask
• HTML EMAIL BOILERPLATE
• Patterns for Flask
• imwilsonxu's fbone