TaskFlow/Task Arguments and Results

Overview

In TaskFlow, all flow state should go to storage. That includes all the information that task needs when it is executed (task arguments), and all the information task produces (task results). Developer who implements task or flow can specify what arguments task accepts and what result it returns in several ways.

Set of names of task arguments is available as requires property of the task instance. When task is about to be executed values with this names are retrieved from storage and passed to execute method of the task as keyword arguments.

Set of names of task results (what task provides) is available as provides property of task instance. After task finishes successfully, it's result(s) (what task execute method returns) are available by these names from storage (there will be examples below).

Arguments Specification

There are different way to specify task argument set.

Arguments Inference

Task arguments can be inferred from arguments of execute method of the task. For example:

   >>> class MyTask(task.Task):
   ...     def execute(self, spam, eggs):
   ...         return spam + eggs
   ... 
   >>> MyTask().requires
   set(['eggs', 'spam'])

Inference from signature is simplest way to specify task arguments. Optional arguments (with default values), and special arguments like self, *args and **kwargs are ignored on iferrence:

   >>> class MyTask(task.Task):
   ...     def execute(self, spam, eggs=()):
   ...         return spam + eggs
   ... 
   >>> MyTask().requires
   set(['spam'])
   >>>
   >>> class UniTask(task.Task):
   ...     def execute(self,  *args, **kwargs):
   ...         pass
   ... 
   >>> UniTask().requires
   set([])

Rebind

There are cases when value you want to pass to task is stored with name other then corresponding task argument. That's when rebind task constructor parameter comes handy. Using it flow author can instruct engine to fetch a value from storage by one name, but pass it to task's execute method with another.

There are two possible way of using it. First is to pass dictionary that maps task argument name to name of saved value. For example, if you have task:

   class SpawnVMTask(task.Task):
       def execute(self, vm_name, vm_image_id, **kwargs):
           pass  # TODO(imelnikov): use paramters to spawn vm

and you saved vm name with 'name' key in storage, you can spawn vm with such name like this:

   SpawnVMTask(rebind={'vm_name': 'name'})

Second, you can pass a tuple or list of argument names, and values with that names are passed to task. The length of tuple or list should not be less then number of task required parameters. For example, you can achieve same effect as the previous example with:

   SpawnVMTask(rebind_args=('name', 'vm_image_id'))

which is equivalent to more elaborate

   SpawnVMTask(rebind=dict(vm_name='name',
                           vm_image_id='vm_image_id'))

In both cases, if your task accepts arbitrary arguments with **kwargs construct, you can specify extra arguments. For example:

   SpawnVMTask(rebind=('name', 'vm_image_id', 'admin_key_name'))

When such task is about to be executed, name, vm_image_id and admin_key_name values are fetched from stroage, and, and value from name is passed to execute method as vm_name, value from vm_image_id is passed as vm_image_id, and value from admin_key_name is passed as admin_key_name parameter in kwargs.

Manually Specifying Requirements

TODO(imelnikov): describe requires parameter, optional task args and **kwargs.