API documentation

The following functions and classes are part of Flask Storm’s public API. All are available directly from the top level namespace flask_storm. Imports from namespaces below flask_storm, such as flask_storm.debug is not supported and may change across versions.

Extension

class FlaskStorm(app=None)

Create a FlaskStorm instance.

Parameters

app – Application to enable Flask-Storm for. This is the same as calling init_app() after initialization.

connect(bind=None)

Return a new Store instance with a connection to the database specified in the STORM_DATABASE_URI configuration variable of the bound application. This method normally not be called externally as it does not close the store once the application context tears down.

Parameters

bind – Database URI to use, defaults to STORM_DATABASE_URI. See get_binds() for details.

Returns

Store instance

Raises

RuntimeError – if no connection URI is found.

get_binds()

Return dict of database URIs for the application as defined by the STORM_BINDS configuration variable. If STORM_DATABASE_URI is defined it will be available using the key None.

Returns

Dict from bind names to database URIs.

get_store(bind=None)

Return a Store instance for the current application context. If there is no instance a new one will be created. Instances created using this method will close on application context tear down.

Parameters

bind – Bind name of database URI. Defaults to the one specified by STORM_DATABASE_URI.

Returns

Store for the current application context.

Raises

RuntimeError – if accessed outside the scope of an application context.

init_app(app)

Binds this extension to the given application. This is important since the database connection will not close unless the application has been initialized.

Note

One instance of FlaskStorm may be registered to multiple applications. One application should however only be registered to one FlaskStorm instance, or tear down functionality will trigger multiple times.

Parameters

app – Application to enable Flask-Storm for.

Raises

RuntimeError – if an application is already bound to this instance by being passed to the constructor.

property store

Return a Store instance for the current application context. If there is no instance a new one will be created. Instances created using this method will close on application context tear down.

Parameters

bind – Bind name of database URI. Defaults to the one specified by STORM_DATABASE_URI.

Returns

Store for the current application context.

Raises

RuntimeError – if accessed outside the scope of an application context.

Context locals

store = Proxy for FlaskStorm.store

Shorthand for FlaskStorm.store which does not depend on knowing the FlaskStorm instance bound to the current request context. This is the prefered method of accessing the Store, since using the FlaskStorm.store property directly makes it easy to accidentally create circular imports.

create_context_local(bind)

Create a context local for the given bind. None means the default store.

# Context local for the bind report_store
report_store = create_context_local("report_store")

This is what is used to implement the store context local which analogue to

store = create_context_local(None)

Parameters

bind – Bind name of database URI to use when creating store.

Raises

RuntimeError – if working outside application context or if FlaskStorm is not bound to the current application.

Tracers

Tracers provide facilities to intercept and read SQL statements generated by Storm. The tracers provided in Flask-Storm are tailored for use in multithreaded environments, and work in conjunction with Flask’s contexts.

DebugTracer

class DebugTracer

A tracer which stores all queries with parameters onto the current request context. Queries are accessible using get_debug_queries(). It is used as a context manager. Since all queries are stored on the request context, they can only be accessed until the current request tears down.

with DebugTracer():
    # Perform queries
    queries = get_debug_queries()

Note

get_debug_queries() do not need to be called within the context manager, as long as the request context is still alive, since all queries are stored on the request context.

get_debug_queries()

Return an array of queries executed within the context of a DebugTracer under the current application context and thread.

RequestTracer

class RequestTracer(file=None, fancy=None)

A tracer which prints all SQL queries generated by Storm directly to STDOUT. This is useful when debugging views in flask.

with RequestTracer():
    # Queries executed here will be printed into STDOUT
    ...

Parameters

• file – File like object (has write method) where queries will be logged to.

• fancy – When True (default) colored output is used, if support is detected, when False plain text is used.

start()

Install and activate this tracer for all statements executed in this thread (or greenlet).

stop()

Stop using this tracer.

Utility

find_flask_storm(app)

Find and return FlaskStorm instance for the given application.

Parameters

app – Application to look for FlaskStorm instance in.

Returns

FlaskStorm instance if found, else None.