Core IRC client

The Omnipresence IRC utility bot.

class omnipresence.IRCClient(factory)

Omnipresence’s core IRC client protocol class. Common parameters for callbacks and class methods include:

prefix

A full nick!user@host mask.

channel or nick

An IRC channel, for commands directed at an entire channel; or specific nickname, for commands directed at a single user. Despite their names, parameters with either name will usually take both channels and nicks as values. To distinguish between the two in a callback, use the Twisted constant CHANNEL_PREFIXES:

from twisted.words.protocols import irc

class Handler(object):
    # ...
    def callback(self, prefix, channel):
        if channel[0] in irc.CHANNEL_PREFIXES:
            # addressed to a channel
        else:
            # addressed to the bot specifically

action(prefix, channel, data)

Called when a /me action is performed in the given channel.

channel_names = None

A mapping of channels to the set of nicks present in each channel.

connectionLost(reason)

Called when the connection to the IRC server has been lost or disconnected.

connectionMade()

Called when a connection has been successfully made to the IRC server.

factory = None

The IRCClientFactory that created this client.

heartbeatInterval = 60

The number of seconds to wait between sending successive PINGs to the server. This overrides a class variable in Twisted’s implementation, hence the unusual capitalization.

irc_ERR_NICKNAMEINUSE(prefix, params)

Called when the bot attempts to use a nickname that is already taken by another user.

join(channel)

Join the given channel. If joins have been suspended with suspend_joins(), add the channel to the join queue and actually join it when resume_joins() is called.

joined(prefix, channel)

Called when the bot successfully joins the given channel. Use this to perform channel-specific initialization.

kick(channel, nick, reason=None)

Kick the the given nick from the given channel.

kickedFrom(channel, kicker, message)

Called when the bot is kicked from the given channel.

last_pong = None

The time of the last PONG seen from the server.

leave(channel, reason=None)

Leave the given channel.

left(prefix, channel)

Called when the bot leaves the given channel.

max_lag = 150

The maximum acceptable lag, in seconds. If this amount of time elapses following a PING from the client with no PONG response from the server, the connection has timed out. (The timeout check only occurs at every heartbeatInterval, so actual disconnection intervals may vary by up to one heartbeat.)

me(channel, action)

Perform an action in the given channel.

message_buffers = None

A mapping of channels to a mapping containing message buffers for each channel, keyed by nick.

mode(chan, set, modes, limit=None, user=None, mask=None)

Change the mode of the given channel. See the Twisted documentation for information on this method’s parameters.

modeChanged(prefix, channel, set, modes, args)

Called when a channel’s mode is changed. See the Twisted documentation for information on this method’s parameters.

msg(nick, message)

Send a message to the nickname or channel specified by nick.

myInfo(servername, version, umodes, cmodes)

Called with information about the IRC server at logon.

names(*channels)

Ask the IRC server for a list of nicknames in the given channels. Plugins generally should not need to call this method, as it is automatically invoked on join.

nickChanged(nick)

Called when the bot’s nickname is changed.

notice(nick, message)

Send a notice to the nickname or channel specified by nick.

noticed(prefix, channel, message)

Called when we receive a notice from another user. Behaves largely the same as privmsg().

privmsg(prefix, channel, message)

Called when we receive a message from another user.

quit(message='')

Quit from the IRC server.

reactor = None

The reactor in use on this client. This may be overridden when a deterministic clock is needed, such as in unit tests.

reply(prefix, channel, message)

Send a reply to a user. The method used depends on the values of prefix and channel:

• If prefix is specified and channel starts with an IRC channel prefix (such as # or +), send the reply publicly to the given channel, addressed to the nickname specified by prefix.
• If prefix is specified and channel is the bot’s nickname, send the reply as a private notice to the nickname specified by prefix.
• If prefix is not specified, send the reply publicly to the channel given by channel, with no nickname addressing.

Long replies are buffered in order to satisfy protocol message length limits; a maximum of 256 characters will be sent at any given time. Further content from a buffered reply can be retrieved by using the command provided with the more plugin.

When possible, Omnipresence attempts to truncate replies on whitespace, instead of in the middle of a word. Replies are _always_ broken on newlines, which can be useful for creating commands that progressively give more information.

reply_with_error(failure, prefix, channel, keyword)

Call reply() with information on an error that occurred during an invocation of the command with the given keyword. failure should be an instance of twisted.python.failure.Failure.

Note

This method is automatically called whenever an unhandled exception occurs in a command’s execute() method, and usually does not need to be invoked manually.

resume_joins()

Resume immediate joining of channels after suspending it with suspend_joins(), and perform any channel joins that have been queued in the interim.

setNick(nickname)

Change the bot’s nickname.

signedOn()

Called after successfully signing on to the server.

signon_timed_out()

Called when a timeout occurs after connecting to the server, but before receiving the RPL_WELCOME message that starts the normal PING heartbeat.

signon_timeout = None

An IDelayedCall used to detect timeouts that occur after connecting to the server, but before receiving the RPL_WELCOME message that starts the normal PING heartbeat.

suspend_joins()

Suspend all channel joins until resume_joins() is called.

suspended_joins = None

If joins are suspended, a set containing the channels to join when joins are resumed. Otherwise, None.

topic(channel, topic=None)

Change the topic of channel if a topic is provided; otherwise, ask the IRC server for the current channel topic, which will be provided through the topicUpdated() callback.

topicUpdated(nick, channel, newTopic)

Called when the topic of the given channel is changed.

userJoined(prefix, channel)

Called when another user joins the given channel.

userKicked(kickee, channel, kicker, message)

Called when another user kicks a third party from the given channel.

userLeft(prefix, channel)

Called when another user leaves the given channel.

userQuit(prefix, quitMessage)

Called when another user has quit the IRC server.

userRenamed(oldname, newname)

Called when another user changes nick.