Plugin Architecture

Each command provided by KIWI NG is written as a task plugin under the kiwi.tasks namespace. As a developer you can extend KIWI NG with custom task plugins if the following conventions are taken into account:

Naming Conventions

Task Plugin File Name

The file name of a task plugin must follow the pattern <service>_<command>.py. This allows to invoke the task with kiwi-ng service command ...

Task Plugin Option Handling

KIWI NG uses the docopt module to handle options. Each task plugin must use docopt to allow option handling.

Task Plugin Class

The implementation of the plugin must be a class that matches the naming convention: <Service><Command>Task. The class must inherit from the CliTask base class. On startup of the plugin, KIWI NG expects an implementation of the process method.

Task Plugin Entry Point

Registration of the plugin must be done in using the entry_points concept from Python’s setuptools.

'packages': ['kiwi_plugin'],
'entry_points': {
    'kiwi.tasks': [

Example Plugin


The following example assumes an existing Python project which was set up according to the Python project rules and standards.

  1. Assuming the project namespace is kiwi_relax_plugin.

    Create the task plugin directory kiwi_relax_plugin/tasks

  2. Create the entry point in

    Assuming we want to create the service named relax providing the command justdoit this would be the following entry point definition in

    'packages': ['kiwi_relax_plugin'],
    'entry_points': {
        'kiwi.tasks': [
  3. Create the plugin code in the file kiwi_relax_plugin/tasks/ with the following content:

    usage: kiwi-ng relax justdoit -h | --help
           kiwi-ng relax justdoit --now
            time to relax
            right now. For more details about docopt
    # These imports requires kiwi to be part of your environment
    # It can be either installed from pip into a virtual development
    # environment or from the distribution package manager
    from kiwi.tasks.base import CliTask
    from import Help
    class RelaxJustdoitTask(CliTask):
        def process(self):
            self.manual = Help()
            if self.command_args.get('help') is True:
                # The following will invoke man to show the man page
                # for the requested command. Thus for the call to
                # succeed a manual page needs to be written and
                # installed by the plugin
  4. Test the plugin

    $ ./ develop
    $ kiwi-ng relax justdoit --now