supybot.ircmsgs

This module provides the basic IrcMsg object used throughout the bot to represent the actual messages. It also provides several helper functions to construct such messages in an easier way than the constructor for the IrcMsg object (which, as you’ll read later, is quite…full-featured :))

class supybot.ircmsgs.IrcMsg(s='', command='', args=(), prefix='', server_tags=None, msg=None, reply_env=None)

Class to represent an IRC message.

As usual, ignore attributes that begin with an underscore. They simply don’t exist. Instances of this class are not to be modified, since they are hashable. Public attributes of this class are .prefix, .command, .args, .nick, .user, and .host.

The constructor for this class is pretty intricate. It’s designed to take any of three major (sets of) arguments.

Called with no keyword arguments, it takes a single string that is a raw IRC message (such as one taken straight from the network).

Called with keyword arguments, it requires a command parameter. Args is optional, but with most commands will be necessary. Prefix is obviously optional, since clients aren’t allowed (well, technically, they are, but only in a completely useless way) to send prefixes to the server.

Since this class isn’t to be modified, the constructor also accepts a ‘msg’ keyword argument representing a message from which to take all the attributes not provided otherwise as keyword arguments. So, for instance, if a programmer wanted to take a PRIVMSG they’d gotten and simply redirect it to a different source, they could do this:

IrcMsg(prefix=’’, args=(newSource, otherMsg.args[1]), msg=otherMsg)

command

The IRC command of the message (eg. PRIVMSG, NOTICE, MODE, QUIT, …). In case of “split” commands (eg. CAP LS), this is only the first part, and the other parts are in args.

args

Arguments of the IRC command (including subcommands). For example, for a PRIVMSG, args = (‘#channel’, ‘content of the message’).

channel

The name of the channel this message was received on or will be sent to; or None if this is not a channel message (PRIVMSG to a nick, QUIT, etc.)

msg.args[0] was formerly used to get the channel, but it had several pitfalls (such as needing server-specific channel vs nick detection, and needing to strip statusmsg characters).

prefix

nick!user@host of the author of the message, or None.

nick

Nickname of the author of the message, or None.

user

Username/ident of the author of the message, or None.

host

Hostname of the author of the message, or None.

time

Float timestamp of the moment the message was sent by the server. If the server does not support server-time, this falls back to the value of time.time() when the message was received.

server_tags

Dictionary of IRCv3 message tags. None values indicate the tag is present but has no value.

This includes client tags; the name is meant to disambiguate wrt the tags attribute, which are tags used internally by Supybot/Limnoria.

reply_env

(Mutable) dictionary of internal key:value pairs, all of which must be strings.

Several plugins offer string templating, such as the ‘echo’ command in the Misc plugin; which replace $variable with a value.

Adding values to this dictionary allows access to these values from these commands; this is especially useful when nesting commands.

tags

(Mutable) dictionary of internal key:value pairs on this message.

This is not to be confused with IRCv3 message tags; these are stored as server_tags (including the client tags).

tag(tag, value=True)

Affect an internal key:value pair to this message.

This is not to be confused with IRCv3 message tags; these are stored as server_tags (including the client tags).

tagged(tag)

Get the value affected to a tag, or None if it is not set..

exception supybot.ircmsgs.MalformedIrcMsg

supybot.ircmsgs.action(recipient, s, prefix='', msg=None)

Returns a PRIVMSG ACTION to recipient with the message s.

supybot.ircmsgs.ban(channel, hostmask, exception='', prefix='', msg=None)

Returns a MODE to ban nick on channel.

supybot.ircmsgs.bans(channel, hostmasks, exceptions=(), prefix='', msg=None)

Returns a MODE to ban each of nicks on channel.

supybot.ircmsgs.dehalfop(channel, nick, prefix='', msg=None)

Returns a MODE to dehalfop nick on channel.

supybot.ircmsgs.dehalfops(channel, nicks, prefix='', msg=None)

Returns a MODE to dehalfop each of nicks on channel.

supybot.ircmsgs.deop(channel, nick, prefix='', msg=None)

Returns a MODE to deop nick on channel.

supybot.ircmsgs.deops(channel, nicks, prefix='', msg=None)

Returns a MODE to deop each of nicks on channel.

supybot.ircmsgs.devoice(channel, nick, prefix='', msg=None)

Returns a MODE to devoice nick on channel.

supybot.ircmsgs.devoices(channel, nicks, prefix='', msg=None)

Returns a MODE to devoice each of nicks on channel.

supybot.ircmsgs.halfop(channel, nick, prefix='', msg=None)

Returns a MODE to halfop nick on channel.

supybot.ircmsgs.halfops(channel, nicks, prefix='', msg=None)

Returns a MODE to halfop each of nicks on channel.

supybot.ircmsgs.invite(nick, channel, prefix='', msg=None)

Returns an INVITE for nick.

supybot.ircmsgs.isAction(msg)

A predicate returning true if the PRIVMSG in question is an ACTION

supybot.ircmsgs.isCtcp(msg)

Returns whether or not msg is a CTCP message.

supybot.ircmsgs.join(channel, key=None, prefix='', msg=None)

Returns a JOIN to a channel

supybot.ircmsgs.joins(channels, keys=None, prefix='', msg=None)

Returns a JOIN to each of channels.

supybot.ircmsgs.kick(channel, nick, s='', prefix='', msg=None)

Returns a KICK to kick nick from channel with the message s.

supybot.ircmsgs.kicks(channels, nicks, s='', prefix='', msg=None)

Returns a KICK to kick each of nicks from channel with the message s.

supybot.ircmsgs.modes(channel, args=(), prefix='', msg=None)

Returns a MODE message for the channel for all the (mode, targetOrNone) 2-tuples in ‘args’.

supybot.ircmsgs.nick(nick, prefix='', msg=None)

Returns a NICK with nick nick.

supybot.ircmsgs.notice(recipient, s, prefix='', msg=None)

Returns a NOTICE to recipient with the message s.

supybot.ircmsgs.op(channel, nick, prefix='', msg=None)

Returns a MODE to op nick on channel.

supybot.ircmsgs.ops(channel, nicks, prefix='', msg=None)

Returns a MODE to op each of nicks on channel.

supybot.ircmsgs.part(channel, s='', prefix='', msg=None)

Returns a PART from channel with the message s.

supybot.ircmsgs.parts(channels, s='', prefix='', msg=None)

Returns a PART from each of channels with the message s.

supybot.ircmsgs.password(password, prefix='', msg=None)

Returns a PASS command for accessing a server.

supybot.ircmsgs.ping(payload, prefix='', msg=None)

Takes a payload and returns the proper PING IrcMsg.

supybot.ircmsgs.pong(payload, prefix='', msg=None)

Takes a payload and returns the proper PONG IrcMsg.

supybot.ircmsgs.prettyPrint(msg, addRecipients=False, timestampFormat=None, showNick=True)

Provides a client-friendly string form for messages.

IIRC, I copied BitchX’s (or was it XChat’s?) format for messages.

supybot.ircmsgs.privmsg(recipient, s, prefix='', msg=None)

Returns a PRIVMSG to recipient with the message s.

supybot.ircmsgs.quit(s='', prefix='', msg=None)

Returns a QUIT with the message s.

supybot.ircmsgs.split_args(s, maxsplit=-1)

Splits on spaces, treating consecutive spaces as one.

supybot.ircmsgs.topic(channel, topic=None, prefix='', msg=None)

Returns a TOPIC for channel with the topic topic.

supybot.ircmsgs.unAction(msg)

Returns the payload (i.e., non-ACTION text) of an ACTION msg.

supybot.ircmsgs.unban(channel, hostmask, prefix='', msg=None)

Returns a MODE to unban nick on channel.

supybot.ircmsgs.unbans(channel, hostmasks, prefix='', msg=None)

Returns a MODE to unban each of nicks on channel.

supybot.ircmsgs.user(ident, user, prefix='', msg=None)

Returns a USER with ident ident and user user.

supybot.ircmsgs.voice(channel, nick, prefix='', msg=None)

Returns a MODE to voice nick on channel.

supybot.ircmsgs.voices(channel, nicks, prefix='', msg=None)

Returns a MODE to voice each of nicks on channel.

supybot.ircmsgs.who(hostmaskOrChannel, prefix='', msg=None, args=())

Returns a WHO for the hostmask or channel hostmaskOrChannel.

supybot.ircmsgs.whois(nick, mask='', prefix='', msg=None)

Returns a WHOIS for nick.

supybot.ircmsgs.whowas(nick, mask='', prefix='', msg=None)

Returns a WHOIS for nick.