Plugins

This page documents the plugins that ship with the PyBuilder distribution.

QA plugins

Running Python Unittests

PyBuilder ships with a plugin to execute unittests written using Python’s unittest module during the build. Use the python.unittest plugin to enable unittest support.

The plugin executes all test cases found in modules ending with _tests.py in the directory src/unittest/python.

Python unittest properties

Measuring unittest coverage

PyBuilder adds support to measure the coverage of your unittest using the coverage module. Use the python.coverage module to activate coverage.

Coverage properties

Please note that properties coverage_reload_modules and coverage_fork are deprecated and will not be used.

SonarQube integration

Using the plugin python.sonarqube will add the task run_sonar_analysis to your project. This task has a run-time dependency to the sonar-runner program and will submit your project to sonarqube for analysis.

SonarQube configuration

Linting python sources

Frosted plugin

Frosted is a fork of pyflakes (originally created by Phil Frost) that aims at more open contribution from the outside public, a smaller more maintainable code base, and a better Python checker for all.

Frosted configuration

Flake8 plugin

PyBuilder can lint your files and verify (or enforce) compliance with PEP8 and PyFlakes through the flake8 module. Use the python.flake8 module to activate linting.

Flake8 configuration

Pychecker plugin

Using the plugin python.pychecker will let pychecker run on python source modules.

Pychecker configuration

Pylint plugin

Using the plugin python.pylint will let pylint run on python source modules.

Pylint configuration

Pep8 plugin

Using the plugin python.pep8 will let pep8 run on python sources. There is no configuration possible currently, consider using the flake8 plugin instead.

Pymetrics plugin

Using the plugin python.pymetrics will let pymetrics run on all python source files. There is no configuration possible currently, consider using the flake8 plugin instead.

Running Python Integration Tests

PyBuilder ships with a plugin to run integration tests written in Python. The plugin is named python.integrationtest. It executes all python modules named *_tests.py in the src/integrationtest/python directory.

However, the default run_integration_tests job is just a stub per default , which won’t run your integration tests. In order to use integration tests, you will have to enable the module by specifying use_plugin('python.integrationtest'). If you don’t specify this, your integration tests will not be run.

Every module is executed as a Python module. The Python path contains the integration test directory as well as the production source directory.

Integration test properties

Running Cram tests

Cram is a functional testing framework for command line applications based on Mercurial’s unified test format.

The plugin python.cram can be used to run tests written for cram. Cram tests run during run_integration_tests but there is also a separate task available (run_cram_tests).

if not sys.version_info[0:2] == (3,2):
    use_plugin("python.cram")

Cram properties

Python deployment

Python core

The python core plugin deals with sources and distributions. It copies the sources into the distribution directory.

Python core properties

Installing dependencies

PyBuilder manages build and runtime dependencies for you. Use the python.install_dependencies module to activate dependency management. This will make the following tasks available:

Declaring dependencies

The project object exposes the following methods for declaring dependencies

Requirements file :

project.depends_on_requirements("requirements.txt")

project.build_depends_on_requirements("requirements-dev.txt")

Runtime dependencies :

project.depends_on("awesome-library")

Build dependencies :

project.build_depends_on("awesome-library")

Note that the *_depends_on methods accept the following arguments :

The logic of version goes as follows:

• If you don’t specify any version, you don’t care about the version and any version will do, so PyB will get whatever version if one doesn’t exist and then don’t bother ever updating.
• If you specify an exact version once it is obtained there is no point in updating it.
• If you specify a fuzzy version, you want the latest and greatest that satisfies the expression specified. This aids rapid incompatibility detection, as PyBuilder tracks the latest version that always satisfies the version specifier.

Install dependencies configuration

Creating a source distribution

PyBuilder can build a source distribution of your code with the plugin source_distribution. Activating this plugin will expose a task, build_source_distribution.

Source distribution configuration

Building a Python package

PyBuilder ships a plugin that generates and executes setup.py files using with distutils or setuptools (distribute will be supported in future releases). In order to generate a setup.py file use the python.distutils plugin.

The distutils plugin will consider many of the project’s attributes, i.e.

• name
• version
• summary
• description
• author
• license
• url

Moving scripts to a nested directory

By default, executable scripts are located at the egg’s root. The setup.py contains the bare script names. Sometimes though you may want to move the scripts inside a directory to avoid naming collisions (i.e. with packages).

The python.core and python.distutils plugins support the property dir_dist_scripts that can name a directory to contain scripts inside the egg. This property is empty by default. Set it to the local name of the directory you want the scripts to be moved to:

@init
def initialize (project):
    project.set_property("dir_dist_scripts", 'scripts')

...

Distutils properties

Each distutils_commands is called individually with clean --all parameter. The reason that clean --all is used is to ensure that if PyBuilder is generating multiple packages (bdist_wheel vs dumb vs bdist) that the build/ directory doesn’t cross-contaminate the builds. Some use absolute paths, some use relative.

Distutils property examples

distutils_command_options

project.set_property('distutils_commands', 'build')
project.set_property('distutils_command_options',
                     {'build': ('-e', '/opt/python2.7/bin/python', 'bdist_wheel')})

distutils_console_scripts

project.set_property('distutils_console_scripts', [
    "some_console1 = some_module1:some_function1",
    "some_console2 = some_package.some_module2:some_function2"])

distutils_entry_points

project.set_property('distutils_entry_points', {
    'console_scripts': [
        "some_console1 = some_module1:some_function1",
        "some_console2 = some_package.some_module2:some_function2"],
    'some.entry.point': [
        'value1 = some_module3:some_function3',
        'value2 = some_module4:some_function4']})

Copying resources into a distribution

In some cases you want to include non-source files in a distribution. An example is adding a setup.cfg to your project. It is not a source file, but it needs to be in the distribution to work (beneath the setup.py file). The copy_resources plugin will do this for you at build-time.

Copy resources configuration

Filtering files

With the filter_resources plugin, it is possible to replace placeholder values of type ${version} with actual values at build-time. The actual values are the attributes and the properties dict of the project object. So ${version} will be replaced with the value of project.version and ${some_property} by project.get_property('some_property'). In order to make resource filtering explicit, all files that go through filtering need to be specified with a glob.

Filter resources configuration

Filter resources example

A common use case is keeping a __version__ attribute in your main module. But you don’t want to specify the version both in build.py and in __init__.py because build.py should be the single point of truth.

So just use __version__ = '${version}' in __init__.py.

We can tell the plugin to filter this file by adding ['**/YOUR-PACKAGE-NAME/__init__.py'] to the filter_resources_glob. The correct version will be patched in at run-time since the version is defined in project.version. For filtering other attributes like ${myattribute}, just add a project.myattribute = "foobar" in build.py’s initializer.

Creating documentation with sphinx

The plugin python.sphinx will expose the task sphinx_generate_documentation which will generate the project documentation.

Sphinx plugin configuration

Generic build plugins

Executing shell commands

PyBuilder ships with a plugin that allows you to incorporate arbitrary shell commands in the build process.

This plugin can be activated using use_plugin("exec") and is configured through the project properties.

Adding a shell command to the build process

Adding commands is done by setting properties and is discrete towards the project lifecycles, thus you may have only one shell command for the analyze lifecycle for example.

The output of the plugin can also be customized by using the properties $PHASE_propagate_stdout and $PHASE_propagate_stderr.

See the properties for the phase run_unit_tests for example:

IDE integration

Project files for Eclipse PyDev

If the plugin python.pydev is used, PyBuilder provides the task pydev_generate. This task can be used to generate PyDev project files in the project root directory. The project can then be imported easily.

Project files for Jetbrains PyCharm

If the plugin python.pycharm is used, PyBuilder provides the task pycharm_generate. This task can be used to generate a PyCharm project files in the project root directory. The project can then be imported easily through the Open... command.

Developer tools

Visual feedback for tests

The python.pytddmon plugin provides the task pytddmon which will start a graphical application that gives real-time feedback about passing or failing unit tests. Please see the pytddmon page (http://pytddmon.org/ broken link) for more information about pytddmon.

Additional project structure

Splitting up your build.py with bldsup

Maybe you want to have project specific plugins and support code while keeping your build.py file small, while avoiding to clutter your project’s root directory. This can be done by activating bldsup support :

from pybuilder.core import use_bldsup
use_bldsup(build_support_dir="bldsup")

If it’s not called in a project’s build.py, then no “bldsup” directory is searched. If it is called, then it confirms that the build_support_dir directory exists and that includes a __init__.py file so imports will work. It just needs to be called before you try to import/use_plugin() any modules from the build_support_dir.