xbotlib

XMPP bots for humans

status: experimental

A friendly lightweight wrapper around slixmpp for writing XMPP bots in Python. The goal is to make writing and running XMPP bots easy and fun. xbotlib is a single file implementation which can easily be understood and extended. It provides a small API surface which reflects the slixmpp way of doing things.

Install

$ pip install xbotlib

Example

Put the following in a echo.py file.

xbotlib provides a number of example bots which you can use to get moving fast and try things out.

from xbotlib import EchoBot

EchotBot()

And then python echo.py. You will be asked a few questions in order to load the account details that your bot will be using. This will generate a echobot.conf file in the same working directory for further use. See the configuration section for more.

Here's the code for the EchoBot.

class EchoBot(Bot):
    def direct(self, message):
        self.reply(message.body, to=message.sender)

    def group(self, message):
        if "echobot" in message.body:
            self.reply(message.body.split(":")[-1], room=message.room)

Read more in the API reference for how to write your own bots.

All examples

• EchoBot: Sends back what you sent it
• WhisperBot: Anonymous whispering in group chats

See xbotlib.py for all example bots.

API Reference

When writing your own bot, you always sub-class the Bot class provided from xbotlib. Then if you want to respond to a direct message, you write a direct function. If you want to respond to a group chat message, you write a group function.

Bot.direct(message)

Respond to direct messages.

Arguments:

• message: received message (see SimpleMessage below for available attributes)

Bot.group(message)

Respond to a message in a group chat.

Arguments:

• message: received message (see SimpleMessage below for available attributes)

SimpleMessage

A simple message interface.

Attributes:

• body: the body of the message
• sender: the user the message came from
• room: the room the message came from
• receiver: the receiver of the message
• nickname: the nickname of the sender
• type: the type of message (chat or groupchat)

Documenting your bot

Add a help = "my help" to your Bot class like so.

class MyBot(Bot):
    help = "My help"

See more in the commands section on how to use this.

Commands

Using !<command> in direct messages and <nick>:!<command> in group chats, here are the supported commands.

• !uptime: how long the bot has been running
• !help: the end-user provided help text of what the bot does

Avatars

By default, xbotlib will look for an avatar.png (so far tested with .png but other file types may work) file alongside your Python script which contains your bot implementation. You can also specify another path using the --avatar option on the command-line interface. The images should ideally have a height of 64 and a width of 64 pixels each.

Configure your bot

All the ways you can pass configuration details to your bot.

Using the .conf configuration file

If you run simply run your Python script which contains the bot then xbotlib will generate a configuration for you by asking a few questions. This is the simplest way to run your bot locally.

Using the command-line interface

Every bot accepts a number of comand-line arguments to load configuration. You can use the --help option to see what is available (e.g. python bot.py --help).

Using the environment

xbotlib will try to read the following configuration values from the environment if it cannot read them from a configuration file or the command-line interface. This can be useful when doing remote server deployments.

• XBOT_ACCOUNT: The bot account
• XBOT_PASSWORD: The bot password
• XBOT_NICK: The bot nickname

Roadmap

See the issue tracker.

Changes

See the CHANGELOG.md.

License

See the LICENSE.