Bolt Provided Tasks

Bolt provides the implementation of a few common tasks that most Python projects should be able to leverage their functionality. This tasks are registered when Bolt is executed, and users only need to configure and invoke them in their boltfile.py.

The following documents the included tasks and how they work.

delete-files

This task deletes files matching a specified pattern found in a specified sourcedir. A recursive flag can be specified to search also in sub-directories of sourcedir.

The pattern specified follows the matching rules of the Python standard library glob.glob() function.

The following example configures the delete-file task to delete all the files in a tmp directory located at the project root, and all its sub-directories:

config = {
    'delete-files': {
        'sourcedir': './tmp',
        'pattern': '*.*',
        'recursive': True
    }
}

The sourcedir configuration option indicates the directory to search for file matches. This option is required.

The pattern option specifies the matching pattern to find files. This option is required.

The recursive option indicates if sub-directories should be searched for matches. This option is optional and has a value of False by default.

delete-pyc

Searches for .pyc in the specified directory and deletes them. The task allows to recursively search sub-directories for .pyc files.

The following example shows how to configure the task to recursively delete files from a source directory and its sub-directories:

config = {
    'delete-pyc': {
        'sourcedir': './source',
        'recursive': True
    }
}

The sourcedir option specifies the directory to search for .pyc files. This option is required.

The recursive option indicates if sub-directories should be searched for matches. This option is optional and has a value of False by default.

class bolt.tasks.bolt_delete_files.DeleteFilesTask

class bolt.tasks.bolt_delete_files.DeletePycTask

mkdir

Creates the directory specified, including intermediate directories, if they do not exist:

config = {
    'mkdir': {
        'directory': 'several/intermediate/directories'
    }
}

class bolt.tasks.bolt_mkdir.ExecuteMKDir

shell

The shell task allows executing a shell command with specified arguments inside the bolt execution context. This task comes handy when no bolt specific implementation has been provided for a particular task or to invoke an existing script that should be included as part of the process.

The trade-off of using this task is that commands are system specific and it makes it harder to implement a cross-platform boltfile.py.

The task takes a command parameter specifying the command to be executed, and an arguments option that must be set to a list of string for each of the command line argument tokens to be passed to the tool.

The following example shows how to invoke an existing Python script that takes a few parameters:

config = {
    'shell': {
        'command': 'python',
        'arguments': ['existing_script.py', '--with-argument', '-f', '--arg-with', 'a_value']
    }
}

Todo

Find a better example.

exception bolt.tasks.bolt_shell.ShellError(shell_code)

class bolt.tasks.bolt_shell.ShellExecuteTask

pip

The pip task provides an automation hook to execute pip inside of Bolt. In its simplest form, the task does not require any configuration, and it just assumes a requirements.txt file is provided at the current working directory, which will be used to execute a pip install.

The task also provides a simple form where a command and package are specified to allow install a single package.

config = {
    'pip': {
        'command': 'install',
        'package': 'package_name'
    }
}

The supported pip functionality can be configured by setting the command option to a valid pip command, and providing a set of arguments to pip as an options dictionary where the keys are valid pip arguments in short or long form without leading dashes and the values are the respective argument values, or True in the case of flags. The following shows a more advance use of this task.

config = {
    'pip': {
        'command': 'install',
        'options': {
            'r': './data/project_requirements.txt',
            'target': './requirements',
            'upgrade': True,
            'force-reinstall': True
        }
    }
}

class bolt.tasks.bolt_pip.ExecutePipTask

exception bolt.tasks.bolt_pip.PipError(pip_code)

set-vars

Sets environment variables for all specified variable:value pairs. The following shows how the task is configured:

config = {
    'set-vars': {
        'vars': {
            'STRING_VAR': 'string_value',
            'INT_VAR': 10
        }
    }
}

Numeric vars will be converted to their integer representation.

class bolt.tasks.bolt_set_vars.SetVarsTask

setup

The setup task provides an automation hook to execute setup.py commands and options inside of Bolt. The task, in its simplest form, assumes a default setup.py in the current working directory and uses a build command as a default if no configuration is provided.

The task configuration allows spcifying a setup script, which by default will be set to setup.py if no script is specified, a valid command, and it command arguments. The following example shows how to configure the task.

config = {
            'setup':{
                    'script': 'special_setup.py',
                    'command': 'install',
                    'options': {
                            'verbose': True,
                            'dry-run': True
                    }
            }
}

exception bolt.tasks.bolt_setup.BuildSetupError(code=4)

class bolt.tasks.bolt_setup.ExecuteSetupTask

nose

Executes unit tests using nose and nosetests as the unit test runner. The task allows to specify the directory where the tests are located through the directory parameter and supports all the arguments available in the installed version of nosetests:

config = {
    'nose': {
        'directory': 'test/unit',
        'options': {
            'xunit-file': 'output/unit_tests.xml'
            'with-coverage': True,
            'cover-erase': True,
            'cover-package': 'mypackage',
            'cover-html': True,
            'cover-html-dir': 'output/coverage',
        }
}

class bolt.tasks.bolt_nose.ExecuteNoseTask

exception bolt.tasks.bolt_nose.NoseError(nose_code)

conttest

This task uses conttest to monitor a directory for changes and executes the specified task everytime a change is made. The following configuration is supported:

config = {
    'conttest': {
        'task': 'registered_task',
        'directory': './directory/to/monitor/'
    }
}

The task parameter is the task to be executed and must be registered in boltfile.py. The directory parameter is the directory (including sub-directories) to monitor for changes.

To use this task, you need to have conttest installed, which you can do by calling:

pip install conttest

class bolt.tasks.bolt_conttest.ExecuteConttest