Get your IRC bot off the ground with Flyrc!

Flyrc is a modular library for IRC (Internet Relay Chat) using gevent. Flyrc uses 'handler' objects to dispatch server messages. The client is completely extensible, with a focus on supporting modern IRC features.

from flyrc import client, util, handler

cli = client.SimpleClient('Flyrcbot', 'flyrc', 'Flyrc demo bot', 'irc.esper.net', 6697, ssl=True)
cli.add_handler(handler.AutoJoin('#flyrctest'))
cli.add_handler(handler.BasicChannelCommand(prefix='!'))
cli.add_handler(handler.QuitWhenAsked())
util.run_client(cli)

Flyrcbot has joined #flyrctest
<mr_flea> !quit
Flyrcbot has quit [Quit: Requested by mr_flea.]

Handlers react to messages from the IRC server and other handlers. Handlers are written as Python classes, containing functions that will be executed in response to events. To prevent namespace conflicts, all handler function names start with 'irc_'. A handler is loaded by calling Client.add_handler with an instance of the handler.

from flyrc import message

class AutoJoin(object):
	def __init__(self, *args):
		self.channels = args

	def irc_RPL_WELCOME(self, client, msg):
		for channel in self.channels:
			client.send(message.join(channel))

Handlers for IRC numerics can either be named by number or by the numeric's name. (e.g. irc_RPL_WELCOME vs. irc_001)

Since handlers can trigger events, they can also define dependencies on other handlers:

from flyrc import message, handler

class QuitWhenAsked(object):
	DEPENDENCIES = [handler.BasicCommand]

	def irc_command_quit(self, client, source, target, args):
		client.send(message.quit("Requested by %s." % source.nick))

The client is the core of Flyrc. The client takes care of establishing the connection to the server, dispatching events, and rate-limiting message sending. The client is also (presently) the only part of Flyrc that uses gevent, so it can be replaced with a another compatible client to remove the dependency upon gevent.

By default, the client handles no messages. As it would be tedious to add a bunch of handlers each time a Flyrc bot is written, a SimpleClient convenience class that includes many common handlers by default is offered. These include:

• Ping, for sending the PONG reply to PING messages
• User, for sending the USER and NICK messages upon connection to the IRC server
• NickInUse, for automatically changing the nick if it's already in use
• MessageProcessor, for generating channel_message, channel_action, etc. events from NOTICE and PRIVMSG
• One of either AutoReconnect or GenericDisconnect handlers, for gracefully quitting
• BasicCTCP, for supporting CTCP PING, VERSION, and CLIENTINFO queries

TODO: document client options (host, port, ssl, throttle_delay, throttle_burst, enforce_order, timeout)

All exceptions raised by the client itself inherit from flyrc.client.ClientError. As of now, all of the exceptions deal with dependency tree violations. These include:

• DuplicateHandlerObject, raised when attempting to load an identical instance of a handler
• MissingHandlerObject, raised when attempting to remove a handler that isn't loaded
• UnsatisfiedDependency, raised when attempting to load a handler without loading its dependencies first
• LingeringDependency, raised when attempting to unload a handler without first unloading everything that depends upon it
• InvalidDependencyTree, raised when an invalid dependency tree is encountered while unloading a handler (either a refcount lower than 0 or a missing dependency); InvalidDependencyTree exceptions should only occur if previous exceptions have been ignored

Exceptions from the underlying TCP socket are propagated to handlers as client_error events (more about this below).

Events can be generated by the client or by other handlers, and can have an arbitrary number of arguments and keyword arguments. The first argument is always present and always the client instance from which the event originates. Each handler instance can only bind to each event once.

The client automatically generates events for all IRC messages. The name of the event will be either the numeric or command (whichever is applicable) from the server (e.g. 001 or PRIVMSG). Names of events generated in this manner will always be uppercase. As mentioned above, a numeric can be addressed by either name or number; this is internally accomplished by rewriting names of numerics as the number they represent when the handler is added. All IRC message events generated by the core have a single argument: an instance of the Message class representing the message that was received.

The client also generates several special events about client operation. The names of all of these events are prefixed with "client_". These events include (arguments in brackets):

• client_connected[] - fires when the TCP connection to the server is established
• client_disconnected[] - fires when the TCP connection to the server is closed
• client_error[e] - fires when a socket error is intercepted; the first argument is the socket exception that was caught
• client_global_send[msg] - fires when any message is sent to the server; the first argument is the Message object
• client_global_recv[msg] - fires when any message is received from the server; the first argument is the Message object
• client_load[] - fires when the client loads a handler (special: will only be called on the handler that has just been loaded)
• client_unload[] - fires when the client unloads a handler (special: will only be called on the handler that has just been unloaded)

Flyrc ships with some default handlers, which will (TODO) eventually be documented here.

• Ping - respond to server PING messages
• AutoJoin - automatically join channels
• NickInUse - change to alternate nicks if the attempted nick is already in use
• SASL - support SASL services authentication (note: this will likely be written into more of a SASL framework)
• User - send the NICK and USER messages upon connection to register with the IRC server
• LogToConsole - log all messages and connection/disconnection/socket error events to console
• GenericDisconnect - gracefully handle the server closing our socket
• Oper - automatically oper upon connection, and disable ratelimiting once opered
• MessageProcessor - split privmsg/notice events into many smaller, easier-to-deal-with events
• BasicCTCP - handle CTCP PING, VERSION, and CLIENTINFO requests
• BasicChannelCommand - generate command_ events from channel messages, with a configurable prefix; implements BasicCommand
• BasicPrivateCommand - generate command_ events from private messages; implements BasicCommand
• QuitWhenAsked - quit upon receiving the "quit" command
• LogCommands - log all commands to console
• InfoTracker - (still under development) save all whois, who, etc. information into structures accessible from other handlers; provide events to notify other handlers when (new) data is available

Copyright (C) 2012 Keith Buck

Flyrc is licensed under the MIT license.