Welcome to Pipobot’s documentation!¶

Config section¶

In this section you will have to provide general parameters for pipobot, eg parameters independent of rooms and modules. Here is a list of parameters you can use:

• logpath: a relative or absolute path to a log file for pipobot
• xmpp_logpath: a relative or absolute path to log all debug related to XMPP communication. This will only be useful in debug mode otherwise nothing will be logged (see General command-line options).
• force_ipv4: the bot will try to connect to the XMPP server in IPv6 (if a DNS record exists) if this boolean is not provided.
• lang: the language the application will use
• modules_path: a list of directories (relative or absolute) where the bot will try to find modules.

Database section¶

Configuration of the database which will be used by the bot. Supported engines are: MySQL, PostgreSQL, SQLite, with their respecting configuration.

Room section¶

A room is a reference to an XMPP MUC that the bot will join. It requires these parameters:

• chat: the MUC it will join (room@domain.tld).
• address: the address of the XMPP server (optional, default is extracted from the JID of the bot).
• port: the port of the XMPP server (optional, default is 5222).
• login: the JID used to authenticate to an XMPP server.
• passwd: the password used for the authentication.
• resource: the resource of the bot
• nick: the nickname of the bot in the MUC
• modules: a list of modules or groups to load for this room. Groups must be prefixed with an underscore.

Group section¶

A group is a list of modules we create that can be referenced in a room configuration (see the Room section above). example:

groups:

group1:

• module1
• module2

group2:

• module1
• module3

Then in the modules parameter of a room can add _group1 or _group2.

Module-config section¶

In the module_config section you will define modules specific configuration. You can refer to the documentation of these modules to determine how to configure them, or if there is no such documentation to messages given by the bot when it is started: it will inform you that some configuration parameters are missing, or what default parameters are used instead.

Modules configuration are defined this way:

module_config:

module_name:

param1: a single value

param2:

• a list
• of items

param3:

key: value

Testing section¶

The testing section is what will define which parameters and which modules the bot will use when started in testing modes (see Unit-test mode). You will need to provide these parameters:

• fake_nick: a nickname for the bot.
• fake_chan: a fake chan name (like XMPP MUC name).
• modules: a list of modules, just like in a real room.

General command-line options¶

When you start the bot in XMPP mode, you can use these options (use pipobot -h to retrieve them):

--version         show program's version number and exit
-h, --help        show this help message and exit
-q, --quiet       Log and print only critical information
-d, --debug       Log and print debug messages
-b, --background  Run in background, with reduced privileges
--pid=PID_FILE    Specify a PID file (only used in background mode)

You can also always specify a configuration file (default being /etc/pipobot.conf.yml):

pipobot /path/to/alternative/config

Check-modules mode¶

In this mode the bot will only check the configuration file, check all modules and verify that you provided all required configuration parameters.

To use this mode use:

--check-modules   Checks if modules' configuration is correct

Unit-test mode¶

In this mode, unit test modules will be used and started to detect errors. It will use the testing section of the configuration file (see Testing section).

If you want to learn more about unit test, you can refer to Unit Tests.

To use this mode use:

--unit-test       Run unit test defined in the config file

Example:

pipobot --unit-test

test_todo_add (todo.TodoAdd)
!todo add ... ok
test_todo_remove (todo.TodoRemove)
!todo remove ... ok
test_search (todo.TodoSearch)
!todo search ... ok

----------------------------------------------------------------------
Ran 3 tests in 1.054s

OK

Script mode¶

This mode allows you to start the bot with a pre-defined list of commands. Commands are separated with a ;. It will generate their outputs and display them to you. Example:

pipobot --script=":help;http://www.google.fr;:todo list all"

--> :help
<== I can execute:
-todo
--> http://www.google.fr
<== [Lien] Titre : Google
--> :todo list all
<== TODO-list vide

Interactive mode¶

This mode is provided to simulate an XMPP room locally. You can start the bot in this mode with:

pipobot --interract

Loaded modules will be those defined in the testing section of the configuration file (see Testing section). This will start a server waiting for fake XMPP clients to connect. To create a new client you can use the pipobot-twisted provided application:

pipobot-twisted foo

This will create a new client called foo connecting to the fake server. You can then enter your commands and see the result :

pipobot-twisted foo

Connected to server
Welcome !
*** foo has joined
!help
<foo> !help
<Pipo-test> I can execute:
-todo
!todo add liste un test
<foo> !todo add my_list a test
<Pipo-test> TODO added
!todo list
<foo> !todo list
<Pipo-test> All TODO-lists:
my_list
!todo list my_list
<foo> !todo list my_list
<Pipo-test> my_list :
1 - a test (by foo on 2012/03/10 at 16:20)

You can start multiple client to the room as long as they have different nicknames.

Types of modules¶

There are several classes of modules, depending on what you are trying to achieve.

<user> !date
<bot> Today is `insert the date of the day here !`

<user> Here is an awesome link : http://pipobot.xouillet.info !
<bot> [Lien] Titre : Forge xouillet

*** user has joined the room
<bot> user: welcome to the room !!

What they can return¶

def some_function(self, sender, message):
    return ["msg1", "msg2", "msg3"]

<bot> msg1
<bot> msg2
<bot> msg3

return {"text" : "*Message for clients which don't support XHTML*",
        "xhtml" : "<b>Message for clients which do support XHTML</b>"
        }

raw_msg =  "| Some       | tabular   |\n"
raw_msg += "| requiring  | monospace |"
return {"text" : raw_msg,
        "monospace" : True}

<p>
    <span style="font-family: monospace">
        | Some       | tabular   | <br />
        | requiring  | monospace |
    </span>
</p>

return { "user1" : { "text": "Message for user1",
                     "monospace": True },
         "user2" : { "text" : "raw message for user2",
                     "xhtml" : "<p> an <b> XHTML </b> message for user2 </p>"}
        }

Using configuration parameters¶

Some modules may require configuration parameters that will be provided by the pipobot‘s main configuration file.

pipobot includes a syntax to define such parameters, and will automatically:

• check if required parameters are present
• replace optional parameters by a default value
• check if provided parameters are correct (type verification)

To add parameters to a module you must provide a _config attribute to the module class, listing them. For example if we want a module to parse the several sample of configuration:

modules_config:
    my_module:
        param1: True
        param2:
            - foo
            - bar
        param3:
            key1: val1
            key2: val2
        # OPTIONAL
        param4: "somestring"

In the corresponding module class we will add:

class MyModule(SyncModule):
    _config = (("param1", bool, None), ("param2", list, None),
               ("param2", dict, None), ("param4", string, "somestring))

Then in the code of the module we will be able to access to these parameters with self.param1, self.param2...

Possible types of parameters are defined by the yaml language:

• a boolean
• a string
• an int
• a list
• a dictionary

Each element of the _config array is a parameter constructed with (name, type, default_value), None in default_value meaning that the parameter is not optional.

SyncModule¶

<user> !date
<bot> Today is `insert the date of the day here !`

<user> !todo
<bot> This is a command to handle TODO-list
<user> !todo list
<bot> Here is the list of all TODO : …
<user> !todo add some_list I have TODO this !
<bot> The todo 'I have TODO this !' has been successfully added to 'some_list'

def some_name(self, sender, message):

<user> !todo add some_list I have TODO this !

from lib.modules import SyncModule, answercmd, defaultcmd

class CmdTodo(SyncModule):
    def __init__(self, bot):
        desc = "A TODO module"
        command_name = "todo"
        SyncModule.__init__(self, bot, desc, command_name)

    @answercmd("add")
    def add(self, sender, args):
        #what to do with !todo add some other args
        pass

    @answercmd("list")
    def list(self, sender, args):
        #what to do with !todo list some other args
        pass

    @answercmd("rm", "del")
    def rm(self, sender, args):
        #what to do with !todo rm or !todo del  some other args
        pass

    @defaultcmd
    def default(self, sender, message):
        #In any other case this will be called
        pass

!todo
!todo should RTFM
!todo don't know what i am doing

class CmdTodo(SyncModule):
    def __init__(self, bot):
        pass

    @answercmd("^$")
    def empty(self, sender, args):
        pass

    @answercmd("list"):
    def list(self, sender, args):
        pass

    @answercmd("add (?P<list_name>\S+) (?P<desc>.*)"=
    def add(self, sender, args):
        liste = args.group("list_name")
        desc = args.group("desc")

    @answercmd("(remove|delete) (?P<ids>(\d+,?)+)")
    def remove(self, sender, args):
        ids = args.group("ids").split(",")

!todo add somelist a new todo to add

!todo remove 1,2,3

!todo

@anwsercmd("add (?P<list_name>\S+) (?P<desc>.*)")
@answercmd("search (?P<query>.*)")
@answercmd("(remove|delete) (?P<ids>(\d+,?)+)")
@answercmd("")

MultiSyncModule¶

A MultiSyncModule is similar to a SyncModule but it contains several commands which will be handled by the same module. You initialize it with a dictionary command_name → command_description. Then you will provide some handling method with the same syntax as you would in a SyncModule.

AsyncModule¶

An AsyncModule is a module executing a task automatically every n seconds and send a message in a room with the result of this task. Its action is not related to anything said in the room.

Example:

<bot> You have received a new mail !!!

Additionally to the name and the description of the module (see Description format) you have to provide a delay which means : every delay seconds the action will be executed. Then you write an action function with no argument :

def action(self):
    #some_work
    self.bot.say("The message we send to the room")

action is the method that will be called every delay seconds.

ListenModule¶

An ListenModule is a module executing a task which depend on something that has been said in the room. But as opposed to SyncModule it is not explicitly called with a !command syntax.

For instance, it can be used to analyse messages with URL :

<user> hey, check this amazing link : http://www.nojhan.net/geekscottes/strips/geekscottes_103.png
<bot> [Lien] Type: image/png, Taille : 68270 octets

The parameters required for a ListenModule are:

• its name
• a description (see Description format)

The answer handler function will have this signature:

def answer(self, sender, message):
    #some work on the message
    if (re.findall(SOME_URL_REGEXP, message)):
        #handle url
        return "[Lien] Type: %s, Taille : %s octets" % (ctype, clength))
    else:
        return None

Then if the message contains an URL you can extract it, work on it and return some information about it. If it does not, you return None so the bot will not say anything in the room.

PresenceModule¶

A PresenceModule is handling XMPP Presence stanza, for instance in a MUC : an user joins/leaves the room. The handling method is named do_answer with this signature:

def do_answer(self, message):
    # some work on the message
    if join_message:
        self.bot.say("Hello %s !" % username)

Which will result in:

*** user has joined
<bot> Hello user !!!

Help Module¶

User Monitoring Module¶

FortuneModule¶

This module is a SyncModule with some pre-defined functions. It can be used in this context : you have a website presenting some quote/fortunes and you want to write a module which, when called, will parse quotes from the website and return it. In addition to all SyncModule parameters, it has two more attributes you have to set : url_random and url_indexed. It provides commands with the syntax:

!cmd
!cmd some_number

In the first case, the module will use the url_random, and parse it. In the second case, the module will use the url_indexed, insert in it some_number, and get the corresponding page. All you need to do in your module is to override the extract_data, method using with your own, using the soup parameter which is a BeautifulSoup object created with the content of the page.

You can see some example of such FortuneModule in the bot (bashfr, vdm, chuck, …).

NotifyModule¶

This module is the combination of a SyncModule and an AsyncModule. You have to define a do_action method that will be called every n seconds. In a NotifyModule, the action method (see AsyncModule for more details) is already defined and will check if the module has been muted or not. If it has not, the method do_action that you are supposed to write will be called. The NotifyModule will provide a mute/unmute method that will disable/enable the notifications. You can add to it as many @answercmd as you need to, like in any other SyncModule.

The reminder module is an example of such module.

Write a ModuleTest class¶

Some tools are provided to you to write a unit test. First you can use the bot_answer method that will take a string defining what is the message that must be analysed by the bot, and retuning its answer. Then you can use unittest functionalities to check if the result is correct. Each test is a method that must be prefixed with test_ Here is a first simple example:

class BandMTest(ModuleTest):
    def test_current(self):
        """ !b&m : check current song """
        bot_rep = self.bot_answer("!b&m")
        self.assertRegexpMatches(bot_rep, "Titre en cours : (.*)")

    def test_lyrics(self):
        """ !b&m lyrics """
        self.bot_answer("!b&m lyrics")

This ModuleTest contains 2 unit test : the first is asking the bot !b&m and expects in return a result matching a regular expression. The second test is asking !b&m lyrics and has no test on the output : it will only fail an exception is raised.

You can also create more complicated example : for instance to test modules that need to access to database elements :

class TodoRemove(ModuleTest):
    def setUp(self):
        """ Creates 3 random todo we add manually to the database """
        self.todos = []
        todos = {string_gen(8): string_gen(50),
                 string_gen(8): string_gen(50),
                 string_gen(8): string_gen(50)}
        for list_name, todo in todos.iteritems():
            todo = Todo(list_name, todo, "sender", time.time())
            self.bot.session.add(todo)
            self.bot.session.commit()
            self.todos.append(todo)

    def test_todo_remove(self):
        """ !todo remove """
        bot_rep = self.bot_answer("!todo remove %s" % ",".join([str(elt.id) for elt in self.todos]))
        expected = "\n".join(["%s a été supprimé" % todo for todo in self.todos])
        self.assertEqual(bot_rep, expected)

    def tearDown(self):
        """ In case of failure, we manually remove the todo we added """
        for todo in self.todos:
            remove = self.bot.session.query(Todo).filter(Todo.id == todo.id).first()
            if remove is not None:
                self.bot.session.delete(remove)
                self.bot.session.commit()

In this class, we are only testing one command with the method test_todo_remove. The setUp and tearDown methods are defined in the python unittest API :

• setUp is executed before the actual test
• tearDown is executed after the test

In the test we want to try the deletion of todo, with the ”!todo remove id1,id2,id3” command. So in the setUp we manually create 3 todos with random values. Then in the test we try to remove them. The tearDown is usefull in case of the test fails : it manually removes todo added in the setUp, so we are sure that even if the test fails we will not have any generated todo remaining in the database.

Run your tests¶

To ask the bot to run the test you have just created, use the –unit-test option of pipobot, as described here: Unit-test mode.

New language¶

To translate Pipobot to a new language (for instance zz_ZZ, use the following commands (from the directory containing the setup.py script):

python setup.py extract_messages # Extract the messages from Pipobot’s sources
python setup.py init_catalog -l zz_ZZ # Create a translation catalog for the specified language

You can now edit pipobot/i18n/zz_ZZ/LC_MESSAGES/pipobot.po (with a standard text editor or POEdit, for instance) and translate every message. When done, run:

python setup.py compile_catalog # Compile the translation catalog

The translation can now be used by Pipobot.

Update an existing language¶

To update an existing translation catalog in order to take into account the changes in Pipobot’s source code, run the following commands (replace zz_ZZ with the name of the catalog you want to update):

python setup.py extract_messages # Extract the messages from Pipobot’s sources
python setup.py update_catalog -l zz_ZZ # Update the translation catalog for the specified language

You can now edit pipobot/i18n/zz_ZZ/LC_MESSAGES/pipobot.po (with a standard text editor or POEdit, for instance) and translate every message. When done, run:

python setup.py compile_catalog # Compile the translation catalog

The translation can now be used by Pipobot.