This package contains a framework for an easily set-up, multi-purpose IRC bot. The intent with this package is not that it be included with other packages, but rather be run as a standalone program. However, it is intended (and encouraged) that users write new “modules” for it. This documentation is intended to serve that goal.
Due to the high level of customization encouraged by this bot, there are a few different versions of it floating around. For this documentation, we will cover three: the original “phenny” by Sean B. Palmer the “jenni” fork by Michael Yanovich, and the “Willie” fork by Edward Powell et al. While all recieve periodic updates, the above lists them in a generally ascending order of recentness.
For clarity’s sake, this documentation will refer to these forks as different “API levels” or “API versions”. The version numbers will approach the square root of 2 (1.41421...), the mathematical constant e (2.71828...), and pi (3.14159...) respectively. When a fork adds a new feature, and this guide documents it, the current API level of that fork will be given one more decimal.
At its most basic, writing a Willie module involves creating a Python file with some number of functions in it. Each of these functions will be passed a “Willie” object (“Phenny” in 1.x) and a “Trigger” object (CommandInput in 1.x and 2.x). By convention, these are named phenny and input in 1.x, jenni and input in 2.x, and willie and trigger in 3.x. For the purposes of this guide, the 3.x names will be used.
A Willie module contains one or more callables. It may optionally contain a configure or setup function. callables are given a number of attributes, which determine when they will be executed. Syntactically, this is done at the same indentation level as the function’s def line, following the last line of the function.
This is the general function format, called by Willie when a command is used, a rule is matched, or an event is seen, as determined by the attributes of the function. The details of what this function does are entirely up to the module writer - the only hard requirement from the bot is that it be callable with a Willie object and a Trigger object , as noted above. Usually, methods of the Willie object will be used in reply to the trigger, but this isn’t a requirement.
Note that the name can, and should, be anything - it doesn’t need to be called callable.
A list of commands which will trigger the function. If the Willie instance is in a channel, or sent a PRIVMSG, where one of these strings is said, preceeded only by the configured prefix (a period, by default), the function will execute.
A regular expression which will trigger the function. If the Willie instance is in a channel, or sent a PRIVMSG, where a string matching this expression is said, the function will execute. Note that captured groups here will be retrievable through the Trigger object later.
Inside the regular expression, some special directives can be used. $nick will be replaced with the nick of the bot and , or :, and $nickname will be replaced with the nick of the bot.
Prior to 3.1, rules could also be made one of three formats of tuple. The values would be joined together to form a singular regular expression. However, these kinds of rules add no functionality over simple regular expressions, and are considered deprecated in 3.1.
This is one of a number of events, such as 'JOIN', 'PART', 'QUIT', etc. (More details can be found in RFC 1459.) When the Willie bot is sent one of these events, the function will execute. Note that functions with an event must also be given a rule to match (though it may be '.*', which will always match) or they will not be triggered.
Availability: 2+
This limits the frequency with which a single user may use the function. If a function is given a rate of 20, a single user may only use that function once every 20 seconds. This limit applies to each user individually. Users on the admin list in Willie’s configuration are exempted from rate limits.
Priority can be one of high, medium, low. It allows you to control the order of callable execution, if your module needs it. Defaults to medium
This is an optional function of a module, which will be called while the module is being loaded. Note that this normally occurs prior to connection to the server, so the behavior of the Willie object’s messaging functions is undefined. The purpose of this function is to perform whatever actions are needed to allow a module to function properly (e.g, ensuring that the appropriate configuration variables are set and exist).
The bot will not continue loading modules or connecting during the execution of this function. As such, an infinite loop (such as an unthreaded polling loop) will cause the bot to hang.
Availability: 3+
This is an optional function of a module, which will be called during the user’s setup of the bot. It’s intended purpose is to use the methods of the passed Config object in order to create the configuration variables it needs to function properly.
In 3.1+, the docstring of this function can be used to document the configuration variables that the module uses. This is not currently used by the bot itself; it is merely convention.
The channel (or nick, in a private message) from which the message was sent.
The nick of the person who sent the message.
The event which triggered the message.
The line which triggered the message.
The regular expression MatchObject for the triggering line.
The arguments given to a command.
True if the nick which triggered the command is in Willie’s admin list as defined in the config file.
True if the nick which triggered the command is the owner stated in the config file.
The host which sent the triggering message.
Availability: 3+
True if the nick which triggered the command is an op on the channel it was triggered in. Will always be False if the command was triggered by a private message
The willie object has, among others, the attributes db and config. These can be used for a number of functions and features.