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
underlyingapply_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 resultFuture
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.
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.
- result (AsyncResult):
-
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 intimeout
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.
- futures (list, tuple): Iterable of
-
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 andFalse
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:
- 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.
- 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
orcontrol
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()
andcelery.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.
-