plugin dev

Plugin Development

Add a development directory in the plugin searchpath

Make a directory to host your new plugin or plugins and set it in config.py

BOT_EXTRA_PLUGIN_DIR = '/home/path/to/plugin/root'

Tip : Start the bot in test mode (optional but it helps)

You can start the bot with the "-t" command line parameter. It runs the bot in test mode, a kind of single user mode on pure console (no XMPP server involved here).

It will prompt you :

# err.py -t
[...]
INFO:Plugin activation done.
Talk to  me >> _

Then you can enter all the available commands and it will trust you as an admin. Combine it with the debug mode of an IDE and you have a super snappy environment to try out and debug your code.

Writing a simple plugin

Let say you want to make an helloWorld plugin. First define a class implementing BotPlugin with a method decorated by @botcmd as follow :

helloWorld.py

from errbot.botplugin import BotPlugin
from errbot.jabberbot import botcmd

class HelloWorld(BotPlugin):
    @botcmd                               # this tag this method as a command
    def hello(self, mess, args):          # it will respond to !hello
        """ this command says hello """   # this will be the answer of !help hello
        return 'Hello World !'            # the bot will answer that

Then you need to put some metadescription in a .plug file.

helloWorld.plug

[Core]
Name = HelloWorld
Module = helloWorld
    
[Documentation]
Description = let's say hello !

Start the bot or restart it if it is already live with the command !restart.

Note : Module must match the name of the python module your main class is

That's it ! You can check if the plugin correctly load with the !status command. Then you can check if the hello command is correctly bound with !help. Then you can try it : !hello

If something goes wrong to can inspect the last lines of the log instantly with !taillog

Sending a message asynchronously while computing a command

Often, with commands that takes long, you want to be able to send some feedback to the user that the command is progressing. You can use the helper send to achieve that.

plugin_example.py

    from errbot.botplugin import BotPlugin
    from errbot.jabberbot import botcmd

    class PluginExample(BotPlugin):
        @botcmd
        def longcompute(self, mess, args):
            self.send(mess.getFrom(), "/me is computing ... ", message_type=mess.getType())
            [...] # long processing
            return "Done !"

make err split the arguments for you [v1.2.1]

With the split_args_with argument to botcmd, you can specify a delimiter of the arguments and it will give you an array of strings instead of a string

@botcmd(split_args_with=' ')
    def action(self, mess, args):
        # if you send it !action one two three
        # args will be ['one', 'two', 'three']

subcommands [v1.2.0]

If you put an _ in the name of the function, err will create for you a subcommand. It is useful to categorize a feature

@botcmd
    def basket_add(self, mess, args):
        # it will respond to !basket add

    def basket_remove(self, mess, args):
        # it will respond to !basket remove

Implementing a callback to listen to every messages in the chatrooms

You can add a specific callback that will be called on any message sent on the chatroom. It is useful to react at specific keywords even the the bot is not called explicitely with the ! commands.

plugin_example.py

from errbot.botplugin import BotPlugin
from errbot.jabberbot import botcmd

class PluginExample(BotPlugin):
    def callback_message(self, conn, mess):
        if mess.find('cookie'):
            self.send(mess.getFrom(), "What what somebody said cookie !?", message_type=mess.getType())