Package: hippybot
IntroductionHippyBot is a Hipchat.com chatroom bot written in Python. It is technically just a Jabber/XMPP bot, but it has customised features for connecting to and working on Hipchat.HippyBot includes a simple plugin API for adding commands.InstallationThere a few ways you can install Hippybot:Download and install withsetup.py:python setup.py installInstall from PyPi:pip install hippybot
# or using setuptools
easy_install hippybotConfigurationThere is an example configuration file distributed with HippyBot calledhippybot.conf.example, copy this and edit it. You will need to add an account to your Hipchat group for the bot to connect as. While logged in as the account go to theXMPPsettings page to get the details you’ll need to edit the config file.UsageRun HippyBot from a terminal like so:hippybot -c path/to/your/config/file.confTo run as a background daemon use-dor-daemon:hippybot -c path/to/your/config/file.conf -dOptionally you can provide a path to a PID file to use with-por--pid.Note: at present you will have to provide your own control script, e.g. for use withinit.dorupstart.You should see the bot join any channels listed in the config file. You can then target the bot with commands using the at-sign notation, e.g.:@botname rot13 hello worldIf you have therot13example plugin set to load (via the plugins section of the config file) then the bot will reply to you using at-sign notation with a ROT13’d (each character offset by 13) version of the text “hello world”.The bot has 2 inbuilt commands:load_plugins: this will reload any updated plugins (note it will also reset the internal state of any loaded plugins, e.g. the counter in themexican waveplugin). Note itdoes notreload the bot’s configuration file and so will not load new plugins.reload: this will reload the bot itself, reloading the configuration file, reconnecting to HipChat and reloading any plugins, in the process. Note: it does not end the main process, you would have to do that yourself from the terminal (for example if HippyBot were updated).PluginsThere are 3 plugins currently distributed with HippyBot:rot13: this is mostly included as an example, it ROT13s, any text spoken directly to the bot, back at the speaker.mexican_wave: this is a fun plugin that completes a mexican wave if 2 people in a row say\o/in a channel, e.g.:John Smith: \o/
Joe Bloggs: \o/
Hippy Bot:  \o/udefine: look up a term onUrban Dictionary, the first 3 definitions will be posted back to the channel.Warning: many terms are NSFW.To instruct the bot to load a plugin include the plugin’s module path in the load field of the plugins section of the config file, e.g. to load themexican_waveplugin which is located in the filemexican_wave.pyinhippybot/plugins/, you would write it as:[plugins]
load = hippybot.plugins.mexican_waveTo load a plugin namedmy_custom_pluginthat you have installed into your python path undermyhippybotpluginsin a filename (or module) namedmy_custom_plugin.pyyou would append (on a new line, notice the indentation):[plugins]
load = hippybot.plugins.mexican_wave
       myhippybotplugins.my_custom_pluginTo search for plugins in paths outside of hippybot, you can use theload_pathoption:[plugins]

load_path = /absolute/path/plugins
    hippybot/plugins
    plugins
    another/relative/pathPlugin APIHippyBot includes a very simple plugin API. To add commands to HippyBot you just need an importable Python package (e.g. a directory in thePYTHON_PATHthat includes a file named__init__.py), and place your plugin in it’s own Python file (the ROT13 plugin lives inrot13.py).You then can include a function that matches the same name as the file and is the same command you want to register, and use either thebotcmdordirectcmddecorators:# hello_world.py
from hippybot.decorators import directcmd

@directcmd
def hello_world(bot, mess, args):
    return u'Hello world!'This registers the commandhello worldas a direct command, that means the text “Hello world!” will be directly spoken back to the user using at-sign notation. Thebotcmddecorator on the other hand will respond in the channel without targetting the original speaker.
By default these function based plugins only support direct commands (spoken to the bot using at-sign notation), however you can create more complex plugins with greater control using class based plugins.To create class based plugins create the Python module as normal, with any descriptive name you want, and include a class namedPluginin the module, for example the hello world plugin can be written like:# hello_world.py
from hippybot.decorators import botcmd, directcmd

class Plugin(object):
    global_commands = ['hello_world']
    command_aliases = {'hi!': 'hello'}

    @botcmd
    def hello_world(self, mess, args):
        return u'Hello world!'

    @directcmd
    def hello(self, mess, args):
        return u'Well hello there..'This uses 2 special properties:global_commands: a list of commandmethod namesthat can be triggered without targetting the bot using at-sign notation (just say the command in the channel without mentioning the bot).command_aliases: dict of command aliases and the methods they map to, this is a way of triggering a command from a string that can’t be used as a Python method name (e.g. using special symbols such as the “o/” trigger used in themexican waveplugin).all_msg_handlers: a list of handlermethod namesthat will be passed all incoming XMPP message objects regardless of type as. This can be used for low-level hanbdling of Jabber messages without using the higher level message handling of jabberbot or hippybot.HipChat APIHippyBot includes a very simple object orientated wrapper for theHipChat API. To make use of the API you need tocreate an API keyand enter that into the config file under the sectionhipchat, as an option calledapi_auth_token, e.g.:[hipchat]
api_auth_token = xxxxxxxxxxxxxxxxxxxxxxxxIf you are using self-hosted Hipchat service, set up something like this:[hipchat]
api_server = api.example.com
api_auth_token = xxxxxxxxxxxxxxxxxxxxxxxxThen you can access the wrapper via theapiattribute on the bot instance, e.g. from within a command method on a plugin class:# hello_world.py
from hippybot.decorators import botcmd

class Plugin(object):
    global_commands = ['hello']

    @botcmd
    def hello(self, mess, args):
        channel = unicode(mess.getFrom()).split('/')[0]
        # Say hello world as a room notification
        # Params to the API wrapper are sent as dicts
        self.bot.api.rooms.message({
            'room_id': channel,
            'from': self.bot._config['connection']['nickname'],
            'message': 'Hello world!'
        })