Tools & Integrations

doit.tools includes some commonly used code. These are not used by the doit core, you can see it as a “standard library”. The functions/class used with uptodate were already introduced in the previous section.

create_folder (action)

Creates a folder if it does not exist yet. Uses os.makedirs() <http://docs.python.org/2/library/os#os.makedirs>_.

from doit.tools import create_folder

BUILD_PATH = "_build"

def task_build():
    return {'actions': [(create_folder, [BUILD_PATH]),
                        'touch %(targets)s'],
            'targets': ["%s/file.o" % BUILD_PATH]
            }

title_with_actions (title)

Return task name task actions from a task. This function can be used as ‘title’ attribute of a task dictionary to provide more detailed information of the action being executed.

from doit.tools import title_with_actions

def task_with_details():
    return {'actions': ['echo abc 123'],
            'title': title_with_actions}

LongRunning (action)

class doit.tools.LongRunning(action, task=None, save_out=None, shell=True, encoding='utf-8', decode_error='replace', buffering=0, **pkwargs)

Action to handle a Long running shell process, usually a server or service. Properties:

• the output is never captured

• it is always successful (return code is not used)

• “swallow” KeyboardInterrupt

This is useful for executing long running process like a web-server.

from doit.tools import LongRunning

def task_top():
    cmd = "top"
    return {'actions': [LongRunning(cmd)],}

Interactive (action)

class doit.tools.Interactive(action, task=None, save_out=None, shell=True, encoding='utf-8', decode_error='replace', buffering=0, **pkwargs)

Action to handle Interactive shell process:

• the output is never captured

PythonInteractiveAction (action)

class doit.tools.PythonInteractiveAction(py_callable, args=None, kwargs=None, task=None)

Action to handle Interactive python:

• the output is never captured

• it is successful unless a exception is raised

set_trace

doit by default redirects stdout and stderr. Because of this when you try to use the python debugger with pdb.set_trace, it does not work properly. To make sure you get a proper PDB shell you should use doit.tools.set_trace instead of pdb.set_trace.

def need_to_debug():
    # some code here
    from doit import tools
    tools.set_trace()
    # more code

def task_X():
    return {'actions':[(need_to_debug,)]}

IPython integration

A handy possibility for interactive experimentation is to define tasks from within ipython sessions and use the %doit magic function to discover and execute them.

First you need to register the new magic function into ipython shell.

>>> %load_ext doit.tools

Tip

To permanently add this magic-function to your IPython include it on your profile, create a new script inside your startup-profile (i.e. ~/.ipython/profile_default/startup/doit_magic.ipy) with the following content:

from doit import load_ipython_extension
load_ipython_extension()

Then you can define your task_creator functions and invoke them with %doit magic-function, instead of invoking the cmd-line script with a dodo.py file.

Examples:

>>> %doit --help          ## Show help for options and arguments.

>>> def task_foo():
        return {'actions': ["echo hi IPython"],
                'verbosity': 2}

>>> %doit list            ## List any tasks discovered.
foo

>>> %doit                 ## Run any tasks.
.  foo
hi IPython