Tasks

Every task must define actions. It can optionally defines other attributes like targets, dependencies, doc ...

actions

Actions define what the task actually do. A task can define any number of actions. There 2 kinds of actions: cmd-action and python-action.

cmd-action

If action is a string it will be executed by the shell.

The result of the task follows the shell convention. If the process exits with the value 0 it is successful. Any other value means the task failed.

python-action

If action is a tuple (callable, *args, **kwargs) - only callable is required. args is a sequence and kwargs is a dictionary that will be used as positional and keywords arguments for the callable. see *args and **kwargs.

The result of the task is given by the returned value of the action function. So it must return a boolean value True to indicate successful completion of the task. Or False to indicate task failed. If it raises an exception, it will be considered an error.

example - dynamic

It is easy to include dynamic (on-the-fly) behavior to your tasks. Let’s take a look at another example:

def task_hello():
    """hello from shell & python! """

    def python_hello(times, text):
        output = open("hello.txt", "a")
        output.write(times * text)
        output.close()
        return True

    msg = 3 * "hi! "
    return {'actions': ['echo %s > hello.txt' % msg,
                        (python_hello, [3, "py!\n"])]
            }

sub-tasks

Most of the time we want to apply the same task several times in different contexts.

The task function can return a python-generator that yields dictionaries. Since each sub-task must be uniquely identified it requires an additional field name.

def task_create_file():
    for i in range(3):
        filename = "file%d.txt" % i
        yield {'name': filename,
               'actions': ["touch %s" % filename]}

eduardo@eduardo:~$ doit
create_file:file0.txt => Cmd: touch file0.txt
create_file:file1.txt => Cmd: touch file1.txt
create_file:file2.txt => Cmd: touch file2.txt
create_file => Group: create_file:file0.txt, create_file:file1.txt, create_file:file2.txt

groups

You can define group of tasks by adding tasks as dependencies and setting its actions to None.

def task_foo():
    return {'actions': ["echo foo"]}

def task_bar():
    return {'actions': ["echo bar"]}

def task_mygroup():
    return {'actions': None,
           'dependencies': [':foo', ':bar']}

Note that task is never executed twice in the same “run”.