Documentation

asdfasdfasfdf

Quickstart

This will be a quick example of how to use Flask-Storm to create a REST API endpoint for a list of messages. For the full example code, see Full example.py.

Imports

# example.py
from flask import Flask, jsonify
from flask_storm import FlaskStorm, store
from random import choice
from storm.locals import Int, Unicode

To get a minimal application running there are a few needed imports. The only noteworthy thing here is the store context local. For a primer on context locals see the flask documentation. This variable is a bit magic, and works just like the built-in g.

Application setup

app = Flask("example")
app.config["STORM_DATABASE_URI"] = "sqlite:///test.db"

flask_storm = FlaskStorm()
flask_storm.init_app(app)

Flask-Storm needs the STORM_DATABASE_URI to know which database to connect to. The format is described in the official documentation for Storm. It does not matter when the configuration variable is set, as long as it is done before using the store context local. Flask-Storm is bound to a Flask application by using init_app(). One instane of FlaskStorm can be bound to multiple applications at once. One application can however only be bound to a single FlaskStorm instance.

Declaring a model

class Post(object):
    __storm_table__ = "posts"

    id = Int(primary=True)
    name = Unicode()
    text = Unicode()

    def __init__(self, name=None, text=None):
        if name is not None:
            self.name = name

        if text is not None:
            self.text = text

This is how a model is declared in Storm. In this case a Post has an integer id column as primary key, and two Unicode text columns; name and text. The table posts is declared using a special dunderscore __storm_table__.

Initializing the database

@app.cli.command()
def initdb():
    """Create schema and fill database with 15 sample posts by random authors"""

    store.execute("""DROP TABLE IF EXISTS posts""")
    store.execute("""
        CREATE TABLE posts(
            id    INTEGER PRIMARY KEY,
            name  VARCHAR,
            text  VARCHAR
        )
    """)

    names = [
        u"Alice",
        u"Bob",
        u"Eve",
    ]

    for i in range(1, 16):
        store.add(Post(choice(names), u"Post #{}".format(i)))

    store.commit()

Starting with Flask version 0.11 there is a default command line interface that one can hook into. To create all tables and fill them with sample data, it is just a matter of running:

FLASK_APP=example.py flask initdb

The command will create test.db with the schema and data. This is the first use of an actual connection to the database. Note that there is no need to connect or close the store. This is handled automatically by Flask-Storm. A connection is never opened until the store context local is accessed, and remains open until the application context is torn down.

Serving requests

@app.route("/")
def index():
    """Return the 10 latest posts in JSON format"""

    return jsonify([{
        "id": post.id,
        "name": post.name,
        "text": post.text,
    } for post in store.find(Post).order_by(Desc(Post.id)).config(limit=10)])

The route serves a JSON array response containing the last 10 posts. In this case it is post 6 through 15.

Now it is just a matter of running the application. This is easily done using the Flask command line interface:

FLASK_APP=example.py flask run

This will, if there are no errors, serve the application on http://localhost:5000/. Open this page in a web-browser to see the JSON data.

Setup and tear down procedure

To prevent unnecessary overhead, database connections are created on demand when used within the application context. The same connection gets reused, and remains open, until the application context is torn down.

This means the only thing required to use the store context local is a configured application context.

Configuration options

This is the full list of configuration options for Flask Storm.

STORM_DATABASE_URI

URI for the default database to connect to. This has the same format as the argument to Storm’s create_database as defined in the official documentation.

STORM_BINDS

A dictionary of Storm URIs that Flask Storm can connect to. A bind is defined as an arbitrary key, used to identify the bind, and a URI for the database. See Using with multiple Stores for an in-depth explaination.

Using with Flask CLI

When using flask shell, Flask Storm will automatically provide a refence to the store context local. Flask Storm also sets up debug output of the SQL statements created by Storm. This makes flask shell a good testing environment for building complex queries with Storm.

To make things more convenient it is recommended to provide model objects directly to the shell context. This is done easily by adding them using a shell context processor.

from flask import Flask
from storm.locals import Int, Unicode

class User(object):
    __storm_table__ = "users"

    id = Int(primary=True)
    name = Unicode()

app = Flask("example")

@app.shell_context_processor
def shell_context():
    return {"User": User}

This example makes automatically makes User available in the shell environment.

Note

It is possible to disable SQL statement printing by calling stop on the tracer.

>>> _storm_tracer.stop()

To disable color printing, reset the fancy flag:

>>> _storm_tracer.fancy = False

Using with multiple Stores

To interface with multiple Stores simultaneously binds exist. Apart from the default database, declared in STORM_DATABASE_URI, an arbitrary number of extra databases can be declared in STORM_BINDS. A bind declaration may look something like this:

STORM_BINDS = {
    "extra": "sqlite://:memory:",
}

The key extra is used to reference the bind, and the URI is used when connecting to the database. To make binds as easy to use as the normal store context local it is possible to create context locals for every bind, using create_context_local().

# Use the same key as when declaring the bind. In this case "extra"
extra_store = create_context_local("extra")

extra_store can now be used just like store as long as an application context is available. Just like the default store, all binds are automatically closed on application context teardown.

Tip

Declare extra bind context locals in a separate Python file that can be imported.

Full example.py

# example.py
from flask import Flask, jsonify
from flask_storm import FlaskStorm, store
from random import choice
from storm.locals import Int, Unicode


app = Flask("example")
app.config["STORM_DATABASE_URI"] = "sqlite:///test.db"

flask_storm = FlaskStorm()
flask_storm.init_app(app)


class Post(object):
    __storm_table__ = "posts"

    id = Int(primary=True)
    name = Unicode()
    text = Unicode()

    def __init__(self, name=None, text=None):
        if name is not None:
            self.name = name

        if text is not None:
            self.text = text


@app.cli.command()
def initdb():
    """Create schema and fill database with 15 sample posts by random authors"""

    store.execute("""DROP TABLE IF EXISTS posts""")
    store.execute("""
        CREATE TABLE posts(
            id    INTEGER PRIMARY KEY,
            name  VARCHAR,
            text  VARCHAR
        )
    """)

    names = [
        u"Alice",
        u"Bob",
        u"Eve",
    ]

    for i in range(1, 16):
        store.add(Post(choice(names), u"Post #{}".format(i)))

    store.commit()


@app.route("/")
def index():
    """Return the 10 latest posts in JSON format"""

    return jsonify([{
        "id": post.id,
        "name": post.name,
        "text": post.text,
    } for post in store.find(Post).order_by(Desc(Post.id)).config(limit=10)])