This is an IRC bot framework written in Python 3.

To use it, import the ircBot class from ircbotframe.py.

Example usage

First, create the bot object with the constructor:

bot = ircBot(<irc netwrok address>, <port>, <bot name>, <bot description>[, password=<server password>][, ssl=True][, ip_ver=<4 or 6>])

Next, bind functions to the various IRC message types. These functions will be called when the IRC bot receives messages with those message types. The function to be called should be of the form:

funcname(sender, header, message)

These can then be bound using:

bot.bind(<messsage type>, <funcname>)

Once functions have been bound, connect the irc bot to the server using:

bot.connect()

Then join a / some channel(s) using:

bot.joinchan(<channel name>)

where channel name begins with the # character. Finally, make the bot start listening to messages with:

bot.run()

Bot methods

ban(banMask, channel, reason)

Bans and kicks users satistfying the ban mask banMask from channel with a given reason (optional). Only works if the bot has operator privileges in channel.

bind(msgtype, callback)

This command binds a particular message type msgtype (passed as a string) to a given function. If the bot hears a message with this message type, the corresponding function will be called. The callback function MUST be of the form funcname(sender, headers, message) where sender is the nick of the entity that sent the message, headers is a list of any additional message headers before the message content and message is the actual message content. Bind can be used to listen for both server and user message types (bear in mind that server message types are usually numeric strings). Bind only allows a single function to be bound to each message type.

connect()

Makes the bot connect to the specified irc server.

debug(state)

Sets the bot's debug state to state which is a boolean value.

disconnect(qMessage)

Makes the bot disconnect from the irc server with the quit message qMessage (for no quit message, put an empty string)

identify(nick, callbackApproved, approvedParameters, callbackDenied, deniedParameters)

where callbackApproved and callbackDenied are of the form funcname(parameter 1, parameter 2, ...). Used for checking whether or not a user with the nickname nick is who they say they are by checking their WHOIS info from the server. If they are verified, the function callbackApproved will be called with the parameters approvedParameters (which will fill parameter 1, parameter 2, etc. in order). If they cannot be verified or are not registered, then callbackDenied is called with deniedParameters. Parameter lists approvedParameters and deniedParameters are tuples with the tuple items matching the callbackApproved and callbackDenied function parameters in order from the second parameter. For example, identify(nick, approved, (string, integer1), denied, (integer2)). If the nick is verified the following function will be called: approved(string, integer1). Otherwise the other function will be called: denied(integer2)

joinchan(channel)

Makes the bot join a given channel. channel must start with a # character.

kick(nick, channel, reason)

If the bot has operator privileges in the channel channel, the user with nick will be kicked from it with the given reason .

reconnect()

Disconnects from the server then reconnects. It disconnects with the quit message "Reconnecting".

run()

Tells the bot to start listening to the messages it receives and to act upon the input using functions connected to the bindings using the command bind(). The bot starts listening on a new thread and so is not a blocking call. Any bot functions you wish to call must be called by functions connected to bindings (using the command bind()).

say(recipient, message)

The bot says the given message message to the recipient recipient. The recipient can be a channel (and should start with a # character if this is the case).

send(string)

Sends a raw IRC message given by string to the server. Can have dire consequences if your message is not formatted correctly. It is advised that you consult the IRC specification in RFC 1459.

stop()

Stops the IRC bot from running. You should disconnect from the server first. The bot's thread will terminate naturally. Should you wish to use the bot's thread join() function, stop() should be called first.

topic(channel, message)

The bot sets the topic in channel to message, if it has sufficient privileges.

unban(banMask, channel)

Unbans previously banned users satistfying the ban mask banMask from channel. Only works if the bot has operator privileges in channel.