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 theCliTask
base class. On startup of the plugin, KIWI NG expects an implementation of theprocess
method.- Task Plugin Entry Point
Registration of the plugin must be done in
setup.py
using theentry_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.
Assuming the project namespace is kiwi_relax_plugin.
Create the task plugin directory
kiwi_relax_plugin/tasks
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' ] }
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' )
Test the plugin
$ ./setup.py develop $ kiwi-ng relax justdoit --now