Plugins

This section describes how plugins can be developed to extend the functionality of Kadi4Mat without having to touch the main application code. As currently all first party plugins are part of the main application package, all existing examples can be found in the kadi.plugins module. This also includes code not implemented as a separate plugin, but still using the plugin hooks.

Plugin infrastructure

The plugin infrastructure in Kadi4Mat builds upon pluggy, a simple and flexible plugin system. It allows implementing different plugin interface functions, called hook specifications, which a plugin can choose to implement. Each hook will be called in certain places in the application flow, which will invoke all corresponding implementations of that hook.

In order for the main application to find a plugin, it has to register itself using the kadi_plugins setuptools entry point, as also done for all first party plugins in setup.py. Each plugin needs to specify a unique name and the module that contains all hook implementations:

entry_points={
    "kadi_plugins": [
        "example=kadi_plugin_example.plugin",
    ],
},

In this case, the plugin is called example, while the hook implementations are loaded via the kadi_plugin_example.plugin module of some package called kadi_plugin_example.

Plugin hooks

Plugin hooks can be implemented by using the hookimpl decorator. The name of the decorated function must correspond to the respective plugin hook. Plugin configurations, specified via the PLUGIN_CONFIG configuration value, can be loaded by using the get_plugin_config function (see also how to install plugins). An example implementation could look like the following:

from kadi.plugins import get_plugin_config
from kadi.plugins import hookimpl

@hookimpl
def kadi_example_plugin_hook():
    # Load the configuration of the "example" plugin, if necessary.
    config = get_plugin_config("example")
    # Do something else.

To see a list of all currently existing hook specifications, please refer to the API reference.

Warning

As long as Kadi4Mat is still in beta, hook specifications are still subject to change without prior deprecation notice.

Plugin API

As plugins might need to make use of Kadi4Mat’s internal functionality in order to properly implement any plugin hooks, a subset of the most relevant functions, classes and modules are available via the kadi.plugins module, as also shown in the example above. This module defines the public API that third party plugins may use without fear of unexpected breaking changes.

Warning

As long as Kadi4Mat is still in beta, the public plugin API is still subject to change without prior deprecation notice.