Plugin Writing

There are two types of pyaib plugins, class based or just functions. They both use the same decorators but the class based plugins get a irc_context and config passed to their constructor.

Pyaib objects

Context Object

Every method called by pyaib will receive an irc context object. The context is a dictionary subclass (pyaib.util.data.Object)

The context contains information about the running bot and has methods for interacting with IRC. The following methods are present in the context object, they are all UPPERCASE. In the future these might move to a sub dictionary called 'cmd'

• context.RAW(string) send raw strings to the irc server
• context.NICK(string) Set the bot nickname
• context.PRIVMSG(target, message) Send message to target via PRIVMSG. Messages longer than 510 characters will be split into multiple messages
• context.JOIN(channels) Join a single channel or a sequence of channels. Will split long sequences of channels into multiple JOINs of a max of 510 characters long.
• context.PART(channels, message=None) Leave a channel and provide an optional message. Channels can be a list remember context.JOIN('0') is the fastest way to leave all your channels.

The context has the following bits of information

• context.botnick is the bot's current nickname
• context.botsender is the bot's Sender Object
• context.server is the current IRC Server Sender Object
• context.config the global bot config

The following components are available via the context

• context.channels (Good for checking membership in a channel) '#channel' in context.channels
• context.events (Fire events or register new ones)
• context.timers (Periodic events)
• context.triggers (keyword triggers)
• context.db (DB component access, if configured)

Plugin Hooks (Decorators)

from pyaib.plugins import observe, keyword, every, plugin_class There are various aliases for each of these.

@plugin_class

This decorator designates a class as a plugin and it will be initialized when the module is loaded. The decorator can take an optional string argument that tells pyaib to save the instance of the plugin in the irc_context object with the given name.

All plugin classes must have an init method that takes two arguments the first is the irc context the second is a config object.

@observe(event, [event]*)

This decorator designates a method or function to be a handler for an 'event'. Multiple handlers can exist for a single event

Event handlers take 2 arguments: irc context object, Message Object

Common Events

@keyword('word', ['word']*)

This decorator designates this method or function as a command word trigger handler. 'triggers.prefix' (default: '!') can be set in the config file as a single character that these words must be prefixed by so the bot knows to react to them.

You can also address the bot: 'botnick: word' would be the same as '!word'

Keyword Handlers take 5 arguments: irc context, Message Object, trigger word, args, keyword args)

The trigger word is useful if the same method listens to multiple words and you want to know which one.

args will be all positional arguments after the command word.

keyword args will be any arguments after the command word that prefixed with -- ex: '--help' or '--value=4'

If you don't like working with args or keywords you can always parse the message from the Message Object

@every(seconds, optional name)

This method will be called every 'seconds' and will be passed two arguments: irc context, timer name.

More complex timers are supported, but required working directly with the timers api in the context object. Timers can be fired at an exact time in the future, repeats a set number of times, etc.