irclib Package

irclib Package

connection Module

class hanyuu.ircbot.irclib.connection.Connection(irclibobj)[source]

Bases: object

Base class for IRC connections.

Must be overridden.

execute_at(at, function, arguments=())[source]

Executes a function at a specified time.

See also


execute_delayed(delay, function, arguments=())[source]

Executes a function after a specified number of seconds.

See also


class hanyuu.ircbot.irclib.connection.Event(eventtype, source, target, arguments=None)[source]

Bases: hanyuu.ircbot.irclib.connection.Event

Class representing an IRC event.

exception hanyuu.ircbot.irclib.connection.IRCError[source]

Bases: exceptions.Exception

Represents an IRC exception.

class hanyuu.ircbot.irclib.connection.ServerConnection(irclibobj)[source]

Bases: hanyuu.ircbot.irclib.connection.Connection

This class represents an IRC server connection.

action(target, action)[source]

Send a CTCP ACTION command.


Send an ADMIN command.


Close the connection.


This method closes the connection permanently; after it has been called, the object is unusable.

connect(server, port, nickname, password=None, username=None, ircname=None, localaddress=u'', localport=0, ssl=False, ipv6=False, encoding=u'utf-8')[source]

Connect/reconnect to a server.

  • server – Server name.
  • port – Port number.
  • nickname – The nickname.
  • password

    IRC Password (if any).


    This is NOT the NickServ password; you have to send that manually.

  • username – The IRC username.
  • ircname – The IRC name (‘realname’).
  • localaddress – Bind the connection to a specific local IP address.
  • localport – Bind the connection to a specific local port.
  • ssl – Enable support for ssl.
  • ipv6 – Enable support for ipv6.

This function can be called to reconnect a closed connection.

Returns the ServerConnection object.

ctcp(ctcptype, target, parameter=u'')[source]

Send a CTCP command.

ctcp_reply(target, parameter)[source]

Send a CTCP REPLY command.


Hang up the connection.


Get the (real) nick name.

This method returns the (real) nickname. The library keeps track of nick changes, so it might not be the nick name that was passed to the connect() method.


Get the (real) server name.

This method returns the (real) server name, or, more specifically, what the server calls itself.


Return the topic of a channel.


You must be joined to the channel in order to get the topic.


Send a GLOBOPS command.

hasaccess(channel, nick)[source]

Check if nick is halfop or higher

hasanymodes(channel, nick, modes)[source]

Check if nick has any of the specified modes on a channel.

inchannel(channel, nick)[source]

Check if nick is in channel


Send an INFO command.

invite(nick, channel)[source]

Send an INVITE command.


Check if a string is a channel name.

Returns True if the argument is a channel name, otherwise False.


Return connection status.

Returns True if connected, otherwise False.

ishop(channel, nick)[source]

Check if nick is half operator on a channel.

isnormal(channel, nick)[source]

Check if nick is a normal on a channel.


Send an ISON command.

isop(channel, nick)[source]

Check if nick is operator or higher on a channel.

isvoice(channel, nick)[source]

Check if nick has voice on a channel.

join(channel, key=u'')[source]

Send a JOIN command.

kick(channel, nick, comment=u'')[source]

Send a KICK command.

Send a LINKS command.

list(channels=None, server=u'')[source]

Send a LIST command.


Send a LUSERS command.

mode(target, command)[source]

Send a MODE command.


Send an MOTD command.


Send a NAMES command.


Send a NICK command.

notice(target, text)[source]

Send a NOTICE command.

oper(nick, password)[source]

Send an OPER command.

part(channels, message=u'')[source]

Send a PART command.


Send a PASS command.

ping(target, target2=u'')[source]

Send a PING command.

pong(target, target2=u'')[source]

Send a PONG command.

privmsg(target, text)[source]

Send a PRIVMSG command.

privmsg_many(targets, text)[source]

Send a PRIVMSG command to multiple targets.


Processes incoming data and dispatches handlers.

Only for internal use.


Send a QUIT command.


This is not the same as disconnect().


Many IRC servers don’t use your quit message unless you’ve been connected for at least 5 minutes.


Disconnect and connect with same parameters


Send raw string to the server.

The string will be padded with appropriate CR LF.


Send raw string to the server, bypassing the flood protection.

squit(server, comment=u'')[source]

Send an SQUIT command.

stats(statstype, server=u'')[source]

Send a STATS command.


Send a TIME command.

topic(channel, new_topic=None)[source]

Send a TOPIC command.


Send a TRACE command.

user(username, realname)[source]

Send a USER command.


Send a USERHOST command.


Send a USERS command.


Send a VERSION command.


Send a WALLOPS command.

who(target=u'', op=u'')[source]

Send a WHO command.


Send a WHOIS command.

whowas(nick, max=u'', server=u'')[source]

Send a WHOWAS command.

exception hanyuu.ircbot.irclib.connection.ServerConnectionError[source]

Bases: hanyuu.ircbot.irclib.connection.IRCError

exception hanyuu.ircbot.irclib.connection.ServerNotConnectedError[source]

Bases: hanyuu.ircbot.irclib.connection.ServerConnectionError

dcc Module

class hanyuu.ircbot.irclib.dcc.DCCConnection(irclibobj, dcctype, dccinfo=(None, 0))[source]

Bases: hanyuu.ircbot.irclib.connection.Connection

This class represents a DCC connection.

DCCConnection objects are instantiated by calling session.Session.dcc().

For usage, see connect() and listen().

connect(address, port)[source]

Connect/reconnect to a DCC peer.

  • address – Host/IP address of the peer.
  • port – The port number to connect to.

Returns the DCCConnection object.


Hang up the connection and close the object.

Parameters:message – Quit message.


After calling this method, the object becomes unusable.


Wait for a connection/reconnection from a DCC peer.

Returns the DCCConnection object.

The local IP address and port are available as localaddress and localport. After connection from a peer, the peer address and port are available as peeraddress and peerport.


Send data to DCC peer.

The string will be padded with appropriate LF if it’s a DCC CHAT session.



exception hanyuu.ircbot.irclib.dcc.DCCConnectionError[source]

Bases: hanyuu.ircbot.irclib.connection.IRCError

session Module

A high level session object to the lower level irclib.connection module.

class hanyuu.ircbot.irclib.session.HighEvent(server, command, nickname, channel, message)[source]

Bases: object

A abstracted event of the IRC library.

classmethod from_low_event(server, low_event)[source]

Generates a high level event from a low level one.

class hanyuu.ircbot.irclib.session.Nickname(host, nickname_only=False)[source]

Bases: object

A simple class that represents a nickname on IRC.

Contains information such as actual nickname, hostmask and more.

class hanyuu.ircbot.irclib.session.Session(encoding=u'utf-8', handle_ctcp=True)[source]

Class that handles one or several IRC server connections.

When a Session object has been instantiated, it can be used to create Connection objects that represent the IRC connections. The responsibility of the Session object is to provide a high-level event-driven framework for the connections and to keep the connections alive. It runs a select loop to poll each connection’s TCP socket and hands over the sockets with incoming data for processing by the corresponding connection. It then encapsulates the low level IRC events generated by the Connection objects into higher level versions.

ctcp_source = None

Used to respond to CTCP SOURCE messages.

ctcp_version = None

Used to respond to CTCP VERSION messages.

dcc(dcctype=u'chat', dccinfo=(None, 0))[source]

Creates and returns a dcc.DCCConnection object.

Parameters:dcctype – “chat” for DCC CHAT connections or “raw” for DCC SEND (or other DCC types). If “chat”, incoming data will be split in newline-separated chunks. If “raw”, incoming data is not touched.

Disconnects all connections.

Parameters:message – The quit message to send to servers.
execute_at(at, function, arguments=())[source]

Execute a function at a specified time.

  • at – Time to execute at (standard “time_t” time).
  • function – The function to call.
  • arguments – Arguments to give the function.
execute_delayed(delay, function, arguments=())[source]

Execute a function after a specified time.

  • delay – How many seconds to wait.
  • function – The function to call.
  • arguments – Arguments to give the function.
handlers = {}

Called when there is more data to read on connection sockets.

Parameters:sockets – A list of socket objects to be processed.

Run an infinite loop, processing data from connections.

This method repeatedly calls process_once().

Parameters:timeout – Parameter to pass to process_once.

Process data from connections once.

Parameters:timeout – How long the select() call should wait if no data is available.

This method should be called periodically to check and process incoming and outgoing data, if there is any.

It calls process_data(), _send_once() and process_timeout().

It will also examine when we last received data from the server; if it exceeds a specified time limit, the Session assumes that we have lost connection to the server and will attempt to reconnect us.

If calling it manually seems boring, look at the process_forever() method.


This is called to process any delayed commands that are registered to the Session object.

See also


register_socket(socket, conn)[source]

Internal method used to map the sockets on connection.Connection to the connections themselves.


Creates and returns a connection.ServerConnection object.

hanyuu.ircbot.irclib.session.event_handler(events, channels=[], nicks=[], modes=u'', regex=u'')[source]

The decorator for high level event handlers. By decorating a function with this, the function is registered in the global Session event handler list, Session.handlers.

  • events – The events that the handler should subscribe to. This can be both a string and a list; if a string is provided, it will be added as a single element in a list of events. This rule applies to channels and nicks as well.
  • channels – The channels that the events should trigger on. Given an empty list, all channels will trigger the event.
  • nicks – The nicknames that this handler should trigger for. Given an empty list, all nicknames will trigger the event.
  • modes – The required channel modes that are needed to trigger this event. If an empty mode string is specified, no modes are needed to trigger the event.
  • regex – The event will only be triggered if the HighEvent.message matches the specified regex. If no regex is specified, any HighEvent.message will do.
hanyuu.ircbot.irclib.session.high_level_events = [u'connect', u'text', u'join', u'part', u'kick', u'quit', u'mode', u'umode', u'topic', u'invite', u'ctcp', u'ctcpreply', u'action', u'nick', u'raw']

All the high level events that we can register to. Low level events that aren’t on this list can be registered to as well, but they will not be parsed.

tracker Module

Module that contains all the classes required to track channels, nicknames modes and other related stuff.

class hanyuu.ircbot.irclib.tracker.IRCTracker[source]

This class is used to track nicknames, channels, and the modes that are associated to nicknames on channels. It also tracks channel topics.

This tracker uses an internal Sqlite database to store its information.

add_mode(chan, nick, mode)[source]

Sets ‘mode’ on ‘nick’ in the channel ‘chan’.


Closes the Sqlite connection.


Executes a Sqlite query and returns the results.


Returns True if the tracker is familiar with the channel ‘chan’.

has_modes(chan, nick, modes, operator=u'and')[source]

Returns true if the nickname ‘nick’ has the modes ‘modes’ in the channel ‘chan’.

Based on the value of ‘operator’, the return value is different; if the operator is ‘and’, the nickname must have ALL of the specified modes. If the operator is ‘or’, the nickname must have ANY of the specified modes.


Returns True if the tracker is familiar with the nickname ‘nick’.

in_chan(chan, nick)[source]

Returns true if the nickname ‘nick’ is in the channel ‘chan’.

join(chan, nick)[source]

Tells the tracker that the nickname ‘nick’ joined ‘chan’.

nick(nick, newnick)[source]

Tells the tracker that the nickname ‘nick’ has changed to ‘newnick’.

part(chan, nick)[source]

Tells the tracker that the nickname ‘nick’ left ‘chan’.


Tells the tracker that the nickname ‘nick’ has left the server.

rem_mode(chan, nick, mode)[source]

Unsets ‘mode’ on ‘nick’ in the channel ‘chan’

topic(chan, topic=None)[source]

If ‘topic’ is None, this gets the topic in the channel ‘chan’.

Otherwise, the topic will be set to ‘topic’.

class hanyuu.ircbot.irclib.tracker.SqliteCursor(conn)[source]

A simple Sqlite cursor.

utils Module


Convert an IP number as an integer given in ASCII representation (e.g. ‘3232235521’) to an IP address string (e.g. ‘’).


Convert an IP address string (e.g. ‘’) to an IP number as an integer given in ASCII representation (e.g. ‘3232235521’).


Returns a lowercased string.

The definition of lowercased comes from the IRC specification (RFC 1459).

hanyuu.ircbot.irclib.utils.mask_matches(nick, mask)[source]

Check if a nick matches a mask.

Returns True if the nick matches, otherwise False.

hanyuu.ircbot.irclib.utils.nick_characters = u'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-[]\\`^{}'

The characters that are permitted in IRC nicknames


Get the host part of a nickmask.

(The source of an connection.Event is a nickmask.)


Get the nick part of a nickmask.

(The source of an connection.Event is a nickmask.)


Get the user part of a nickmask.

(The source of an connection.Event is a nickmask.)


Get the userhost part of a nickmask.

(The source of an connection.Event is a nickmask.)

Project Versions

Table Of Contents

Previous topic

ircbot Package

Next topic

listener Package

This Page