tessl/pypi-irc

IRC (Internet Relay Chat) protocol library for Python

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

IRC

Name: tessl/pypi-irc
Author: tessl

A comprehensive Python library for Internet Relay Chat (IRC) protocol implementation. The IRC package provides both synchronous and asynchronous client implementations with full event-driven architecture, enabling developers to create IRC clients, bots, and servers with support for modern IRC features including IRCv3, CTCP, DCC, and server capabilities detection.

Package Information

Package Name: irc
Language: Python
Installation: pip install irc

Core Imports

import irc.client
import irc.bot

For synchronous IRC clients:

from irc.client import Reactor, SimpleIRCClient, ServerConnection

For asynchronous IRC clients:

from irc.client_aio import AioReactor, AioSimpleIRCClient, AioConnection

For bot framework:

from irc.bot import SingleServerIRCBot, ServerSpec

Basic Usage

Simple IRC Client

import irc.client

def on_connect(connection, event):
    connection.join("#test")

def on_join(connection, event):
    connection.privmsg("#test", "Hello IRC!")

def on_pubmsg(connection, event):
    print(f"<{event.source.nick}> {event.arguments[0]}")

client = irc.client.SimpleIRCClient()
client.connect("irc.libera.chat", 6667, "mybot")
client.connection.add_global_handler("welcome", on_connect)
client.connection.add_global_handler("join", on_join)
client.connection.add_global_handler("pubmsg", on_pubmsg)
client.start()

IRC Bot

from irc.bot import SingleServerIRCBot

class TestBot(SingleServerIRCBot):
    def __init__(self, channels, nickname, server, port=6667):
        spec = [{"host": server, "port": port}]
        super().__init__(spec, nickname, nickname)
        self.channels = channels

    def on_welcome(self, connection, event):
        for channel in self.channels:
            connection.join(channel)

    def on_pubmsg(self, connection, event):
        message = event.arguments[0]
        if message.startswith("!hello"):
            connection.privmsg(event.target, f"Hello {event.source.nick}!")

bot = TestBot(["#test"], "mybot", "irc.libera.chat")
bot.start()

Asyncio IRC Client

import asyncio
from irc.client_aio import AioSimpleIRCClient

async def main():
    client = AioSimpleIRCClient()
    
    def on_connect(connection, event):
        connection.join("#test")
    
    def on_pubmsg(connection, event):
        print(f"<{event.source.nick}> {event.arguments[0]}")
    
    client.connection.add_global_handler("welcome", on_connect)
    client.connection.add_global_handler("pubmsg", on_pubmsg)
    
    await client.connect("irc.libera.chat", 6667, "mybot")
    # Client runs in background, process events as needed

asyncio.run(main())

Architecture

The IRC package follows an event-driven architecture with these core components:

Reactor: Central event loop managing connections and dispatching events
ServerConnection: Individual IRC server connection handling protocol communication
Event System: Comprehensive event handling with prioritized handlers
Bot Framework: High-level abstractions for building IRC bots with channel management
Protocol Support: CTCP, DCC, IRCv3 features, and server capability detection

The library supports both traditional callback-based programming and modern asyncio/await patterns, making it suitable for both simple scripts and complex applications.

Capabilities

Synchronous IRC Client

Core IRC client functionality using traditional socket connections with select-based event processing. Provides ServerConnection for protocol communication and Reactor for event management.

class Reactor:
    def __init__(self, on_connect=None, on_disconnect=None): ...
    def server(self) -> ServerConnection: ...
    def process_forever(self, timeout=0.2): ...
    def add_global_handler(self, event: str, handler, priority: int = 0): ...

class ServerConnection:
    def connect(self, server: str, port: int, nickname: str, password: str = None, 
                username: str = None, ircname: str = None, **kwargs): ...
    def join(self, channel: str, key: str = ""): ...
    def privmsg(self, target: str, text: str): ...
    def quit(self, message: str = ""): ...

class SimpleIRCClient:
    def connect(self, server: str, port: int, nickname: str, **kwargs): ...
    def start(self): ...

Synchronous Client

Asynchronous IRC Client

Asyncio-based IRC client implementation providing full async/await support for modern Python applications. Uses asyncio protocols for non-blocking network communication.

class AioReactor:
    def __init__(self, on_connect=None, on_disconnect=None, loop=None): ...
    def server(self) -> AioConnection: ...
    async def process_forever(self): ...

class AioConnection:
    async def connect(self, server: str, port: int, nickname: str, **kwargs): ...
    def join(self, channel: str, key: str = ""): ...
    def privmsg(self, target: str, text: str): ...

class AioSimpleIRCClient:
    async def connect(self, server: str, port: int, nickname: str, **kwargs): ...

Asynchronous Client

Bot Framework

High-level IRC bot framework with automatic reconnection, channel management, and common bot functionality. Provides SingleServerIRCBot base class for easy bot development.

class SingleServerIRCBot:
    def __init__(self, server_list, nickname: str, realname: str, **kwargs): ...
    def start(self): ...
    def die(self, msg: str = "Bye, cruel world!"): ...
    def jump_server(self, msg: str = "Changing servers"): ...

class Channel:
    def users(self) -> list: ...
    def is_oper(self, nick: str) -> bool: ...
    def is_voiced(self, nick: str) -> bool: ...
    def set_mode(self, mode: str, value=None): ...

class ServerSpec:
    def __init__(self, host: str, port: int = 6667, password: str = None): ...

Bot Framework

Event System

Comprehensive event handling system supporting all IRC protocol events, custom handlers with priorities, and extensible event processing for advanced applications.

class Event:
    def __init__(self, type: str, source, target, arguments: list = None, tags: list = None): ...
    
def add_global_handler(event: str, handler, priority: int = 0): ...
def remove_global_handler(event: str, handler): ...

# Event types available
protocol_events = [
    "error", "join", "kick", "mode", "part", "ping", "privmsg", 
    "privnotice", "pubmsg", "pubnotice", "quit", "invite", "pong", 
    "action", "topic", "nick"
]

Event System

Protocol Extensions

Support for IRC protocol extensions including CTCP (Client-To-Client Protocol), DCC (Direct Client-to-Client), IRCv3 message tags, and server capability detection.

# CTCP support
def dequote(message: str) -> list: ...

# DCC connections
class DCCConnection:
    def connect(self, address: tuple, port: int): ...
    def listen(self, addr=None): ...
    def send_bytes(self, bytes: bytes): ...

# Server features
class FeatureSet:
    def set(self, name: str, value=True): ...
    def load(self, arguments: list): ...

Protocol Extensions

Connection Management

Connection factories, SSL support, IPv6 compatibility, rate limiting, and automatic ping/pong handling for robust IRC connections.

class Factory:
    def __init__(self, bind_address=None, wrapper=None, ipv6: bool = False): ...
    def connect(self, server_address: tuple): ...

def set_rate_limit(self, frequency: float): ...
def set_keepalive(self, interval: int): ...

Connection Management

Utilities and Helpers

IRC-specific string handling, nickname parsing, channel detection, mode parsing, and scheduling utilities for IRC applications.

class NickMask:
    @property
    def nick(self) -> str: ...
    @property
    def user(self) -> str: ...
    @property
    def host(self) -> str: ...

def is_channel(string: str) -> bool: ...
def parse_nick_modes(mode_string: str) -> list: ...
def parse_channel_modes(mode_string: str) -> list: ...

class IRCDict(dict):
    # Case-insensitive dictionary using IRC rules
    pass

class DefaultScheduler:
    def execute_every(self, period, func): ...
    def execute_at(self, when, func): ...
    def execute_after(self, delay, func): ...

Utilities

Types

class IRCError(Exception):
    """Base IRC exception class."""
    pass

class ServerConnectionError(IRCError):
    """Server connection error."""
    pass

class ServerNotConnectedError(ServerConnectionError):
    """Server not connected error."""
    pass

class InvalidCharacters(ValueError):
    """Invalid characters in IRC message."""
    pass

class MessageTooLong(ValueError):
    """IRC message exceeds length limits."""
    pass

class DCCConnectionError(IRCError):
    """DCC connection error."""
    pass

class PrioritizedHandler:
    priority: int
    callback: callable

class Event:
    type: str
    source: NickMask
    target: str
    arguments: list
    tags: list