Skip to main content

IRC (Internet Relay Chat) protocol library for Python

Project description

https://img.shields.io/pypi/v/irc.svg https://img.shields.io/pypi/pyversions/irc.svg tests Ruff https://readthedocs.org/projects/irc/badge/?version=latest https://img.shields.io/badge/skeleton-2024-informational Join the chat at https://gitter.im/jaraco/irc https://tidelift.com/badges/github/jaraco/irc

Full-featured Python IRC library for Python.

Overview

This library provides a low-level implementation of the IRC protocol for Python. 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, it’s best to read up first on the IRC specifications.

Client Features

The main features of the IRC client framework are:

  • Abstraction of the IRC protocol.

  • Handles multiple simultaneous IRC server connections.

  • Handles server PONGing transparently.

  • Messages to the IRC server are done by calling methods on an IRC connection object.

  • Messages from an IRC server triggers events, which can be caught by event handlers.

  • Multiple options for reading from and writing to an IRC server: you can use sockets in an internal select() loop OR use Python3’s asyncio event loop

  • Functions can be registered to execute at specified times by the event-loop.

  • Decodes CTCP tagging correctly (hopefully); I haven’t seen any other IRC client implementation that handles the CTCP specification subtleties.

  • A kind of simple, single-server, object-oriented IRC client class that dispatches events to instance methods is included.

  • DCC connection support.

Current limitations:

  • The IRC protocol shines through the abstraction a bit too much.

  • 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 …

  • DCC is not currently implemented in the asyncio-based version

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 modules might be of interest:

  • irc.client

    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.client_aio

    All the functionality of the above library, but utilizing Python 3’s native asyncio library for the core event loop. Interface/API is otherwise functionally identical to the classes in irc.client

  • irc.bot

    An IRC bot implementation.

  • irc.server

    A basic IRC server implementation. Suitable for testing, but not intended as a production service.

    Invoke the server with python -m irc.server.

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.

  • aio_irccat

    Same as above, but uses the asyncio-based event loop in AioReactor instead of the select() based Reactor.

  • aio_irccat2

    Same as above, but using the AioSimpleIRCClient 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.

Scheduling Events

The library includes a default event Scheduler as irc.schedule.DefaultScheduler, but this scheduler can be replaced with any other scheduler. For example, to use the schedule package, include it in your dependencies and install it into the IRC library as so:

class ScheduleScheduler(irc.schedule.IScheduler):
def execute_every(self, period, func):

schedule.every(period).do(func)

def execute_at(self, when, func):

schedule.at(when).do(func)

def execute_after(self, delay, func):

raise NotImplementedError(“Not supported”)

def run_pending(self):

schedule.run_pending()

irc.client.Reactor.scheduler_class = ScheduleScheduler

Decoding Input

By default, the IRC library attempts to decode all incoming streams as UTF-8, even though the IRC spec stipulates that no specific encoding can be expected. Since assuming UTF-8 is not reasonable in the general case, the IRC library provides options to customize decoding of input by customizing the ServerConnection class. The buffer_class attribute on the ServerConnection determines which class is used for buffering lines from the input stream, using the buffer module in jaraco.stream. By default it is buffer.DecodingLineBuffer, but may be re-assigned with another class, following the interface of buffer.LineBuffer. The buffer_class attribute may be assigned for all instances of ServerConnection by overriding the class attribute.

For example:

from jaraco.stream import buffer

irc.client.ServerConnection.buffer_class = buffer.LenientDecodingLineBuffer

The LenientDecodingLineBuffer attempts UTF-8 but falls back to latin-1, which will avoid UnicodeDecodeError in all cases (but may produce unexpected behavior if an IRC user is using another encoding).

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

server = irc.client.Reactor().server()
server.buffer_class = buffer.LenientDecodingLineBuffer
server.connect()

Alternatively, some clients may still want to decode the input using a different encoding. To decode all input as latin-1 (which decodes any input), use the following:

irc.client.ServerConnection.buffer_class.encoding = "latin-1"

Or decode to UTF-8, but use a replacement character for unrecognized byte sequences:

irc.client.ServerConnection.buffer_class.errors = "replace"

Or, to simply ignore all input that cannot be decoded:

class IgnoreErrorsBuffer(buffer.DecodingLineBuffer):
    def handle_exception(self):
        pass


irc.client.ServerConnection.buffer_class = IgnoreErrorsBuffer

The library requires text for message processing, so a decoding buffer must be used. Clients must use one of the above techniques for decoding input to text.

Notes and Contact Info

Enjoy.

Maintainer: Jason R. Coombs <jaraco@jaraco.com>

Original Author: Joel Rosdahl <joel@rosdahl.net>

Copyright © 1999-2002 Joel Rosdahl Copyright © 2011-2016 Jason R. Coombs Copyright © 2009 Ferry Boender

For Enterprise

Available as part of the Tidelift Subscription.

This project and the maintainers of thousands of other packages are working with Tidelift to deliver one enterprise subscription that covers all of the open source you use.

Learn more.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

irc-20.5.0.tar.gz (92.2 kB view details)

Uploaded Source

Built Distribution

irc-20.5.0-py3-none-any.whl (75.5 kB view details)

Uploaded Python 3

File details

Details for the file irc-20.5.0.tar.gz.

File metadata

  • Download URL: irc-20.5.0.tar.gz
  • Upload date:
  • Size: 92.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.4

File hashes

Hashes for irc-20.5.0.tar.gz
Algorithm Hash digest
SHA256 8ddbfd19f71204ceceba7b7c72724b15b3fa87bab5e81e45a75bef736a1a3c76
MD5 7be2d8bec815a2e5693bfbc6ba4f54ad
BLAKE2b-256 0dc05b875df761bfbf51482bab7ddb4b9f9968327bc08801f5ac9599ab451824

See more details on using hashes here.

File details

Details for the file irc-20.5.0-py3-none-any.whl.

File metadata

  • Download URL: irc-20.5.0-py3-none-any.whl
  • Upload date:
  • Size: 75.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.4

File hashes

Hashes for irc-20.5.0-py3-none-any.whl
Algorithm Hash digest
SHA256 712c6065c41ceaf75c874d623b02edaa5e6c7d605532da81c52d39629a8e9fd0
MD5 4f68ae011608eaa4d47379bee2d8fb57
BLAKE2b-256 117093034515cfc18e2020146f889c82abb38a01c7d77b50bc033f91bc5c12b9

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page