API

Plugin

class flask_execute.Celery(app=None, base_task=None)

Plugin for managing celery task execution in Flask.

Arguments:

app (Flask): Flask application object. base_task (celery.Task): Celery task object to

use as base task for celery operations.

apply(func, args=(), kwargs={}, **options)

Submit function to celery worker for processing.

Arguments:

args (list): Arguments to function. kwargs (dict): Keyword arguments to function. **options (dict): Arbitrary celery options to pass to

underlying apply_async() function. See celery documentation for details.

get(ident)

Retrieve a Future object for the specified task.

Arguments:

ident (str): Identifier for task to query.

map(func, *args, **kwargs)

Submit function with iterable of arguments to celery and return FuturePool object containing all task result Future objects.

Arguments:

queue (str): Name of queue to submit function to. countdown (int): Number of seconds to wait before

submitting function.

eta (datetime): Datetime object describing when

task should be executed.

retry (bool): Whether or not to retry the task

upon failure.

*args (list): list of arguments to pass to functions. **kwargs (dict): Keyword arguments to apply for every

function.

processes

Proxy with list of all subprocesses managed by the plugin.

start(timeout=None)

Start local celery workers specified in config.

Arguments:

timeout (int): Timeout to wait for processes to start

after process is submitted. celery status is used to poll the status of workers.

status(timeout=5)

Return status of celery server as dictionary.

stop(timeout=None)

Stop all processes started by this plugin.

Arguments:

timeout (int): Timeout to wait for processes to join

after termination signal is sent.

submit(func, *args, **kwargs)

Submit function to celery worker for processing.

Arguments:

queue (str): Name of queue to submit function to. countdown (int): Number of seconds to wait before

submitting function.

eta (datetime): Datetime object describing when

task should be executed.

retry (bool): Whether or not to retry the task

upon failure.

*args (list): Arguments to function. **kwargs (dict): Keyword arguments to function.

flask_execute.plugin.dispatch(func, *args, **kwargs)

Dynamic abstracted task for pre-registration of celery tasks.

Arguments:

func (callable): Function to deserialize and call. *args (list, tuple): Arguments to pass to function. **kwargs (dict): Keyword arguments to pass to function.

Futures

class flask_execute.futures.Future(result)

Wrapper around celery.AsyncResult to provide an API similar to the concurrent.futures API.

Arguments:

result (AsyncResult): celery.result.AsyncResult object

containing task information and celery context.

add_done_callback(fn)

Attaches the callable fn to the future. fn will be called, with the task as its only argument, when the future is cancelled or finishes running.

Arguments:

fn (callable): Callable object to issue after task has

finished executing.

cancel(*args, **kwargs)

Attempt to cancel the call. If the call is currently being executed or finished running and cannot be cancelled then the method will return False, otherwise the call will be cancelled and the method will return True.

Arguments and keyword arguments passed to this function will be passed into the internal AsyncResult.revoke() method.

cancelled()

Return True if the call was successfully cancelled.

done()

Return True if the call was successfully cancelled or finished running.

exception(timeout=None)

Return the exception raised by the call. If the call hasn’t yet completed then this method will wait up to timeout seconds. If the call hasn’t completed in timeout seconds. If the call completed without raising, None is returned.

Arguments:

timeout (int): Number of seconds to wait for

result to finish before timing out and raising an error.

result(timeout=None)

Wait for task to finish and return result.

Arguments:

timeout (int): Number of seconds to wait for

result to finish before timing out and raising an error.

running()

Return True if the call is currently being executed and cannot be cancelled.

class flask_execute.futures.FuturePool(futures)

Class for managing pool of futures for grouped operations.

Arguments:

futures (list, tuple): Iterable of celery.result.AsyncResult

objects to manage as a group of tasks.

add(future)

Add future object to pool.

Arguments:

future (Future): Future object to add to pool.

add_done_callback(fn)

Attaches the callable fn to the future pool. fn will be called, with the task as its only argument, when the future is cancelled or finishes running.

Arguments:

fn (callable): Callable object to issue after task has

finished executing.

cancel(*args, **kwargs)

Cancel all running tasks in future pool. Return value will be True if all tasks were successfully cancelled and False if any tasks in the pool were running or done at the time of cancellation.

Arguments and keyword arguments passed to this function will be passed into the internal AsyncResult.revoke() method.

cancelled()

Return True if any tasks were successfully cancelled.

done()

Return boolean describing if all tasks in future pool are either finished or have been revoked.

exception()

Return exception(s) thrown by task, if any were thrown during execution.

result(timeout=0)

Wait for entire future pool to finish and return result.

Arguments:

timeout (int): Number of seconds to wait for

result to finish before timing out and raising an error.

running()

Return boolean describing if any tasks in future pool are still running.

state

Return state of future pool.

status

Return status of future pool.

Managers

class flask_execute.managers.TaskManager

Object for managing registered celery tasks, providing users a way of submitting tasks via the celery API when using the factory pattern for configuring a flask application.

This proxy for the @celery.task decorator is designed to manage two things:

1. For applications set up with the flask application directly, register tasks with the celery application directly. This has the same effect as the original mechanism for configuring celery alongside a Flask application.
2. For applications set up using the factory pattern, store all registered tasks internally so they can be registered with the celery application once the plugin as been initialized with a flask application instance.

init_celery(controller)

Initialize the task manager with a celery controller. This will register all decorated tasks with the specified controller (celery application).

Args:

controller (Celery): Celery application instance to

register tasks for.

class flask_execute.managers.CommandManager(name)

Manager for issuing celery inspect or control calls to the celery API.

Example:

>>> inspect = CommandManager('inspect')

# no options
>>> inspect.active()

# options
>>> inspect.active(timeout=5, destination=['w1@e.com', 'w2@e.com'])

This tool is primarily used alongside the Celery plugin object, allowing developers to issue celery commands via property.

Examples:

>>> celery = Celery(app)

# ``inspect`` command manager.
>>> celery.inspect.ping()
{'worker@localhost': {'ok': 'pong'}}

# ``control`` command manager.
>>> celery.control.pool_shrink(1)
{'worker@localhost': {'ok': 'pool will shrink'}}
>>> celery.control.shutdown()
Shutdown signal sent to workers.

Use celery.inspect.help() and celery.control.help() to see available celery commands.

call(cmd, timeout=None, destination=None, quiet=False)

Issue celery subcommand and return output.

Args:

cmd (str): Command to call. timeout (float): Timeout in seconds (float) waiting for reply. destination (str, list): List of destination node names.

help()

Return help message for specific command.