This library is intended to encapsulate the IRC protocol at a quite
low level. It provides an event-driven IRC client framework. It has
a fairly thorough support for the basic IRC protocol, CTCP and DCC
connections.

In order to understand how to make an IRC client, I’m afraid you more
or less must understand the IRC specifications. They are available
here:

Data is not written asynchronously to the server (and DCC peers),
i.e. the write() may block if the TCP buffers are stuffed.

Like most projects, documentation is lacking…

Unfortunately, this library isn’t as well-documented as I would like
it to be. I think the best way to get started is to read and
understand the example program irccat, which is included in the
distribution.

The following files might be of interest:

irc/client.py

The library itself. Read the code along with comments and
docstrings to get a grip of what it does. Use it at your own risk
and read the source, Luke!

irc/bot.py

An IRC bot implementation.

irc/server.py

A basic IRC server implementation. Suitable for testing, but not
production quality.

Examples

Example scripts in the scripts directory:

irccat

A simple example of how to use the IRC client. irccat reads text from
stdin and writes it to a specified user or channel on an IRC
server.

irccat2

The same as above, but using the SimpleIRCClient class.

servermap

Another simple example. servermap connects to an IRC server,
finds out what other IRC servers there are in the net and prints
a tree-like map of their interconnections.

testbot

An example bot that uses the SingleServerIRCBot class from
irc.bot. The bot enters a channel and listens for commands in
private messages or channel traffic. It also accepts DCC
invitations and echos back sent DCC chat messages.

dccreceive

Receives a file over DCC.

dccsend

Sends a file over DCC.

NOTE: If you’re running one of the examples on a unix command line, you need
to escape the # symbol in the channel. For example, use \#test or “#test”
instead of #test.

Decoding Input

By default, the IRC library does attempt to decode all incoming streams as
UTF-8, but the author acknowledges that there are cases where decoding is
undesirable or a custom decoding option is desirable. To support these cases,
since irc 3.4.2, the ServerConnection class may be customized. The
‘buffer_class’ attribute on the ServerConnection determines what class is used
for buffering lines from the input stream. By default it is
DecodingLineBuffer, but may be re-assigned with another class, such as irc
client.LineBuffer, which does not decode the lines and passes them through as
byte strings. The ‘buffer_class’ attribute may be assigned for all instances
of ServerConnection by overriding the class attribute:

irc.client.ServerConnection.buffer_class = irc.client.LineBuffer

or it may be overridden on a per-instance basis (as long as it’s overridden before the connection is established):

Notes and Contact Info

Changes

8.4

Code base now runs natively on Python 2 and Python 3, but requires six to be installed.

Issue #25: Rate-limiting has been updated to be finer grained (preventing
bursts exceeding the limit following idle periods).

8.3.2

Issue #22: Catch error in bot.py on NAMREPLY when nick is not in any visible
channel.

8.3.1

Fixed encoding errors in server on Python 3.

8.3

Added a set_keepalive method to the ServerConnection. Sends a periodic
PING message every indicated interval.

8.2

Added support for throttling send_raw messages via the ServerConnection
object. For example, on any connection object:

connection.set_rate_limit(30)

That would set the rate limit to 30 Hz (30 per second). Thanks to Jason
Kendall for the suggestion and bug fixes.

8.1.2

Fix typo in client.NickMask.

8.1.1

Fix typo in bot.py.

8.1

Issue #15: Added client support for ISUPPORT directives on server
connections. Now, each ServerConnection has a features attribute which
reflects the features supported by the server. See the docs for
irc.features for details about the implementation.

8.0.1

Issue #14: Fix errors when handlers of the same priority are added under
Python 3. This also fixes the unintended behavior of allowing handlers of
the same priority to compare as unequal.

8.0

This release brings several backward-incompatible changes to the scheduled
commands.

Refactored implementation of schedule classes. No longer do they override
the datetime constructor, but now only provide suitable classmethods for
construction in various forms.

Removed backward-compatible references from irc.client.

Remove ‘arguments’ parameter from scheduled commands.

Clients that reference the schedule classes from irc.client or that construct
them from the basic constructor will need to update to use the new class
methods:

Also, the parameter name when constructing an event was renamed from
eventtype to simply type.

4.0

Removed deprecated arguments to ServerConnection.connect. See notes on the
3.3 release on how to use the connect_factory parameter if your application
requires ssl, ipv6, or other connection customization.

3.6.1

Filter out disconnected sockets when processing input.

3.6

Created two new exceptions in irc.client: MessageTooLong and
InvalidCharacters.

Use explicit exceptions instead of ValueError when sending data.

3.5

SingleServerIRCBot now accepts keyword arguments which are passed through
to the ServerConnection.connect method. One can use this to use SSL for
connections:

3.4.2

3.4.1

3.4 never worked - the decoding customization feature was improperly
implemented and never tested.

The ServerConnection now allows custom classes to be supplied to customize
the decoding of incoming lines. For example, to disable the decoding of
incoming lines,
replace the buffer_class on the ServerConnection with a version that
passes through the lines directly:

irc.client.ServerConnection.buffer_class = irc.client.LineBuffer

This fixes #5.

3.4

Broken Release

3.3

Added connection module with a Factory for creating socket connections.

Added connect_factory parameter to the ServerConnection.

It’s now possible to create connections with custom SSL parameters or other
socket wrappers. For example, to create a connection with a custom SSL cert:

With this release, many of the parameters to ServerConnection.connect are
now deprecated:

localaddress

localport

ssl

ipv6

Instead, one should pass the appropriate values to a connection.Factory
instance and pass that factory to the .connect method. Backwards-compatibility
will be maintained for these parameters until the release of irc 4.0.

3.2.3

Restore Python 2.6 compatibility.

3.2.2

Protect from UnicodeDecodeError when decoding data on the wire when data is
not properly encoded in ASCII or UTF-8.

3.0

Issue #3541414 - The ServerConnection and DCCConnection now encode any
strings as UTF-8 before transmitting.

Issue #3527371 - Updated strings.FoldedCase to support comparison against
objects of other types.

Shutdown the sockets before closing.

Applications that are currently encoding unicode as UTF-8 before passing the
strings to ServerConnection.send_raw need to be updated to send Unicode
or ASCII.

2.0.4

This release officially deprecates 2.0.1-2.0.3 in favor of 3.0.

Re-release of irc 2.0 (without the changes from 2.0.1-2.0.3) for
correct compatibility indication.

2.0

DelayedCommands now use the local time for calculating ‘at’ and ‘due’
times. This will be more friendly for simple servers. Servers that expect
UTC times should either run in UTC or override DelayedCommand.now to
return an appropriate time object for ‘now’. For example:

1.1

Added irc.client.PeriodicCommandFixedDelay. Schedule this command
to have a function executed at a specific time and then at periodic
intervals thereafter.

1.0

Removed irclib and ircbot legacy modules.

0.9

Fix file saving using dccreceive.py on Windows. Fixes #2863199.

Created NickMask class from nm_to_* functions. Now if a source is
a NickMask, one can access the .nick, .host, and .user attributes.

Use correct attribute for saved connect args. Fixes #3523057.

0.8

Added ServerConnection.reconnect method. Fixes #3515580.

0.7.1

Added missing events. Fixes #3515578.

0.7

Moved functionality from irclib module to irc.client module.

Moved functionality from ircbot module to irc.bot module.

Retained irclib and ircbot modules for backward-compatibility. These
will be removed in 1.0.

Renamed project to simply ‘irc’.

To support the new module structure, simply replace references to the irclib
module with irc.client and ircbot module with irc.bot. This project will
support that interface through all versions of irc 1.x, so if you’ve made
these changes, you can safely depend on irc >= 0.7, <2.0dev.

0.6.3

Fixed failing test where DelayedCommands weren’t being sorted properly.
DelayedCommand a now subclass of the DateTime object, where the command’s
due time is the datetime. Fixed issue #3518508.

0.6.2

Fixed incorrect usage of Connection.execute_delayed (again).

0.6.0

Minimum Python requirement is now Python 2.6. Python 2.3 and earlier should use 0.5.0
or earlier.