agentirc 1.0.0__py3-none-any.whl

ircbot/bot.py

@@ -0,0 +1,279 @@
+"""Core IRC bot with event dispatch and command registry.
+
+This is the central piece: it ties the connection, protocol parser,
+and command system together. Subclass it or register commands on an
+instance -- both patterns work.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import textwrap
+from dataclasses import dataclass
+from typing import Callable, Awaitable
+
+from . import protocol
+from .config import BotConfig
+from .connection import IRCConnection
+
+log = logging.getLogger(__name__)
+
+
+# -- Command handler types --
+
+@dataclass(slots=True)
+class Command:
+    """A registered bot command."""
+
+    name: str
+    handler: Callable[[IRCBot, protocol.IRCMessage, str], Awaitable[None]]
+    help: str
+    aliases: list[str]
+
+
+# The handler signature:  async def handler(bot, message, args_str) -> None
+
+class IRCBot:
+    """Async IRC bot with a command registry and overridable event hooks.
+
+    Usage::
+
+        bot = IRCBot(config)
+        bot.command("ping", help="Check if the bot is alive")(ping_handler)
+        await bot.run()
+    """
+
+    def __init__(self, config: BotConfig) -> None:
+        self.config = config
+        self.nick = config.nick  # mutable -- may change on collision
+        self.conn = IRCConnection(
+            host=config.host,
+            port=config.port,
+            use_tls=config.use_tls,
+        )
+        self._commands: dict[str, Command] = {}
+        self._alias_map: dict[str, str] = {}  # alias -> canonical name
+
+    # -- Command registration --
+
+    def command(
+        self,
+        name: str,
+        *,
+        help: str = "",
+        aliases: list[str] | None = None,
+    ) -> Callable:
+        """Decorator to register a command.
+
+        The decorated function must have the signature::
+
+            async def handler(bot: IRCBot, msg: IRCMessage, args: str) -> None
+
+        ``args`` is the text after the command name, stripped.
+
+        Example::
+
+            @bot.command("greet", help="Say hello", aliases=["hi"])
+            async def greet(bot, msg, args):
+                await bot.reply(msg, f"Hello, {msg.nick}!")
+        """
+        aliases = aliases or []
+
+        def decorator(fn: Callable) -> Callable:
+            cmd = Command(name=name, handler=fn, help=help, aliases=aliases)
+            self._commands[name] = cmd
+            for alias in aliases:
+                self._alias_map[alias] = name
+            return fn
+
+        return decorator
+
+    def get_command(self, name: str) -> Command | None:
+        """Look up a command by name or alias."""
+        if name in self._commands:
+            return self._commands[name]
+        canonical = self._alias_map.get(name)
+        if canonical:
+            return self._commands.get(canonical)
+        return None
+
+    @property
+    def commands(self) -> dict[str, Command]:
+        """All registered commands (canonical names only)."""
+        return dict(self._commands)
+
+    # -- Convenience send helpers --
+
+    async def send(self, line: str) -> None:
+        """Send a raw IRC line."""
+        await self.conn.send(line)
+
+    @staticmethod
+    def _chop(text: str, width: int = 420) -> list[str]:
+        """Wrap text into lines under width, preserving word boundaries."""
+        result: list[str] = []
+        for line in text.splitlines():
+            if len(line) > width:
+                result.extend(textwrap.wrap(
+                    line,
+                    width=width,
+                    drop_whitespace=False,
+                    replace_whitespace=False,
+                    fix_sentence_endings=True,
+                    break_long_words=False,
+                ))
+            else:
+                result.append(line)
+        return result
+
+    async def privmsg(self, target: str, text: str) -> None:
+        """Send a PRIVMSG, chopping long lines at word boundaries."""
+        lines = self._chop(text)
+        for i, line in enumerate(lines):
+            await self.send(f"PRIVMSG {target} :{line}")
+            if i < len(lines) - 1:
+                await asyncio.sleep(1)
+
+    async def notice(self, target: str, text: str) -> None:
+        """Send a NOTICE, chopping long lines at word boundaries."""
+        lines = self._chop(text)
+        for i, line in enumerate(lines):
+            await self.send(f"NOTICE {target} :{line}")
+            if i < len(lines) - 1:
+                await asyncio.sleep(1)
+
+    async def reply(self, msg: protocol.IRCMessage, text: str) -> None:
+        """Reply in the appropriate context (channel or DM)."""
+        await self.privmsg(msg.reply_target, text)
+
+    async def join(self, channel: str) -> None:
+        await self.send(f"JOIN {channel}")
+
+    async def part(self, channel: str, reason: str = "Leaving") -> None:
+        await self.send(f"PART {channel} :{reason}")
+
+    async def quit(self, reason: str = "Bye") -> None:
+        await self.send(f"QUIT :{reason}")
+
+    # -- Connection lifecycle --
+
+    async def run(self) -> None:
+        """Start the bot (blocks until cancelled)."""
+        log.info("Starting bot as %s", self.config.nick)
+        await self.conn.run_forever(
+            on_connect=self._on_connect,
+            on_line=self._on_line,
+        )
+
+    async def _on_connect(self) -> None:
+        """Send registration commands after TCP connect."""
+        if self.config.password:
+            await self.send(f"PASS {self.config.password}")
+
+        self.nick = self.config.nick  # reset nick on reconnect
+        await self.send(f"NICK {self.nick}")
+        await self.send(f"USER {self.config.user} 0 * :{self.config.realname}")
+
+    # -- IRC line dispatch --
+
+    async def _on_line(self, raw: str) -> None:
+        """Parse and dispatch a single IRC line."""
+        msg = protocol.parse(raw)
+        await self._dispatch(msg)
+
+    async def _dispatch(self, msg: protocol.IRCMessage) -> None:
+        """Route a parsed message to the appropriate handler."""
+
+        if msg.command == "PING":
+            await self.send(f"PONG :{msg.text}")
+
+        elif msg.command == "001":  # RPL_WELCOME
+            await self.on_welcome(msg)
+
+        elif msg.command == "PRIVMSG":
+            await self.on_privmsg(msg)
+
+        elif msg.command == "JOIN":
+            await self.on_join(msg)
+
+        elif msg.command == "PART":
+            await self.on_part(msg)
+
+        elif msg.command == "KICK":
+            await self.on_kick(msg)
+
+        elif msg.command in ("433", "432"):
+            # Nick in use or erroneous -- try with underscore suffix
+            self.nick += "_"
+            await self.send(f"NICK {self.nick}")
+            log.warning("Nick collision, trying %s", self.nick)
+
+        # Let subclasses handle arbitrary commands
+        handler = getattr(self, f"on_raw_{msg.command.lower()}", None)
+        if handler is not None:
+            await handler(msg)
+
+    # -- Event hooks (override in subclasses) --
+
+    async def on_welcome(self, msg: protocol.IRCMessage) -> None:
+        """Called after successful registration (numeric 001)."""
+        log.info("Registered as %s", self.nick)
+        for channel in self.config.channels:
+            await self.join(channel)
+
+    async def on_privmsg(self, msg: protocol.IRCMessage) -> None:
+        """Called on every PRIVMSG. Dispatches commands automatically."""
+        await self._try_command(msg)
+
+    async def on_join(self, msg: protocol.IRCMessage) -> None:
+        """Called when someone (including the bot) joins a channel."""
+        log.debug("%s joined %s", msg.nick, msg.target)
+
+    async def on_part(self, msg: protocol.IRCMessage) -> None:
+        """Called when someone parts a channel."""
+        reason = msg.text if len(msg.params) > 1 else ""
+        log.debug("%s left %s (%s)", msg.nick, msg.target, reason)
+
+    async def on_kick(self, msg: protocol.IRCMessage) -> None:
+        """Called when someone is kicked. Auto-rejoins if it is the bot."""
+        kicked = msg.params[1] if len(msg.params) > 1 else ""
+        reason = msg.text if len(msg.params) > 2 else ""
+        log.debug("%s kicked from %s (%s)", kicked, msg.target, reason)
+        if kicked == self.nick:
+            await asyncio.sleep(5)
+            await self.join(msg.target)
+
+    # -- Command dispatch --
+
+    async def _try_command(self, msg: protocol.IRCMessage) -> None:
+        """Check if a PRIVMSG is a bot command and dispatch it."""
+        text = msg.text.strip()
+        prefix = self.config.command_prefix
+
+        if not text.startswith(prefix):
+            return
+
+        # Split "!ping some args" -> ("ping", "some args")
+        without_prefix = text[len(prefix):]
+        parts = without_prefix.split(None, 1)
+        if not parts:
+            return
+
+        cmd_name = parts[0].lower()
+        args = parts[1] if len(parts) > 1 else ""
+
+        cmd = self.get_command(cmd_name)
+        if cmd is None:
+            return
+
+        if args:
+            log.info("command [%s] <%s> %s %s", msg.reply_target, msg.nick, cmd.name, args)
+        else:
+            log.info("command [%s] <%s> %s", msg.reply_target, msg.nick, cmd.name)
+
+        try:
+            await cmd.handler(self, msg, args)
+        except Exception:
+            log.exception("Error in command '%s'", cmd_name)
+            await self.reply(msg, f"Error running command '{cmd_name}'.")

ircbot/commands.py

@@ -0,0 +1,52 @@
+"""Built-in bot commands.
+
+Each command is a plain async function with the signature:
+    async def handler(bot: IRCBot, msg: IRCMessage, args: str) -> None
+
+Call register_builtins(bot) to wire them up.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .bot import IRCBot
+    from .protocol import IRCMessage
+
+
+async def cmd_ping(bot: IRCBot, msg: IRCMessage, _args: str) -> None:
+    """Check if the bot is alive."""
+    await bot.reply(msg, f"{msg.nick}: pong!")
+
+
+async def cmd_time(bot: IRCBot, msg: IRCMessage, _args: str) -> None:
+    """Show the current UTC time."""
+    now = time.strftime("%Y-%m-%d %H:%M:%S", time.gmtime())
+    await bot.reply(msg, f"UTC: {now}")
+
+
+async def cmd_help(bot: IRCBot, msg: IRCMessage, args: str) -> None:
+    """List available commands or show help for a specific command."""
+    prefix = bot.config.command_prefix
+
+    if args:
+        cmd = bot.get_command(args.lower())
+        if cmd:
+            alias_str = f" (aliases: {', '.join(cmd.aliases)})" if cmd.aliases else ""
+            await bot.reply(msg, f"{prefix}{cmd.name}{alias_str} -- {cmd.help or 'No description.'}")
+        else:
+            await bot.reply(msg, f"Unknown command: {args}")
+        return
+
+    names = sorted(bot.commands.keys())
+    await bot.reply(msg, f"Commands: {', '.join(prefix + n for n in names)}")
+    await bot.reply(msg, f"Use {prefix}help <command> for details.")
+
+
+def register_builtins(bot: IRCBot) -> None:
+    """Register all built-in commands on a bot instance."""
+    bot.command("ping", help="Check if the bot is alive")(cmd_ping)
+    bot.command("time", help="Show current UTC time")(cmd_time)
+    bot.command("help", help="List commands or get help for one", aliases=["h"])(cmd_help)

ircbot/config.py

@@ -0,0 +1,64 @@
+"""Configuration loading from environment variables and .env files.
+
+Provides a typed dataclass instead of a raw dict.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+def load_env(path: str = ".env") -> None:
+    """Load key=value pairs from a .env file into os.environ.
+
+    Uses setdefault so real environment variables always win.
+    Skips blank lines and comments (#).
+    Handles quoted values (single or double quotes).
+    """
+    p = Path(path)
+    if not p.exists():
+        return
+    for line in p.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
+            value = value[1:-1]
+        os.environ.setdefault(key, value)
+
+
+@dataclass(frozen=True, slots=True)
+class BotConfig:
+    """Typed, immutable bot configuration."""
+
+    host: str
+    port: int
+    nick: str
+    user: str
+    realname: str
+    channels: list[str] = field(default_factory=list)
+    password: str = ""
+    use_tls: bool = False
+    command_prefix: str = "!"
+
+    @classmethod
+    def from_env(cls) -> BotConfig:
+        """Build config from environment variables (IRC_HOST, IRC_PORT, etc.)."""
+        nick = os.environ["IRC_NICK"]
+        channels_raw = os.environ.get("IRC_CHANNELS", "")
+        return cls(
+            host=os.environ["IRC_HOST"],
+            port=int(os.environ.get("IRC_PORT", "6667")),
+            nick=nick,
+            user=os.environ.get("IRC_USER", nick),
+            realname=os.environ.get("IRC_REALNAME", "IRC Bot"),
+            channels=[c.strip() for c in channels_raw.split(",") if c.strip()],
+            password=os.environ.get("IRC_PASSWORD", ""),
+            use_tls=os.environ.get("IRC_USE_TLS", "false").lower() in ("1", "true", "yes"),
+            command_prefix=os.environ.get("IRC_CMD_PREFIX", "!"),
+        )

ircbot/connection.py

@@ -0,0 +1,133 @@
+"""Async IRC connection with automatic reconnect and exponential backoff.
+
+Owns the TCP socket lifecycle. Knows nothing about IRC semantics beyond
+sending/receiving raw lines.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import ssl
+from collections.abc import AsyncGenerator
+from typing import Callable, Awaitable
+
+log = logging.getLogger(__name__)
+
+# Backoff parameters
+_BACKOFF_BASE = 5
+_BACKOFF_MAX = 300
+_BACKOFF_MULTIPLIER = 2
+
+
+class IRCConnection:
+    """Manages an async TCP connection to an IRC server."""
+
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        use_tls: bool = False,
+        encoding: str = "utf-8",
+    ) -> None:
+        self.host = host
+        self.port = port
+        self.use_tls = use_tls
+        self.encoding = encoding
+
+        self._reader: asyncio.StreamReader | None = None
+        self._writer: asyncio.StreamWriter | None = None
+        self._connected = False
+
+    @property
+    def connected(self) -> bool:
+        return self._connected
+
+    # -- connect / disconnect --
+
+    async def connect(self) -> None:
+        """Open the TCP connection."""
+        ssl_ctx: ssl.SSLContext | None = None
+        if self.use_tls:
+            ssl_ctx = ssl.create_default_context()
+
+        self._reader, self._writer = await asyncio.open_connection(
+            self.host, self.port, ssl=ssl_ctx,
+        )
+        self._connected = True
+        log.info("Connected to %s:%d (tls=%s)", self.host, self.port, self.use_tls)
+
+    async def disconnect(self) -> None:
+        """Close the TCP connection gracefully."""
+        self._connected = False
+        if self._writer is not None:
+            try:
+                self._writer.close()
+                await self._writer.wait_closed()
+            except OSError:
+                pass
+            self._writer = None
+        self._reader = None
+        log.info("Disconnected")
+
+    # -- send / receive --
+
+    async def send(self, line: str) -> None:
+        """Send a single IRC line (appends CRLF)."""
+        if self._writer is None:
+            log.warning("send() called while disconnected: %s", line)
+            return
+        data = (line + "\r\n").encode(self.encoding)
+        self._writer.write(data)
+        await self._writer.drain()
+        log.debug(">> %s", line)
+
+    async def read_lines(self) -> AsyncGenerator[str, None]:
+        """Yield decoded IRC lines until the connection drops."""
+        if self._reader is None:
+            raise RuntimeError("read_lines() called before connect()")
+        while self._connected:
+            try:
+                raw = await self._reader.readline()
+            except (ConnectionResetError, asyncio.IncompleteReadError, OSError):
+                break
+            if not raw:
+                break
+            line = raw.decode(self.encoding, errors="replace").rstrip("\r\n")
+            log.debug("<< %s", line)
+            yield line
+        self._connected = False
+
+    # -- reconnect loop --
+
+    async def run_forever(
+        self,
+        on_connect: Callable[[], Awaitable[None]],
+        on_line: Callable[[str], Awaitable[None]],
+    ) -> None:
+        """Connect, read lines, and reconnect on failure with exponential backoff.
+
+        Args:
+            on_connect: Called after each successful TCP connect (send NICK/USER here).
+            on_line: Called for every raw IRC line received.
+        """
+        backoff = _BACKOFF_BASE
+
+        while True:
+            try:
+                await self.connect()
+                backoff = _BACKOFF_BASE  # reset on successful connect
+                await on_connect()
+
+                async for line in self.read_lines():
+                    await on_line(line)
+
+            except (ConnectionResetError, OSError) as exc:
+                log.warning("Connection error: %s", exc)
+
+            finally:
+                await self.disconnect()
+
+            log.info("Reconnecting in %ds...", backoff)
+            await asyncio.sleep(backoff)
+            backoff = min(backoff * _BACKOFF_MULTIPLIER, _BACKOFF_MAX)

ircbot/protocol.py

@@ -0,0 +1,109 @@
+"""IRC protocol message parsing.
+
+Stateless functions that turn raw IRC lines into structured data.
+Follows RFC 2812 message format: [:prefix] command params... [:trailing]
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class IRCMessage:
+    """A parsed IRC protocol message."""
+
+    raw: str
+    prefix: str
+    nick: str
+    user: str
+    host: str
+    command: str
+    params: list[str]
+
+    @property
+    def target(self) -> str:
+        """First param -- typically a channel or nick."""
+        return self.params[0] if self.params else ""
+
+    @property
+    def text(self) -> str:
+        """Trailing param (the human-readable body of PRIVMSG, NOTICE, etc.)."""
+        return self.params[-1] if self.params else ""
+
+    @property
+    def is_channel(self) -> bool:
+        """Whether the target is a channel (starts with # or &)."""
+        return bool(self.target) and self.target[0] in "#&!+"
+
+    @property
+    def reply_target(self) -> str:
+        """Where to send a reply: the channel if public, the sender's nick if private."""
+        return self.target if self.is_channel else self.nick
+
+
+def parse_prefix(prefix: str) -> tuple[str, str, str]:
+    """Split a prefix into (nick, user, host).
+
+    Handles both 'nick!user@host' and plain server names.
+    """
+    nick = prefix
+    user = ""
+    host = ""
+
+    if "!" in prefix:
+        nick, _, rest = prefix.partition("!")
+        user, _, host = rest.partition("@")
+    elif "@" in prefix:
+        nick, _, host = prefix.partition("@")
+
+    return nick, user, host
+
+
+def parse(line: str) -> IRCMessage:
+    """Parse a raw IRC line into an IRCMessage.
+
+    Handles the full RFC 2812 format:
+        [:prefix SPACE] command [params] [:trailing]
+    """
+    raw = line
+    prefix = ""
+    remaining = line
+
+    # Extract prefix
+    if remaining.startswith(":"):
+        prefix, _, remaining = remaining[1:].partition(" ")
+
+    # Extract command
+    if " " in remaining:
+        command, _, remaining = remaining.partition(" ")
+    else:
+        command = remaining
+        remaining = ""
+
+    command = command.upper()
+
+    # Extract params
+    params: list[str] = []
+    while remaining:
+        if remaining.startswith(":"):
+            params.append(remaining[1:])
+            break
+        if " " in remaining:
+            param, _, remaining = remaining.partition(" ")
+            params.append(param)
+        else:
+            params.append(remaining)
+            break
+
+    nick, user, host = parse_prefix(prefix)
+
+    return IRCMessage(
+        raw=raw,
+        prefix=prefix,
+        nick=nick,
+        user=user,
+        host=host,
+        command=command,
+        params=params,
+    )