How to create a plugin

First, make sure you have got your [Ludolph bot installed and configured](How to install and configure Ludolph)

---

Create core plugin

XMPP Extensions can be built into Ludolph core.

1. In the ludolph/plugins directory create a new file with the name of your plugin, e.g. sample.py

2. Inside that directory create a class with the same name as your file; it has to be a child of the LudolphPlugin class

    from ludolph.plugins.plugin import LudolphPlugin
   
    class Sample(LudolphPlugin):
        __version__ = __version__
        ...
   

3. Each function with the @command decorator will be a Ludolph command

4. Add a new section (it can be empty) named after your plugin file into the Ludolph configuration file; e.g. [sample]

5. After reloading Ludolph you can use your plugin (check the log file in case of problems)

Create 3rd party plugin

Other extensions can be created as 3rd party plugins. Creating a 3rd party plugin is almost the same as creating a core plugin. One minor difference is that when registering with Ludolph configuration file use the whole python path for the section name (like a python import); e.g. [thirdparty.plugin.sample]

We have prepared a ludolph-skeleton repository that contains a hello_world plugin. Skeleton has a structure of a pip installable application (for hello_world installation see the repository README file). It contains a plugin with three sample commands, each using different decorators for sample usage.

Plugin naming convention

Project name = ludolph_<project>: where ludolph-<project> is a github and pypi package name.

Path to plugin = ludolph_<project>.<plugin>: where plugin is created from plugin class name, lower-cased and using underscores instead of spaces.

Plugin versions

Ludolph has a version command in its base set of commands. You can add version support to your plugin, by adding __version__ attribute into your plugin class.

from ludolph.plugins.plugin import LudolphPlugin
from sample_plugin import __version__

class SamplePlugin(LudolphPlugin):
    """
    Ludolph jabber bot sample plugin.
    """
    __version__ = __version__