Welcome to Flask-Melodramatiq’s documentation!

Release v1.0. (API Reference, Source Code)

Flask-Melodramatiq is a Flask extension that adds support for the Dramatiq task processing library.

Dramatiq is a great library, and Flask-Melodramatiq tries hard not to force you to change the way you interact with it. Flask-Melodramatiq defines thin wrappers around the broker types available in Dramatiq, so that all the power of Dramatiq’s API remains available to you.

For example:

import dramatiq
from flask import Flask
from flask_melodramatiq import RabbitmqBroker

app = Flask(__name__)
broker = RabbitmqBroker(app)
dramatiq.set_broker(broker)

@dramatiq.actor
def task():
    print('Snakes appreciate good theatrical preformace.')

or, if you prefer the Flask application factory pattern:

import dramatiq
from flask import Flask
from flask_melodramatiq import RabbitmqBroker

broker = RabbitmqBroker()
dramatiq.set_broker(broker)

@dramatiq.actor
def task():
    print('Snakes appreciate good theatrical preformace.')

def create_app():
    app = Flask(__name__)
    broker.init_app(app)
    return app

In those examples, the broker instance that we created (we call it a “lazy broker”) is a genuine Dramatiq broker, and can be used anywhere where a “native” broker can be used. (It has RabbitmqBroker as a superclass!) Lazy brokers are thin wrappers which add several important features:

1. They honor the settings in the Flask application configuration.
2. init_app() can be called on them before or after the actors have been defined.
3. The Flask application context is correctly set during the execution of the tasks.
4. They add few convenience methods. (The actor() decorator for example.)

Configuration

You can change the configuration options for your broker by passing keyword arguments to the constructor, or by setting corresponding values for the DRAMATIQ_BROKER_* set of keys in the app config. For example, you can do either:

from flask_melodramatiq import RabbitmqBroker

broker = RabbitmqBroker(
    url='amqp://mybroker:5672', confirm_delivery=True)

or you can put this in your app config:

DRAMATIQ_BROKER_URL = 'amqp://mybroker:5672'
DRAMATIQ_BROKER_CONFIRM_DELIVERY = True

If the configuration values passed to the constructor are different from the ones set in the app config, the later take precedence. You can even set/override the type of the broker in the app config:

from flask_melodramatiq import Broker

broker = Broker()  # Broker's type is not specified here.

and instead, specify the type in the app config:

DRAMATIQ_BROKER_CLASS = 'StubBroker'

This feature can be quite useful when testing your code.

Starting workers

With Flask-Melodramatiq you have the whole power of Dramatiq’s CLI on on your disposal. For example, to start worker processes for your broker instance you may run:

$ dramatiq wsgi:broker

and in wsgi.py you may have something like this:

from myapp import create_app, broker

app = create_app()

You may have as many broker instances as you want, but you need to start each one of them with a separate command.

Installation

You can install Flask-Melodramatiq with pip:

$ pip install Flask-Melodramatiq

Contents:

API Reference

flask_melodramatiq.create_broker_class(classpath, *, classname=None, docstring=None, mixins=())

Create a new lazy broker class that wraps an existing broker class.

Parameters:

• classpath – A module path to the existing broker class. For example: "dramatiq.brokers.rabbitmq:RabbitmqBroker".
• classname – Optional name for the new class. If not given, the class name specified in classpath will be used.
• docstring – Optional documentation string for the new class
• mixins (tuple(type)) – Optional additional mix-in classes

Returns:

The created lazy broker class

Example:

from flask_melodramatiq import create_broker_class

PostgresBroker = create_broker_class('dramatiq_pg:PostgresBroker')

class flask_melodramatiq.Broker(app=None, config_prefix='DRAMATIQ_BROKER', **options)

A lazy broker of dynamically configurable type.

The type of the broker should be specified by the “config_prefix_CLASS” setting in the Flask application configuration. For example, if config_prefix is the defaut one, the configuration setting: DRAMATIQ_BROKER_CLASS="RedisBroker" specifies that the type of the broker should be RedisBroker.

The following broker type names are always valid:

• "RabbitmqBroker" (default)
• "RedisBroker"
• "StubBroker"

In addition to these, custom broker types can be registered with create_broker_class().

Parameters:

• app – An optonal Flask application instance
• config_prefix – A prefix for the Flask configuration settings for this broker instance. Each broker instance should have a unique configuration settings prefix.
• options – Keyword arguments to be passed to the constructor of the wrapped dramatiq broker class.

actor(fn=None, **kw)

Declare an actor for this broker instance.

Calls dramatiq.actor() internally.

Example:

from flask_melodramatiq import Broker

broker = Broker()

@broker.actor
def task():
    print('Snakes appreciate good theatrical preformace.')

init_app(app)

This method can be used to initialize an application for the use with this broker. A broker can not be used in the context of an application unless it is initialized that way.

init_app() is called automatically if an app argument is passed to the constructor.

set_default()

Configure this broker instance to be the global broker instance.

Calls dramatiq.set_broker() internally.

class flask_melodramatiq.RabbitmqBroker(**kwargs)

A lazy broker wrapping a RabbitmqBroker.

Parameters:

• app – An optonal Flask application instance
• config_prefix – A prefix for the Flask configuration settings for this broker instance. Each broker instance should have a unique configuration settings prefix.
• options – Keyword arguments to be passed to the constructor of the wrapped dramatiq broker class.

actor(fn=None, **kw)

Declare an actor for this broker instance.

Calls dramatiq.actor() internally.

Example:

from flask_melodramatiq import Broker

broker = Broker()

@broker.actor
def task():
    print('Snakes appreciate good theatrical preformace.')

init_app(app)

This method can be used to initialize an application for the use with this broker. A broker can not be used in the context of an application unless it is initialized that way.

init_app() is called automatically if an app argument is passed to the constructor.

set_default()

Configure this broker instance to be the global broker instance.

Calls dramatiq.set_broker() internally.

class flask_melodramatiq.RedisBroker(**kwargs)

A lazy broker wrapping a RedisBroker.

Parameters:

• app – An optonal Flask application instance
• config_prefix – A prefix for the Flask configuration settings for this broker instance. Each broker instance should have a unique configuration settings prefix.
• options – Keyword arguments to be passed to the constructor of the wrapped dramatiq broker class.

actor(fn=None, **kw)

Declare an actor for this broker instance.

Calls dramatiq.actor() internally.

Example:

from flask_melodramatiq import Broker

broker = Broker()

@broker.actor
def task():
    print('Snakes appreciate good theatrical preformace.')

init_app(app)

This method can be used to initialize an application for the use with this broker. A broker can not be used in the context of an application unless it is initialized that way.

init_app() is called automatically if an app argument is passed to the constructor.

set_default()

Configure this broker instance to be the global broker instance.

Calls dramatiq.set_broker() internally.

class flask_melodramatiq.StubBroker(app=None, config_prefix='DRAMATIQ_BROKER', **options)

A lazy broker wrapping a StubBroker.

Parameters:

• app – An optonal Flask application instance
• config_prefix – A prefix for the Flask configuration settings for this broker instance. Each broker instance should have a unique configuration settings prefix.
• options – Keyword arguments to be passed to the constructor of the wrapped dramatiq broker class.

actor(fn=None, **kw)

Declare an actor for this broker instance.

Calls dramatiq.actor() internally.

Example:

from flask_melodramatiq import Broker

broker = Broker()

@broker.actor
def task():
    print('Snakes appreciate good theatrical preformace.')

init_app(app)

This method can be used to initialize an application for the use with this broker. A broker can not be used in the context of an application unless it is initialized that way.

init_app() is called automatically if an app argument is passed to the constructor.

set_default()

Configure this broker instance to be the global broker instance.

Calls dramatiq.set_broker() internally.

class flask_melodramatiq.missing

Missing value for configuration variables. This can be useful when you want to document the given configuration setting in your code, but you do not want to change the default value.

For example:

from flask import Flask
from flask_melodramatiq import missing

app = Flask(__name__)
app.config['DRAMATIQ_BROKER_URL'] = missing