Hack 38 Extend the Python IRCLib

Hack 38 Extend the Python IRCLib

Not every program needs the same features from an IRC library. Extend IRCLib for your specific purposes .

This hack shows you how to write an extension for IRCLib [Hack #37] . Extensions are simply Python scripts that add events and/or methods to the IRCLib classes. This allows you to have a modular, incremental approach to creating bots, adding one feature at a time.

Let's take a look at an example.

5.9.1 The Code

Save this as helloworld.py anywhere in your Python path :

 import irc dependencies=[] IRC_Object=None def send_hi(self, channel):     self.send_string("PRIVMSG %s :Hello World!" % channel)  def handle_parsed(prefix, command, params):     if command=="PRIVMSG":         if params[1]=='hi':             IRC_Instance.active.events['hi'].call_listeners(params[0])          def initialize( ):     irc.IRC_Connection.send_hi=send_hi def initialize_connection(connection):     connection.add_event("hi")     connection.events['parsed'].add_listener(handle_parsed) 

The first line is the import irc needed to get access to the IRCLib classes.

The first variable defined in this extension script is dependencies . If your extension depends on other extensions to work, you can put the names of the extensions in this list. IRCLib will then load these extensions first before loading yours. IRC_Instance is a reference to the IRC_Object instance in the program that is loading your extension.

The script then continues to define four functions:

send_hi

This function will get added to the IRC_Connection class. It sends the string "Hello World!" to the channel specified by channel .

handle_parsed

This is an event handler for the ' parsed ' event. It's used to get the parsed lines from IRCLib. If the line matches with "hi," all listeners for the ' hi ' event are called. The destination of the message (was it said in a channel or private message?) is given to the event handlers as the first argument. Note that it's using IRC_Instance.active to get the connection that triggered the event. This variable exists so you don't have to pass IRC_Connection references to each event handler.

initialize

This function is called immediately after the script is loaded. This sets the send_hi function as a method for the class IRC_Connection .

initialize_connection

This function is called each time a new connection is created, with the IRC_Connection instance as its only argument. The first line of the function adds a ' hi ' event to each connection. The second line connects ' handle_parsed ' to the ' parsed ' event for each connection.

5.9.2 Loading Your Extensions

Now that you have an extension, let's use it in an IRCLib program:

 import irc def handle_hi(destination):     MyConn.send_hi(destination) MyIRC=irc.IRC_Object( )  MyIRC.load_extension("helloworld")  MyConn=MyIRC.new_connection( ) MyConn.nick="MauBot" MyConn.ident="maubot" MyConn.server=("irc.oftc.net", 6667) MyConn.realname="Hoi" MyConn.events['hi'].add_listener(handle_hi) while 1:     MyIRC.main_loop( ) 

This example doesn't contain much new code, except for the MyIRC.load_extension("helloworld") line. As you've probably guessed, this call loads the ' helloworld ' extension. Later on in the script, you add an event handler for the type ' hi ' (added by the extension script). This causes the ' handle_hi ' method to be called whenever the ' hi ' event happens. This event handler uses the ' send_hi ' method (also added by the extension) to send back a response.

5.9.3 Built-in Extensions

IRCLib comes with a number of built-in extensions. To see a complete list of the extensions you can load, consult the IRCLib web site at http://irclib.bitlbee.org. There are also a number of advanced features, such as event handler priorities and the blocking of events.

Maurits Dijkstra