API Reference

This is the documentation of the API for users of FredIRC.

Overview

The following classes are the main part of the API and might be of interest to anyone who uses FredIRC:

  • IRCHandler - Abstract base class containing event handler methods that can be implemented in subclasses.
  • BaseIRCHandler - You probably want to subclass this, to overwrite handler methods in your bot. It is derived from IRCHandler itself.
  • IRCClient - Implements basic IRC client functionality and runs the whole framework. Provides an interface to send messages to the server.
  • Task - Schedule tasks to be executed by the event loop at a specific time.

IRCHandler Class

class fredirc.IRCHandler[source]

Abstract base class for IRC handler classes.

This abstract base class contains handler functions for IRC related events (mostly messages from a server) a client might be interested in. It just defines an interface and all method bodies are empty. You probably want to subclass BaseIRCHandler instead of inheriting directly from this class.

handle_client_init(client)[source]

This handler was attached to a client.

Parameters:client (IRCClient) – The client.
handle_connect()[source]

The client established a connection to the server.

handle_disconnect()[source]

The client lost connection to the server.

This might be the result of a network error but also occurs after a quit by the client or a forced disconnect by the server.

handle_register()[source]

The client successfully registered to the server.

handle_channel_message(channel, message, sender=None)[source]

Received a message to a channel.

A message was sent to a channel the client currently belongs to. Does not include messages from the client itself!

Parameters:
  • channel (str) – the channel name
  • message (str) – the received message
  • sender (str) – Sender of the message, usually a nickname.
  • be None. (Might) –
handle_private_message(message, sender=None)[source]

Received private message (query).

Parameters:
  • message (str) – the received message
  • sender (str) – Sender of the message, usually a nickname. Might be None.
handle_join(channel, nick)[source]

Called when another user joined the channel.

To handle joins of the IRCClient itself, use handle_own_join().

Parameters:
  • channel (str) – a name of a channel, the client is currently in
  • nick (str) – nick of the member that joined the channel
handle_own_join(channel)[source]

Called when the IRCClient joined a channel.

To handle joins of other members, use handle_join().

Parameters:channel (str) – name of the channel
handle_quit(nick, message=None)[source]

A user disconnected from the server.

Also see: handle_part()

Parameters:
  • nick (str) – nick of the user
  • message (str) – quit message (might be None)
handle_part(channel, nick, message=None)[source]

Called when another user left the channel.

To handle partings of the IRCClient itself, use handle_own_part().

Also see: handle_quit()

Parameters:
  • channel (str) – a name of a channel, the client is currently in
  • nick (str) – nick of the member that left the channel
  • message (str) – part message of the parting member (might be None)
handle_own_part(channel)[source]

Called when the IRCClient left a channel.

To handle parting of other members, use handle_part().

Parameters:channel (str) – name of the channel
handle_kick(channel, nick, initiator, reason)[source]

Another user got kicked from a channel.

Parameters:
  • channel (str) – the channel
  • nick (str) – the user who got kicked
  • reason (str) – reason for the kick (might be None)
handle_own_kick(channel, initiator, reason)[source]

The IRCClient got kicked from a channel.

Parameters:
  • channel (str) – the channel
  • reason (str) – reason for the kick (might be None)
handle_got_op(channel, nick, initiator)[source]

Another user received operator status.

Parameters:
  • channel (str) – name of the channel
  • nick (str) – the user who became operator
  • initiator (str) – the user who granted the operator rights
handle_own_got_op(channel, initiator)[source]

The IRCClient received operator status.

Parameters:
  • channel (str) – name of the channel
  • initiator (str) – the user who granted the operator rights
handle_lost_op(channel, nick, initiator)[source]

Another user lost operator status.

Parameters:
  • channel (str) – name of the channel
  • nick (str) – the user who is no longer operator
  • initiator (str) – the user who initiated the mode change
handle_own_lost_op(channel, initiator)[source]

The IRCClient lost operator status.

Parameters:
  • channel (str) – name of the channel
  • initiator (str) – the user who initiated the mode change
handle_got_voice(channel, nick, initiator)[source]

Another user received voice rights.

Parameters:
  • channel (str) – name of the channel
  • nick (str) – the user who received voice
  • initiator (str) – the user who granted the voice rights
handle_own_got_voice(channel, initiator)[source]

The IRCClient received voice rights.

Parameters:
  • channel (str) – name of the channel
  • initiator (str) – the user who granted the voice rights
handle_lost_voice(channel, nick, initiator)[source]

Another user lost voice rights.

Parameters:
  • channel (str) – name of the channel
  • nick (str) – the user who no longer has voice
  • initiator (str) – the user who initiated the mode change
handle_own_lost_voice(channel, initiator)[source]

The IRCClient lost voice rights.

Parameters:
  • channel (str) – name of the channel
  • initiator (str) – the user who initiated the mode change
handle_nick_change(old_nick, new_nick)[source]

A user’s nick name changed.

To handle nick changes of the IRCClient itself, use handle_own_nick_change().

Parameters:
  • old_nick (str) – The nick name of the user until now.
  • new_nick (str) – The new nick name of the user.
handle_own_nick_change(old_nick, new_nick)[source]

The IRCCLient’s nick name changed.

The nick-property will already hold the new nick when this handler is called.

Parameters:
  • old_nick (str) – The old nick name.
  • new_nick (str) – The new nick name.
handle_response(response, message)[source]

A numeric response was received from the server.

See the IRC client protocol specification for valid numeric response codes and their meaning. There are extra handler methods for many common responses, but this general handler is always called first.

Parameters:
  • response (int) – 3-digit response code (between 0 and 399)
  • message (str) – the whole, raw message
handle_error(error, **params)[source]

An irc error message was received from the server.

The error codes are defined in Err. The contents of the params dictionary depend on the specific error. See the documentation of Err for details.

Parameters:
  • error (int) – 3-digit error code (between 400 and 599)
  • params (dict) – Parameters of the error message, each consisting of a parameter name and a value.
handle_ping(server)[source]

Received a ping message from the server.

Parameters:server (str) – name or ip of the server.
handle_unhandled_message(message)[source]
This handler is called whenever a message is not handled by any
other handler.

A message is not handled if either the message is not yet supported by FredIRC or it is invalid/malformed.

Parameters:message (str) – The raw message as received by the client.

BaseIRCHandler Class

class fredirc.BaseIRCHandler[source]

Minimal IRCHandler implementation.

Implements the most basic handler functionality that probably every bot will need. It is recommended to subclass BaseIRCHandler instead of IRCHandler.

What it does for you:

IRCClient Class

class fredirc.IRCClient(handler, nick, server, port=6667, user_name=None, real_name=None, password=None)[source]
IRC client class managing the network connection and dispatching
messages from the server.

Warning

Currently only a single IRCClient instance is allowed! Don’t run multiple clients. This will result in undefined behaviour. Also after run() terminated you should not call it again! This will probably be fixed in future releases.

To connect to the server and start the processing event loop call run() on your IRCClient instance. Nick, user name, real name and password are used by register() to register the client to the server.

Most methods and members that return some state of the client (e.g. is_op_in() or channels) do not need to interact with the server to get the corresponding information. Instead it is cached in the client.

It is also important to remember that the data in the client is only updated on messages from the server. For Example: channels will not contain a new channel instantly after joining it with join() but only after handle_own_join() was called.

Channel and nick name arguments to methods that send a command to the server are case insensitive, except for methods that change the clients nick. Channel names returned by the server (e.g. in IRCClient’s channels-property) are usually lower case while nick names are the case they were registered by it’s user.

Parameters:
  • handler (IRCHandler) – handler that handles events from this client
  • nick (str) – nick name for the client
  • server (str) – server name or ip
  • port (int) – port number to connect to
  • user_name (str) – User name for registration to the server. If None, nick is used.
  • real_name (str) – Full name of the client. If None, nick is used.
  • password (str) – Optional password that can be used to authenticate to the server.
run()[source]

Start the client’s event loop.

An endless event loop which will call the handle_* methods from IRCHandler. The client connects to the server and calls handle_connect() on its handler if this is successful. If the connection is closed the client can re-establish it without exiting the event loop via reconnect(). To terminate the event loop use terminate(). Afterwards run() will return.

reconnect(delay=0.0)[source]

Reconnect the client to the server.

This only reconnects a disconnected client. If the client is still connected to the server, it will have no effects. So reconnect() could be used to re-establish the connection on handle_disconnect().

After successful reconnection handle_connect() gets called.

Parameters:delay (float) – Time to delay the reconnection attempt in seconds. Can be useful as servers might refuse a client that reconnects to fast.
enable_logging(enable)[source]

Enable or disable logging.

Logging is enabled by default.
Parameters:enable (bool) – True to enable logging, False disable it
set_log_level(level)[source]

Set the log level that is used if logging is enabled.

Parameters:level (int) – the log level as defined by constants in Python’s logging module (DEBUG, INFO, WARNING, ERROR, CRITICAL)
terminate()[source]

Shutdown the IRCClient by terminating the event loop.

Control flow will continue after the call to IRCClient.run().

register(nick=None, user_name=None, real_name=None, password=None)[source]

Register to the IRC server.

When called with no arguments, registration data given on initialization or the last call to register is used.

Parameters:
  • nick (str) – Nick name for the client.
  • user_name (str) – User name for registration to the server.
  • real_name (str) – Full name of the client.
  • password (str) – Optional password that might be used to authenticate to the server.
change_nick(nick)[source]

Change the nick name of the client.

Note that the clients nick-property will not change directly, but only after the server acknowledged the new nick name.

Parameters:nick (str) – The new nick name.
join(channel, *channels)[source]

Join the specified channel(s).

Note that no matter what case the channel strings are in, in the handler functions of IRCHandler channel names will probably always be lower case.

Parameters:channel (str) – one or more channels
part(message, channel, *channels)[source]

Leave the specified channel(s).

Parameters:
  • message (str) – part message
  • channel (str) – one or more channels
quit(message=None)[source]

Disconnect from the IRC server.

Also see handle_disconnect()<.IRCHandler.handle_disconnect().

Parameters:message (str) – optional message, send to the server
send_message(channel, message, delay=0.0)[source]

Send a message to a channel.

Parameters:
  • channel (str) – the addressed channel
  • message (str) – the message to send
  • delay (float) – the delay in second before sending message the bot is not blocked during delay
send_private_message(user, message)[source]

Send a private message to a user.

Parameters:
  • user (str) – the addressed user
  • message (str) – the message tro send
kick(user, channel, reason=None)[source]

Forcefully remove a user from a channel.

If the client is no operator, the server will respond with an error message that can be handled via handle_error().

Parameters:
  • user (str) – the affected user
  • channel (str) – the channel
  • reason (str) – optional message with the reason
give_op(user, channel)[source]

Grant operator rights to a user on a channel.

If the client is no operator, the server will respond with an error message that can be handled via handle_error().

Parameters:
  • user (str) – the affected user
  • channel (str) – the channel
revoke_op(user, channel)[source]

Revoke operator rights from user on a channel.

If the client is no operator, the server will respond with an error message that can be handled via handle_error().

Parameters:
  • user (str) – the affected user
  • channel (str) – the channel
give_voice(user, channel)[source]

Grant voice rights to a user on a channel.

If the client is no operator, the server will respond with an error message that can be handled via handle_error().

Parameters:
  • user (str) – the affected user
  • channel (str) – the channel
revoke_voice(user, channel)[source]

Revoke voice rights from user on a channel.

If the client is no operator, the server will respond with an error message that can be handled via handle_error().

Parameters:
  • user (str) – the affected user
  • channel (str) – the channel
is_op_in(channel)[source]

Check if this client has operator rights in the given channel.

Parameters:channel (str) – the channel (case-insensitive)
has_voice_in(channel)[source]

Check if this client has voice rights in the given channel.

Parameters:channel (str) – the channel (case-insensitive)
pong()[source]

Send a pong message to the server.

channel_info

Get information about channels.

To get all channel names use channels.

Returns:A read-only(!) mapping of channel names to ChannelInfo objects.
Return type:dict
nick

Current nick name of the client (read-only).

Returns:nick name or None if client is not registered
Return type:str
server

Name of the Server this client is currently connected to (read-only).

Returns:server name or None if client is not connected to a server.
Return type:str
channels

Names of channels this client is currently in (read-only).

Returns:over channel names as strings
Return type:iterator

ChannelInfo Class

class fredirc.ChannelInfo(name)[source]

Provides information about a channel.

A ChannelInfo object is a view on a channel and is automatically updated as long as the client is in the channel. Afterwards the ChannelInfo becomes invalid and should not be used any longer.

name

Name of the channel (read-only).

Returns:name
Return type:str
topic

Topic of the channel (read-only).

Returns:topic, might be empty
Return type:str
nicks

Nicks of all visible users in this channel. (read-only).

Returns:over nick names
Return type:iterator

Task Class

class fredirc.Task(delay, repeat=False, func=None)[source]

A Task can be used to schedule a function that will be executed by the event loop.

Note

A task will be scheduled only if there is a running(!) IRCClient instance in the same process.

There are two ways to use a Task:

  1. Subclass Task and overwrite its run() method.
  2. Instantiate the task directly and provide a function as parameter to the constructor.

After initialization the Task must be started explicitly via start().

Parameters:
  • delay (float) – Time (in seconds) to defer the execution of the task after it is started or the interval for its repeated execution if repeat=True.
  • repeat (bool) – If True the task will run periodically until it is stopped.
  • func (function type) – function that will be called (the actual task)
change_delay(delay)[source]

Change Task delay.

The new delay will be applied to the next repeat of the tasK

run()[source]

Method that is called on execution of the Task.

Can be overwritten in subclasses or by passing a function to the constructor.

start()[source]

Start the task.

It will be executed after the configured delay. A started task can be stopped by calling stop().

stop()[source]

Stop the task.

Will have no effect if task is not running. The task might be started again later.

Err Class

class fredirc.Err[source]

Error Replies

Contains numerical constants for errors as defined by the irc client protocol as well as the keywords of error specific parameters. Error numbers and parameters are passed to handle_error(self, error, **params). You can take a look at ERROR_PARAMETERS to find out the parameter keywords for a particular error.

See the beginner’s guide for an example on how to use this class to handle errors.

NOSUCHNICK = 401
NOSUCHSERVER = 402
NOSUCHCHANNEL = 403
CANNOTSENDTOCHAN = 404
TOOMANYCHANNELS = 405
WASNOSUCHNICK = 406
TOOMANYTARGETS = 407
NOSUCHSERVICE = 408
NOORIGIN = 409
NORECIPIENT = 411
NOTEXTTOSEND = 412
NOTOPLEVEL = 413
WILDTOPLEVEL = 414
BADMASK = 415
UNKNOWNCOMMAND = 421
NOMOTD = 422
NOADMININFO = 423
FILEERROR = 424
NONICKNAMEGIVEN = 431
ERRONEUSNICKNAME = 432
NICKNAMEINUSE = 433
NICKCOLLISION = 436
UNAVAILRESOURCE = 437
USERNOTINCHANNEL = 441
NOTONCHANNEL = 442
USERONCHANNEL = 443
NOLOGIN = 444
SUMMONDISABLED = 445
USERSDISABLED = 446
NOTREGISTERED = 451
NEEDMOREPARAMS = 461
ALREADYREGISTRED = 462
NOPERMFORHOST = 463
PASSWDMISMATCH = 464
YOUREBANNEDCREEP = 465
KEYSET = 467
YOUWILLBEBANNED = 466
CHANNELISFULL = 471
UNKNOWNMODE = 472
INVITEONLYCHAN = 473
BANNEDFROMCHAN = 474
BADCHANNELKEY = 475
BADCHANMASK = 476
NOCHANMODES = 477
BANLISTFULL = 478
NOPRIVILEGES = 481
CHANOPRIVSNEEDED = 482
CANTKILLSERVER = 483
RESTRICTED = 484
UNIQOPPRIVSNEEDED = 485
NOOPERHOST = 491
UMODEUNKNOWNFLAG = 501
USERSDONTMATCH = 502
ERROR_PARAMETERS = {401: ['nick', 'message'], 402: ['server_name', 'message'], 403: ['channel_name', 'message'], 404: ['channel_name', 'message'], 405: ['channel_name', 'message'], 406: ['nick', 'message'], 407: ['target', 'message'], 408: ['service_name', 'message'], 409: ['message'], 411: ['message'], 412: ['message'], 413: ['mask', 'message'], 414: ['mask', 'message'], 415: ['mask', 'message'], 421: ['command', 'message'], 422: ['message'], 423: ['server', 'message'], 424: ['message'], 431: ['message'], 432: ['nick', 'message'], 433: ['nick', 'message'], 436: ['nick', 'message'], 437: ['nick', 'message'], 441: ['nick', 'channel', 'message'], 442: ['channel', 'message'], 443: ['user', 'channel', 'message'], 444: ['user', 'channel', 'message'], 445: ['message'], 446: ['message'], 451: ['message'], 461: ['command', 'message'], 462: ['message'], 463: ['message'], 464: ['message'], 465: ['message'], 466: [], 467: ['channel', 'message'], 471: ['channel', 'message'], 472: ['mode', 'message'], 473: ['channel', 'message'], 474: ['channel', 'message'], 475: ['channel', 'message'], 476: ['channel', 'message'], 477: ['channel', 'message'], 478: ['channel', 'message'], 481: ['message'], 482: ['channel', 'message'], 483: ['message'], 484: ['message'], 485: ['message'], 491: ['message'], 501: ['message'], 502: ['message']}

Exception Classes

class fredirc.FredIRCError(message)[source]

Base class for FredIRC specific Exceptions. Contains a message with further description of the error.

class fredirc.MessageHandlingError(message)[source]

Indicates that the specified message can not be handled by any of the normal message handlers.

class fredirc.ParserError(message)[source]

Indicates that a parser rejects its input.

class fredirc.ConnectionTimeoutError(message)[source]

The connection to a server timed out.