supybot.irclib

Irc

It is usually the irc object given to plugin commands.

class supybot.irclib.Irc(network, callbacks=[])

The base class for an IRC connection.

Handles PING commands already.

zombie

Whether or not this object represents a living IRC connection.

Type:

bool

network

The name of the network this object is connected to.

Type:

str

startedAt

When this connection was (re)started.

Type:

float

callbacks

List of all callbacks (ie. plugins) currently loaded

Type:

List[IrcCallback]

queue

Queue of messages waiting to be sent. Plugins should use the queueMsg method instead of accessing this directly.

Type:

IrcMsgQueue

fastqueue

Same as queue, but for messages with high priority. Plugins should use the sendMsg method instead of accessing this directly (or queueMsg if the message isn’t high priority).

Type:

smallqueue

driver

Driver of the IRC connection (normally, a supybot.drivers.Socket.SocketDriver object). Plugins normally do not need to access this.

startedSync

When joining a channel, a '#channel': time.time() entry is added to this dict, which is then removed when the join is completed. Plugins should not change this value, it is automatically handled when they send a JOIN.

Type:

ircutils.IrcDict[str, float]

monitoring

A dict with nicks as keys and the number of plugins monitoring this nick as value. Plugins should not access this directly, and should use the monitor and unmonitor methods instead.

Type:

ircutils.IrcDict[str, int]

state

An supybot.irclib.IrcState object, which stores all the known information about the connection with the IRC network.

Type:

supybot.irclib.IrcState

REQUEST_CAPABILITIES = {'account-notify', 'account-tag', 'away-notify', 'batch', 'chghost', 'echo-message', 'extended-join', 'invite-notify', 'labeled-response', 'message-tags', 'metadata-notify', 'msgid', 'multi-prefix', 'sasl', 'server-time', 'setname', 'standard-replies', 'userhost-in-names'}

IRCv3 capabilities requested when they are available.

echo-message is special-cased to be requested only with labeled-response.

To check if a capability was negotiated, use irc.state.capabilities_ack.

REQUEST_EXPERIMENTAL_CAPABILITIES = {'draft/account-registration', 'draft/multiline'}

Like REQUEST_CAPABILITIES, but these capabilities are only requested if supybot.protocols.irc.experimentalExtensions is enabled.

addCallback(callback)

Adds a callback to the callbacks list.

Parameters:

callback (supybot.irclib.IrcCallback) – A callback object

capUpkeep(msg)

Called after getting a CAP ACK/NAK to check it’s consistent with what was requested, and to end the cap negotiation when we received all the ACK/NAKs we were waiting for.

msg is the message that triggered this call.

die(*args, **kwargs)

Makes the Irc object promise to die – but it won’t die (of its own volition) until all its queues are clear. Isn’t that cool?

dispatchCommand(command, args=None)

Given a string ‘command’, dispatches to doCommand.

do002(msg)

Logs the ircd version.

doError(msg)

Handles ERROR messages.

doNick(msg)

Handles NICK messages.

doPing(msg)

Handles PING messages.

doPong(msg)

Handles PONG messages.

feedMsg(*args, **kwargs)

Called by the IrcDriver; feeds a message received.

tag=False is used when simulating echo messages, to skip adding received* tags.

getCallback(name)

Gets a given callback by name.

isChannel(s)

Helper function to check whether a given string is a channel on the network this Irc object is connected to.

isNick(s)

Returns whether the given argument is a valid nick on this network.

monitor(targets)

Increment a counter of how many callbacks monitor each target; and send a MONITOR + to the server if the target is not yet monitored.

queueBatch(msgs)

Queues a batch of messages to be sent to the server. See <https://ircv3.net/specs/extensions/batch-3.2>

queueMsg/sendMsg must not be used repeatedly to send a batch, because they do not guarantee the batch is send atomically, which is required because “Clients MUST NOT send messages other than PRIVMSG while a multiline batch is open.” – <https://ircv3.net/specs/extensions/multiline>

queueMsg(msg)

Queues a message to be sent to the server.

removeCallback(name)

Removes a callback from the callback list.

requestCapabilities(caps)

Takes an iterable of IRCv3 capabilities, and requests them to the server using CAP REQ.

This is mostly just used during connection registration or when the server sends CAP NEW; but plugins may use it as well to request custom capabilities. They should make sure these capabilities cannot negatively impact other plugins, though.

reset()

Resets the Irc object. Called when the driver reconnects.

sendMsg(msg)

Queues a message to be sent to the server immediately

takeMsg(*args, **kwargs)

Called by the IrcDriver; takes a message to be sent.

unmonitor(targets)

Decrements a counter of how many callbacks monitor each target; and send a MONITOR - to the server if the counter drops to 0.

IrcState

Used mainly as the state attribute of supybot.irclib.Irc objects.

class supybot.irclib.IrcState(history=None, supported=None, nicksToHostmasks=None, channels=None, capabilities_req=None, capabilities_ack=None, capabilities_nak=None, capabilities_ls=None, nicksToAccounts=None)

Maintains state of the Irc connection. Should also become smarter.

fsm

A finite-state machine representing the current state of the IRC connection: various steps while connecting, then remains in the CONNECTED state (or CONNECTED_SASL when doing SASL in the middle of a connection).

Type:

IrcStateFsm

capabilities_req

Set of all capabilities requested from the server. See <https://ircv3.net/specs/core/capability-negotiation>

Type:

Set[str]

capabilities_ack

Set of all capabilities requested from and acknowledged by the server. See <https://ircv3.net/specs/core/capability-negotiation>

Type:

Set[str]

capabilities_nak

Set of all capabilities requested from and refused by the server. This should always be empty unless the bot, a plugin, or the server is misbehaving. See <https://ircv3.net/specs/core/capability-negotiation>

Type:

Set[str]

capabilities_ls

Stores all the capabilities advertised by the server, as well as their value, if any.

Type:

Dict[str, Optional[str]]

ircd

Identification string of the software running the server we are connected to. See <https://defs.ircdocs.horse/defs/numerics.html#rpl-myinfo-004>

Type:

str

supported

Stores the value of ISUPPORT sent when connecting. See <https://defs.ircdocs.horse/defs/isupport.html> for the list of keys.

Type:

utils.InsensitivePreservingDict[str, Any]

history

History of messages received from the network. Automatically discards messages so it doesn’t exceed supybot.protocols.irc.maxHistoryLength.

Type:

RingBuffer[ircmsgs.IrcMsg]

channels

Store channel states.

Type:

ircutils.IrcDict[str, ChannelState]

nicksToHostmasks

Stores the last hostmask of a seen nick.

Type:

ircutils.IrcDict[str, str]

nicksToAccounts

Stores the current services account name of a seen nick (or None for un-identified nicks)

Type:

ircutils.IrcDict[str, Optional[str]]

addMsg(*args, **kwargs)

Updates the state based on the irc object and the message.

dispatchCommand(command, args=None)

Given a string ‘command’, dispatches to doCommand.

do004(irc, msg)

Handles parsing the 004 reply

Supported user and channel modes are cached

getClientTagDenied(tag)

Returns whether the given tag is denied by the server, according to its CLIENTTAGDENY policy. This is only informative, and servers may still allow or deny tags at their discretion.

For details, see the RPL_ISUPPORT section in <https://ircv3.net/specs/extensions/message-tags>

getParentBatches(msg)

Given an IrcMsg, returns a list of all batches that contain it, innermost first.

Raises ValueError if msg is not in a batch; or if it is in a batch that has already ended. This restriction may be relaxed in the future.

This means that you should not call getParentBatches on a message that was already processed.

For example, assume Limnoria received the following:

:irc.host BATCH +outer example.com/foo
@batch=outer :irc.host BATCH +inner example.com/bar
@batch=inner :nick!user@host PRIVMSG #channel :Hi
@batch=outer :irc.host BATCH -inner
:irc.host BATCH -outer

If you call getParentBatches on any of the middle three messages, you get [Batch(name='inner', ...), Batch(name='outer', ...)]. And if you call getParentBatches on either the first or the last message, you get [Batch(name='outer', ...)]

And you may only call getParentBatches` on the PRIVMSG if only the first three messages were processed.

getTopic(channel)

Returns the topic for a given channel.

nickToAccount(nick)

Returns the account for a given nick, or None if the nick is logged out. Raises KeyError if the nick was not seen or its account is not known yet.

nickToHostmask(nick)

Returns the hostmask for a given nick.

reset()

Resets the state to normal, unconnected state.

IrcStateFsm

Used as the fsm attribute of supybot.irclib.IrcState objects

class supybot.irclib.IrcStateFsm

Finite State Machine keeping track of what part of the connection initialization we are in.

class States(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Enumeration of all the states of an IRC connection.

CONNECTED = 70

Normal state of the connections

CONNECTED_SASL = 80

Doing SASL authentication in the middle of a connection.

INIT_CAP_NEGOTIATION = 20

Sent CAP LS, did not send CAP END yet

INIT_MOTD = 60

Waiting for end of MOTD

INIT_SASL = 30

In an AUTHENTICATE session

INIT_WAITING_MOTD = 50

Waiting for start of MOTD

UNINITIALIZED = 10

Nothing received yet (except server notices)

on_cap_end(irc, msg)

When we send CAP END

on_end_motd(irc, msg)

On 376 (RPL_ENDOFMOTD) or 422 (ERR_NOMOTD)

on_init_messages_sent(irc)

As soon as USER/NICK/CAP LS are sent

on_sasl_auth_finished(irc, msg)

When sasl auth either succeeded or failed.

on_sasl_start(irc, msg)

Whenever we initiate a SASL transaction.

on_start_motd(irc, msg)

On 375 (RPL_MOTDSTART)

ChannelState

Used mainly as the .state.channels['#chan'] attribute of supybot.irclib.Irc objects.

class supybot.irclib.ChannelState

Represents the known state of an IRC channel.

topic

The topic of a channel (possibly the empty stringà

Type:

str

created

Timestamp of the channel creation, according to the server.

Type:

int

ops

Set of the nicks of all the operators of the channel.

Type:

ircutils.IrcSet[str]

halfops

Set of the nicks of all the half-operators of the channel.

Type:

ircutils.IrcSet[str]

voices

Set of the nicks of all the voiced users of the channel.

Type:

ircutils.IrcSet[str]

users

Set of the nicks of all the users in the channel.

Type:

ircutils.IrcSet[str]

bans

Set of the all the banmasks set in the channel.

Type:

ircutils.IrcSet[str]

modes

Dict of all the modes set in the channel, with they value, if any. This excludes the following modes: ovhbeq

Type:

Dict[str, Optional[str]]

addUser(user, prefix_chars='@%+&~!')

Adds a given user to the ChannelState. Power prefixes are handled.

isHalfop(nick)

Returns whether the given nick is an halfop.

isHalfopPlus(nick)

Returns whether the given nick is an halfop, or an op.

isOp(nick)

Returns whether the given nick is an op.

isOpPlus(nick)

Returns whether the given nick is an op.

isVoice(nick)

Returns whether the given nick is voiced.

isVoicePlus(nick)

Returns whether the given nick is voiced, an halfop, or an op.

removeUser(user)

Removes a given user from the channel.

replaceUser(oldNick, newNick)

Changes the user oldNick to newNick; used for NICK changes.

Other classes

class supybot.irclib.Batch(name, type, arguments, messages, parent_batch)

Represents a batch of messages, see <https://ircv3.net/specs/extensions/batch-3.2>

Only access attributes by their name and do not create Batch objects in plugins; so we can extend the structure without breaking plugins.

arguments

Alias for field number 2

messages

Alias for field number 3

name

Alias for field number 0

parent_batch

Alias for field number 4

type

Alias for field number 1

class supybot.irclib.IrcCallback(*args, **kwargs)

Base class for standard callbacks.

Callbacks derived from this class should have methods of the form “doCommand” – doPrivmsg, doNick, do433, etc. These will be called on matching messages.

callPrecedence(*args, **kwargs)

Returns a pair of (callbacks to call before me, callbacks to call after me)

die(*args, **kwargs)

Makes the callback die. Called when the parent Irc object dies.

inFilter(*args, **kwargs)

Used for filtering/modifying messages as they’re entering.

ircmsgs.IrcMsg objects are immutable, so this method is expected to return another ircmsgs.IrcMsg object. Obviously the same IrcMsg can be returned.

name(*args, **kwargs)

Returns the name of the callback.

outFilter(*args, **kwargs)

Used for filtering/modifying messages as they’re leaving.

As with inFilter, an IrcMsg is returned.

postTransition(*args, **kwargs)

Called when the state of the IRC connection changes.

msg is the message that triggered the transition, if any.

reset(*args, **kwargs)

Resets the callback. Called when reconnecting to the server.

class supybot.irclib.IrcCommandDispatcher

Base class for classes that must dispatch on a command.

dispatchCommand(command, args=None)

Given a string ‘command’, dispatches to doCommand.

class supybot.irclib.IrcMsgQueue(iterable=())

Class for a queue of IrcMsgs. Eventually, it should be smart.

Probably smarter than it is now, though it’s gotten quite a bit smarter than it originally was. A method to “score” methods, and a heapq to maintain a priority queue of the messages would be the ideal way to do intelligent queuing.

As it stands, however, we simply keep track of ‘high priority’ messages, ‘low priority’ messages, and normal messages, and just make sure to return the ‘high priority’ ones before the normal ones before the ‘low priority’ ones.

dequeue()

Dequeues a given message.

enqueue(msg)

Enqueues a given message.

reset()

Clears the queue.