flasker 0.1.37

Flask, SQLAlchemy, and Celery integration

A configurable, lightweight framework that integrates Flask, SQLAlchemy and Celery.

• What Flasker is!

  • A one stop .cfg configuration file for Flask, Celery and the SQLAlchemy engine.

  • A simple pattern to organize your project via the flasker.current_project proxy (cf. Structuring your project).

  • A command line tool from where you can create new projects, launch the Flask buit in Werkzeug server, start Celery workers and the Flower tool, and run a shell in the current project context.

• What Flasker isn’t?

  • A simplified version of Flask, Celery, and SQLAlchemy. Some knowledge of these frameworks is therefore required.

Flasker also comes with three extensions for commonly needed functionalities:

• Authentication

• Expanded ORM Models

• ReSTful API (still alpha)

Flasker is under development. You can find the latest version on GitHub and read the documentation on GitHub pages.

Quickstart

• Installation:

  $ pip install flasker

• To create a new project:

  $ flasker new basic

  This will create a basic project configuration file default.cfg in the current directory and a basic Bootstrap themed app (this can be turned off with the -a flag). Another sample configuration file is available via flasker new celery that includes sane defaults for task routing.

• Next steps:

  $ flasker -h

  This will list all commands now available for that project:

  • server to run the Werkzeug app server

  • worker to start a worker for the Celery backend

  • flower to run the Flower worker management app

  • shell to start a shell in the current project context (using IPython if it is available)

  • new to create a new default configuration file

  Extra help is available for each command by typing:

  $ flasker <command> -h

Structuring your project

Here is a sample minimalistic project configuration file:

[PROJECT]
NAME = My Project
MODULES = app.views, app.tasks
[ENGINE]
# SQLAlchemy engine configuration
URL = sqlite:///db/db.sqlite
[FLASK]
# any valid Flask configuration option can go here
DEBUG = True
TESTING = True
[CELERY]
# any valid Celery configuration option can go here
BROKER_URL = redis://

Before running a command the flasker command line tool imports all the modules declared in the MODULES key of the configuration file (in the PROJECT section). Inside each of these you can use the flasker.current_project proxy to get access to the Flask application object, the Celery application object and the SQLAlchemy database session registry. Therefore a very simple pattern inside each module is to do:

from flask import render_template
from flasker import current_project as pj

# the Flask application
flask_app = pj.flask

# the Celery application
celery_app = pj.celery

# the SQLAlchemy scoped session registry
session = pj.session

# normally you probably wouldn't need all three in a single file
# but you get the idea - and now you can do stuff with each...

@flask_app.route('/')
def index():
  """A random view."""
  return render_template('index.html')

@celery_app.task
def task():
  """And a great task."""
  pass

# and so on...

If you are not using the command line tool (for example if you are using a separate WSGI server or working from an IPython Notebook), you can load the project manually as follow:

from flasker import Project

project = Project('path/to/default.cfg')

Project configuration

A few options are available for the PROJECT section of the configuration file:

• NAME: the name of the project, used for debugging and to generate a default domain name for the Celery workers.

• MODULES: comma separated list of the project’s modules. They must be importable from the configuration file’s folder.

• FLASK_ROOT_FOLDER: path to the Flask application’s root folder relative to the configuration file (defaults to app).

• FLASK_STATIC_FOLDER: the application’s static_folder relative to the application’s root folder (defaults to static).

• FLASK_TEMPLATE_FOLDER: the application’s template_folder relative to the application’s root folder (defaults to templates).

• COMMIT_ON_TEARDOWN: if True (default), all database transactions will be committed after each Flask app request and Celery task completion. If False the session will simply be removed.

• DOMAIN: if specified, used to generate Celery worker hostnames (defaults to the project name, sluggified).

• SUBDOMAIN: if specified, used to generate Celery worker hostnames (defaults to the configuration file’s name).