doit logo

Table Of Contents

Project Links

Sponsors

Your logo here

Sponsor/Donate to doit


Why Donate? Donations will be used to sponsor futher development of the project and participation in conferences.

For coorporate donations the logo of your company will be placed on this website side-bar (see above). For more information please contact schettino72@gmail.com



Command line interface - run

The doit command line contains several sub-commands. Most of the time you just want to execute your tasks, that’s what run does. Since it is by far the most common operation it is also the default, so if you don’t specify any sub-command to doit it will execute run. So $ doit and $ doit run do the same thing.

The basics of task selection were introduced in Task Selection.

python -m doit

doit can also be executed without using the doit script.

$ python -m doit

This is specially useful when testing doit with different python versions.

dodo file

By default all commands are relative to dodo.py in the current folder. You can specify a different dodo file containing task with the flag -f. (This is valid for all sub-commands)

$ doit -f release.py

doit can seek for the dodo.py file on parent folders if the the option --seek-file is specified.

verbosity

By default the stdout from a task is captured and its stderr is sent to the console. If the task fails or there is an error the stdout and a traceback (if any) is displayed.

There are 3 levels of verbosity:

0:
capture (do not print) stdout/stderr from task.
1 (default):
capture stdout only.
2:
do not capture anything (print everything immediately).

You can control the verbosity by:

  • –verbosity/-v command line option.

    change verbosity of all executed tasks.

$ doit --verbosity 2
  • task attribute verbosity
def task_print():
    return {'actions': ['echo hello'],
            'verbosity': 2}
$ doit
.  print
hello

parameters

It is possible to pass option parameters to the task through the command line.

Just a add a ‘params’ field to the task dictionary. params must be a list of dictionaries where every entry is an option parameter. Each parameter must define a name, and a default value. It can optionally define a “short” and “long” names to be used from the command line (it follows unix command line conventions). It may also specify a type the parameter should be converted to.

See the example:

def task_py_params():
    def show_params(param1, param2):
        print param1
        print 5 + param2
    return {'actions':[(show_params,)],
            'params':[{'name':'param1',
                       'short':'p',
                       'default':'default value'},

                      {'name':'param2',
                       'long':'param2',
                       'type': int,
                       'default':0}],
            'verbosity':2,
            }

def task_cmd_params():
    return {'actions':["echo mycmd %(flag)s xxx"],
            'params':[{'name':'flag',
                       'short':'f',
                       'long': 'flag',
                       'default': ''}],
            'verbosity': 2
            }

For python-actions the python function must define arguments with the same name as a task parameter.

$ doit py_params -p abc --param2 4
.  py_params
abc
9

For cmd-actions use python string substitution notation:

$ doit cmd_params -f "-c --other value"
.  cmd_params
mycmd -c --other value xxx

title

By default when you run doit only the task name is printed out on the output. You can customize the output passing a “title” function to the task:

def show_cmd(task):
    return "executing... %s" % task.name

def task_custom_display():
    return {'actions':['echo abc efg'],
            'title': show_cmd}
$ doit
.  executing... Cmd: echo abc efg

dir (cwd)

By default relative paths of file used on the dodo file and the “current working directory” used on python execution is the same as the location of the dodo file. You can specify a different cwd with the –dir/-d option.

$ doit --dir path/to/another/cwd

continue

By default the execution of tasks is halted on the first task failure or error. You can force it to continue execution with the option –continue/-c

$ doit --continue

parallel execution

doit supports parallel execution –process/-n. By default the multiprocessing module is used. So the same restrictions also apply to the use of multiprocessing in doit.

$ doit -n 3

You can also execute in parallel using threads by specifying the option –parallel-type/-P.

$ doit -n 3 -P thread

reporter

doit provides different “reporters” to display running tasks info on the console. Use the option –reporter/-r to choose a reporter. Apart from the default it also includes:

  • executed-only: Produces zero output if no task is executed
  • json: Output results in JSON format
  • zero: display only error messages (does not display info on tasks being executed/skipped). This is used when you only want to see the output generated by the tasks execution.
$ doit --reporter json

custom reporter

It is possible to define your own custom reporter. Check the code on doit/reporter.py ... It is easy to get started by sub-classing the default reporter as shown below. The custom reporter must be configured using DOIT_CONFIG dict.

from doit.reporter import ConsoleReporter

class MyReporter(ConsoleReporter):
    def execute_task(self, task):
        self.outstream.write('MyReporter --> %s\n' % task.title())

DOIT_CONFIG = {'reporter': MyReporter,
               'verbosity': 2}

def task_sample():
    for x in range(3):
        yield {'name': str(x),
               'actions': ['echo out %d' % x]}

Note that the reporter have no control over the real time output from a task while it is being executed, this is controlled by the verbosity param.

output-file

The option –output-file/-o let you output the result to a file.

$ doit --output-file result.txt

config

Command line parameters can be set straight on a dodo file. This example below sets the default tasks to be run, the continue option, and a different reporter.

DOIT_CONFIG = {'default_tasks': ['my_task_1', 'my_task_2'],
               'continue': True,
               'reporter': 'json'}

So if you just execute

$ doit

it will have the same effect as executing

$ doit --continue --reporter json my_task_1 my_task_2

You need to check doit_cmd.py to find out how parameter maps to config names.

Note

The parameters –file and –dir can not be used on config because they control how the dodo file itself is loaded.

returned value

doit process returns:

  • 0 => all tasks executed successfully

  • 1 => task failed

  • 2 => error executing task

  • 3 => error before task execution starts

    (in this case the reporter is not used)

bash completion

Bash completion for doit to auto-complete task names is available at bash_completion_doit . To activate it:

$ source <path-to-file>/bash_completion_doit