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.

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 = <LocalProxy unbound>¶: 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.