csbot.irc module

exception csbot.irc.IRCParseError

Bases: Exception

Raised by IRCMessage.parse() when a message can’t be parsed.

class csbot.irc.IRCMessage(raw: str, prefix: Optional[str], command: str, params: List[str], command_name: str)

Bases: object

Represents an IRC message.

The IRC message format, paraphrased and simplified from RFC2812, is:

message = [":" prefix " "] command {" " parameter} [" :" trailing]

Has the following attributes:

Parameters:

• raw (str) – The raw IRC message
• prefix (str or None) – Prefix part of the message, usually the origin
• command (str) – IRC command
• params (list of str) – List of command parameters (including trailing)
• command_name (str) – Name of IRC command (see below)

The command_name attribute is intended to be the “readable” form of the command. Usually it will be the same as command, but numeric replies recognised in RFC2812 will have their corresponding name instead.

raw

prefix

command

params

command_name

REGEX = re.compile('(:(?P<prefix>\\S+) )?(?P<command>\\S+)(?P<params>( (?!:)\\S+)*)( :(?P<trailing>.*))?')

Regular expression to extract message components from a message.

FORCE_TRAILING = {'PRIVMSG', 'QUIT', 'USER'}

Commands to force trailing parameter (:blah) for

classmethod parse(line)

Create an IRCMessage object by parsing a raw message.

classmethod create(command, params=None, prefix=None)

Create an IRCMessage from its core components.

The raw and command_name attributes will be generated based on the message details.

pretty

Get a more readable version of the raw IRC message.

Pretty much identical to the raw IRC message, but numeric commands that have names end up being NUMERIC/NAME.

pad_params(length, default=None)

Pad parameters to length with default.

Useful when a command has optional parameters:

>>> msg = IRCMessage.parse(':nick!user@host KICK #channel other')
>>> channel, nick, reason = msg.params
Traceback (most recent call last):
  ...
ValueError: need more than 2 values to unpack
>>> channel, nick, reason = msg.pad_params(3)

class csbot.irc.IRCUser(raw: str, nick: str, user: Optional[str], host: Optional[str])

Bases: object

Provide access to the parts of an IRC user string.

The following parts of the user string are available, set to None if that part of the string is absent:

Parameters:

• raw – Raw user string
• nick – Nick of the user
• user – Username of the user (excluding leading ~)
• host – Hostname of the user

>>> IRCUser.parse('my_nick!some_user@host.name')
IRCUser(raw='my_nick!some_user@host.name', nick='my_nick', user='some_user', host='host.name')

raw

nick

user

host

REGEX = re.compile('(?P<raw>(?P<nick>[^!]+)(!~*(?P<user>[^@]+))?(@(?P<host>.+))?)')

Username parsing regex. Stripping out the “~” might be a Freenode peculiarity…

classmethod parse(raw)

Create an IRCUser from a raw user string.

class csbot.irc.IRCCodec

Bases: codecs.Codec

The encoding scheme to use for IRC messages.

IRC messages are “just bytes” with no encoding made explicit in the protocol definition or the messages. Ideally we’d like to handle IRC messages as proper strings.

encode(input, errors='strict')

Encode a message as UTF-8.

decode(input, errors='strict')

Decode a message.

IRC messages could pretty much be in any encoding. Here we just try the two most likely candidates: UTF-8, falling back to CP1252. Unfortunately, any encoding where every byte is valid (e.g. CP1252) makes it impossible to detect encoding errors - if input isn’t UTF-8 or CP1252-compatible, the result might be a bit odd.

exception csbot.irc.IRCClientError

Bases: Exception

class csbot.irc.IRCClient(*, loop=None, **kwargs)

Bases: object

Internet Relay Chat client protocol.

A line-oriented protocol for communicating with IRC servers. It handles receiving data at several layers of abstraction:

• line_received(): decoded line
• message_received(): parsed IRCMessage
• irc_<COMMAND>(msg): called when msg.command == '<COMMAND>'
• on_<event>(...): specific events with specific arguments, e.g. on_quit(user, message)

It also handles sending data at several layers of abstraction:

• send_line(): raw IRC command, e.g. self.send_line('JOIN #cs-york-dev')
• send(): IRCMessage, e.g. self.send(IRCMessage.create('JOIN', params=['#cs-york-dev']))
• <action>(...): e.g. self.join('#cs-york-dev').

The API and implementation is inspired by irc3 and Twisted.

• TODO: NAMES
• TODO: MODE
• TODO: More sophisticated CTCP? (see Twisted)
• TODO: MOTD?
• TODO: SSL

codec = <csbot.irc.IRCCodec object>

Codec for encoding/decoding IRC messages.

static DEFAULTS()

Generate a default configuration. Easier to call this and update the result than relying on dict.copy().

available_capabilities = None

Available client capabilities

enabled_capabilities = None

Enabled client capabilities

disconnect()

Disconnect from the IRC server.

Use quit() for a more graceful disconnect.

line_received(line: str)

Callback for received raw IRC message.

line_sent(line: str)

Callback for sent raw IRC message.

Subclasses can implement this to get access to the actual message that was sent (which may have been truncated from what was passed to send_line()).

message_received(msg)

Callback for received parsed IRC message.

send_line(data: str)

Send a raw IRC message to the server.

Encodes, terminates and sends data to the server. If the line would be longer than the maximum allowed by the IRC specification, it is trimmed to fit (without breaking UTF-8 sequences).

If rate limiting is enabled, the message may not be sent immediately.

send(msg)

Send an IRCMessage.

class Waiter(predicate: Callable[[csbot.irc.IRCMessage], Tuple[bool, Any]], future: _asyncio.Future)

Bases: object

PredicateType = typing.Callable[[csbot.irc.IRCMessage], typing.Tuple[bool, typing.Any]]

wait_for_message(predicate: Callable[[csbot.irc.IRCMessage], Tuple[bool, Any]]) → _asyncio.Future

Wait for a message that matches predicate.

predicate should return a (did_match, result) tuple, where did_match is a boolean indicating if the message is a match, and result is the value to return.

Returns a future that is resolved with result on the first matching message.

process_wait_for_message(msg)

request_capabilities(*, enable: Iterable[str] = None, disable: Iterable[str] = None) → Awaitable[bool]

Request a change to the enabled IRCv3 capabilities.

enable and disable are sets of capability names, with disable taking precedence.

Returns a future which resolves with True if the request is successful, or False otherwise.

set_nick(nick)

Ask the server to set our nick.

join(channel)

Join a channel.

leave(channel, message=None)

Leave a channel, with an optional message.

quit(message=None, reconnect=False)

Leave the server.

If reconnect is False, then the client will not attempt to reconnect after the server closes the connection.

msg(to, message)

Send message to a channel/nick.

act(to, action)

Send action as a CTCP ACTION to a channel/nick.

notice(to, message)

Send message as a NOTICE to a channel/nick.

set_topic(channel, topic)

Try and set a channel’s topic.

get_topic(channel)

Ask server to send the topic for channel.

Will cause on_topic_changed() at some point in the future.

ctcp_query(to, command, data=None)

Send CTCP query.

ctcp_reply(to, command, data=None)

Send CTCP reply.

irc_RPL_WELCOME(msg)

Received welcome from server, now we can start communicating.

Welcome should include the accepted nick as the first parameter. This may be different to the nick we requested (e.g. truncated to a maximum length); if this is the case we store the new nick and fire the on_nick_changed() event.

irc_ERR_NICKNAMEINUSE(msg)

Attempted nick is in use, try another.

Adds an underscore to the end of the current nick. If the server truncated the nick, replaces the last non-underscore with an underscore.

irc_PING(msg)

IRC PING/PONG keepalive.

irc_CAP(msg)

Dispatch CAP subcommands to their own methods.

irc_CAP_LS(msg)

Response to CAP LS, giving list of available capabilities.

irc_CAP_ACK(msg)

Response to CAP REQ, acknowledging capability changes.

irc_CAP_NAK(msg)

Response to CAP REQ, rejecting capability changes.

irc_NICK(msg)

Somebody’s nick changed.

irc_JOIN(msg)

Somebody joined a channel.

irc_PART(msg)

Somebody left a channel.

irc_KICK(msg)

Somebody was kicked from a channel.

irc_QUIT(msg)

Somebody quit the server.

irc_TOPIC(msg)

A channel’s topic changed.

irc_RPL_TOPIC(msg)

Topic notification, usually after joining a channel.

irc_PRIVMSG(msg)

Received a PRIVMSG.

TODO: Implement CTCP queries.

irc_NOTICE(msg)

Received a NOTICE.

TODO: Implement CTCP replies.

on_capabilities_available(capabilities)

Client capabilities are available.

Called with a set of client capability names when we get a response to CAP LS.

on_capability_enabled(name)

Client capability enabled.

Called when enabling client capability name has been acknowledged.

on_capability_disabled(name)

Client capability disabled.

Called when disabling client capability name has been acknowledged.

on_welcome()

Successfully signed on to the server.

on_nick_changed(nick)

Changed nick.

on_joined(channel)

Joined a channel.

on_left(channel)

Left a channel.

on_kicked(channel, by, reason)

Kicked from a channel.

on_privmsg(user, to, message)

Received a message, either directly or in a channel.

on_notice(user, to, message)

Received a notice, either directly or in a channel.

on_action(user, to, action)

Received CTCP ACTION. Common enough to deserve its own event.

on_ctcp_query_ACTION(user, to, data)

Turn CTCP ACTION into on_action() event.

on_user_renamed(oldnick, newnick)

User changed nick.

connect()

Connect to the IRC server.

connection_lost(exc)

Handle a broken connection by attempting to reconnect.

Won’t reconnect if the broken connection was deliberate (i.e. close() was called).

connection_made()

Callback for successful connection.

Register with the IRC server.

on_user_joined(user, channel)

User joined a channel.

read_loop()

Read and dispatch lines until the connection closes.

run(run_once=False)

Run the bot, reconnecting when the connection is lost.

on_user_left(user, channel, message)

User left a channel.

on_user_kicked(user, channel, by, reason)

User kicked from a channel.

on_user_quit(user, message)

User disconnected.

on_topic_changed(user, channel, topic)

user changed the topic of channel to topic.

csbot.irc.main()