Creating custom handlers

Note

Internally, all processed data are unicode strings. If you need to decode strings, you can use the provided fatbotslim.irc.u() function.

Basic handlers

Basic handlers simply react to IRC events by calling methods mapped to them, they are subclasses of fatbotslim.handlers.BaseHandler.

Events are mapped to methods names in the handler’s commands attribute, which is a dict where the key is an IRC event as defined in the fatbotslim.irc.codes module and the value is the name of the method to call. The mapped methods take just one attribute, the fatbotslim.irc.bot.Message object which triggered the event. To communicate back to the server, use the handler’s irc (which is a fatbotslim.bot.IRC instance).

A good example of a custom handler is FatBotSlim’s integrated fatbotslim.handlers.CTCPHandler:

class CTCPHandler(BaseHandler):
    """
    Reacts to CTCP events (VERSION,SOURCE,TIME,PING). (enabled by default)
    """
    commands = {
        CTCP_VERSION: 'version',
        CTCP_SOURCE: 'source',
        CTCP_TIME: 'time',
        CTCP_PING: 'ping'
    }

    def version(self, msg):
        self.irc.ctcp_reply(
            u'VERSION', msg.src.name,
            u'{0}:{1}:{2}'.format(NAME, VERSION, platform.system())
        )

    def source(self, msg):
        self.irc.ctcp_reply(
            u'SOURCE', msg.src.name,
            u'https://github.com/mattoufoutu/fatbotslim'
        )
        self.irc.ctcp_reply(u'SOURCE', msg.src.name)

    def time(self, msg):
        now = datetime.now().strftime(u'%a %b %d %I:%M:%S%p %Y %Z').strip()
        self.irc.ctcp_reply(u'TIME', msg.src.name, now)

    def ping(self, msg):
        self.irc.ctcp_reply(u'PING', msg.src.name, u' '.join(msg.args))

Another, simpler, basic handler is the integrated fatbotslim.handlers.PingHandler, this one simply answers to server’s PINGs:

class PingHandler(BaseHandler):
    """
    Answers to PINGs sent by the server. (enabled by default)
    """
    commands = {
        PING: 'ping'
    }

    def ping(self, msg):
        self.irc.cmd(u'PONG', u' '.join(msg.args))

Command handlers

The fatbotslim.handlers.CommandHandler is a special kind of handler that reacts only to PRIVMSG and NOTICE messages, they are used to implement !foo-like commands to your bot.

The prefix character is defined by the handler’s trigger_char attribute, and defaults to !.

Commands are defined in the handler’s triggers attribute, a dict that maps method names to events they should react to. Possible events are EVT_PUBLIC, EVT_PRIVATE, and EVT_NOTICE. The methods take just 1 argument, the first is a fatbotslim.irc.bot.Message object, and the second is a fatbotslim.irc.bot.IRC object used to send messages back to the server.

For example, the message !foo bar would call the handler’s foo() method.

Here is a command handler that says hello when it receives !hello in public:

from fatbotslim.handlers import CommandHandler, EVT_PUBLIC

class HelloCommand(CommandHandler):
    triggers = {
        u'hello': [EVT_PUBLIC],
    }

    def hello(self, msg):
        self.irc.msg(msg.dst, u"Hello, {0}!".format(msg.src.name))

If you wanted the handler to answer also to private messages, you would simply have to add ‘private’ to the “hello” event list and set the answer destination accordingly:

from fatbotslim.handlers import CommandHandler, EVT_PUBLIC, EVT_PRIVATE

class HelloCommand(CommandHandler):
    triggers = {
        u'hello': [EVT_PUBLIC, EVT_PRIVATE],
    }

    def hello(self, msg):
        dst = msg.src.name if (msg.dst == irc.nick) else msg.dst
        self.irc.msg(dst, u"Hello {0}!".format(msg.src.name))