Adding modules

In this pages you will learn how to add new modules or functions to Granota. You must know Python to do it.

Location

All modules are located at willie/modules/ folder. If you create a file outside this location, it will not load as a module and will not work. We recommend you to choose an easy to remember name for your module as it will be easier for you to reload it from the bot (with the reload command).

Creating a basic module

In this guide we will take as an example the module hello.py, which contains the command hello (with the alias hola and saluda). First of all, let's see the basic structure of any module. Look at this code:

import willie

@willie.module.commands('hello')
def helloworld(bot, trigger):
    bot.say("Hello!")

In the first line, we import willie. This is necessary for all modules. Then, we create the command hello by using the @willie.module.command() decorator. After the decortaror there is the function. The function name must have a different name from any other function and the arguments bot and trigger inside the parenthesis. Inside the function, we make the bot to say Hello! with the function bot.say().

Adding arguments to the command

Ok, now we have our bot saying "Hello" every time you type .hello. Let's make the bot to greet an specific person:

def helloworld(bot, trigger):
    bot.say("Hello %s!" % trigger.group(2))

Now, if you type .hello Mr Smith in IRC, the bot will say "Hello Mr Smith!". trigger.group() is the function that represents the arguments. The number inside parenthesis (in this case 2) represents what argument the bot have to look at. trigger.group(1) represents the command itseld (without the prefix), trigger.group(2) all arguments after the command, trigger.group(3) all arguments after the first argument...

trigger class

trigger class represents things related with the command. The options are the following:

• trigger.group(n): returns the argument n of the command performed.
• trigger.sender: returns the name of the channel where the command has been performed. If the command has been performed in PM, it will return the nick of the sender.
• trigger.nick: returns de nick of the sender.
• trigger.admin: returns True if the sender is in the admins list.
• trigger.owner: returns True if the sender is the bot owner.

bot class

bot class represents actions related with the bot. The options are the following:

• bot.say("string"): makes the bot say the string.
• bot.msg("channel/nick", "message"): sends a message (2nd argument) to the first argument.
• bot.write(("command", "arguments")): sends a raw command to the server.

Example

Let's return to the hello example:

import willie

@willie.module.commands('hello')
def helloworld(bot, trigger):
    if not trigger.sender.startswith('#'): # Only works in channels
        return
    if trigger.admin: # Restricted to admins
        if not trigger.group(2): # If there aren't any arguments...
            bot.say("Hello!")
        else:
            bot.msg(trigger.group(2), "Hello there!") # If there is an argument, send a private message to the argument with "Hello there!"

So, that's it. It should be enough to get started and, remember, if you need help, ask! Read the "Submiting pull requests" page if you want to contribute.