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 setup.py using the entry_points concept from Python’s setuptools.

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

Example Plugin

Note

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 setup.py.

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

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

    """
    usage: kiwi-ng relax justdoit -h | --help
           kiwi-ng relax justdoit --now
    
    commands:
        justdoit
            time to relax
    
    options:
        --now
            right now. For more details about docopt
            see: http://docopt.org
    """
    # 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 kiwi.help 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
                return self.manual.show('kiwi::relax::justdoit')
    
            print(
                'https://genius.com/Frankie-goes-to-hollywood-relax-lyrics'
            )
    
  4. Test the plugin

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