Event List

KitnIRC uses an event system to run code when certain things occur. These events specific to KitnIRC but often linked to corresponding IRC events. There are two types of events that KitnIRC uses: high-level logical events, and low-level network events.

Logical events

These events are the bread and butter of KitnIRC. They represent the kinds of things to which a typical IRC-using application might want to respond.

Connection-related events

WELCOME

This event fires when KitnIRC has successfully connected to the IRC server and is considered "on the network" - specifically, it's triggered by the RPL_WELCOME response from the server.

Arguments: hostmask (your hostmask as perceived by the IRC network).

Informational events

MOTD

This event fires when the entire text of the server's Message of the Day has been received. Servers often send their MOTDs automatically upon connection, and also in response to an MOTD command.

Arguments: motd (the full text of the MOTD as a single string).

User/Channel-related events

TOPIC

This event fires when the topic of a channel is changed.

Arguments: actor (a User indicated who set the topic), channel (a Channel), topic (the topic, as a string).

MODE

This event fires when a mode change occurs (both channel and user modes). For channel modes (including modes that involve a user, e.g. +o), target will be a Chanel object. For user modes, target will be a User.

Arguments:

• actor, a string specifying who or what set the mode.
• target, either a User or Channel indicating where the mode was set.
• op, either '+' or '-' depending on whether the mode was added or removed.
• mode, the letter of the mode that was set.
• argument, either None for modes which don't take an argument, or the string argument.

MEMBERS

This event fires whenever the member list of a channel changes (regardless of the cause - joins, parts, quits, and kicks all trigger this in addition to the more specific event). MEMBERS always fires after more specific events.

Arguments: channel (the channel for which the member list changed, as a Channel object).

JOIN

This even fires whenever a user joins a channel.

Arguments: actor (the User who joined), channel (the Channel that was joined).

PART

This even fires whenever a user parts a channel.

Arguments: actor (the User who parted), channel (the Channel they left), message (the parting message as a string, or an empty string if none).

KICK

This event fires when a user is kicked from a channel.

Arguments:

• actor, the User who did the kicking.
• target, the User who was kicked.
• channel, the Channel from which the target was kicked.
• message, the kick message as a string (or an empty string if none).

QUIT

This event fires when a user disconnects from the network.

Arguments: actor (the User who disconnected), message (the quit message as a string, or an empty string if none).

Network events

These events are mostly used internally by KitnIRC, but you can also hook into them if you have a specific need. In most cases, however, you shouldn't need to worry about them.

Connection-related events

PASSWORD

This event fires when it's time for KitnIRC to potentially supply a password to the IRC server as part of its connection process (the IRC PASS command). It allows modules to supply this password (e.g. from a configuration file) rather than having it passed in as part of the .connect() call. If any PASSWORD handler returns a boolean true value, KitnIRC will assume a PASS command has been issued by the handler and will not send another. (Example usage: kitnirc.contrib.foonetic.)

Arguments: none.

CONNECTED

This event fires when a socket connection is successfully opened to the IRC server, but before any actual IRC protocol traffic is sent. By default, this triggers sending the NICK and USER IRC messages being sent to the server. In most cases where you think you want to use this event, you probably actually want the logical event WELCOME instead.

Arguments: none.

Traffic-related events

LINE

This event fires every time a complete line of IRC protocol traffic is received, no matter what kind of traffic it is. You typically don't want to handle this, as this traffic will get routed through KitnIRC's own parsers and get split up into different logical events based on its type.

Arguments: line (the content of the line).

RAWLINE

This event fires any time a complete line of IRC protocol traffic is received and KitnIRC doesn't have any defined way to handle it (for instance, if the IRC server implements a superset of the standard IRC features, the extra functionality probably won't be handled by KitnIRC). You can listen for this event to write your own handlers for these responses, up to and including dispatching your own events.

Arguments: line (the content of the line).