pinhook 1.11.0__py3-none-any.whl

pinhook/__version__.py

@@ -0,0 +1 @@
+__version__ = '1.11.0'

pinhook/bans.py

@@ -0,0 +1,56 @@
+import fnmatch
+import json
+import os
+
+import irc.strings
+
+# ban and op entries can be one of:
+#   a nick                  troll
+#   a hostmask              *!*@203.0.113.7  (* and ? are wildcards)
+#   a services account      $a:troll
+
+
+def is_account(entry):
+    return entry.startswith('$a:')
+
+
+def is_mask(entry):
+    return '!' in entry or '@' in entry
+
+
+def matches(entry, nick, user=None, host=None, account=None):
+    # irc lowercasing also turns [ ] into { }, so nicks can't break the wildcard match
+    entry = irc.strings.lower(entry)
+    if is_account(entry):
+        return bool(account) and irc.strings.lower(account) == entry[len('$a:'):]
+    if is_mask(entry):
+        mask = irc.strings.lower('{}!{}@{}'.format(nick, user or '', host or ''))
+        return fnmatch.fnmatchcase(mask, entry)
+    return irc.strings.lower(nick) == entry
+
+
+def matches_any(entries, nick, user=None, host=None, account=None):
+    return any(matches(e, nick, user, host, account) for e in entries)
+
+
+def load(path):
+    if not path or not os.path.exists(path):
+        return []
+    with open(path) as f:
+        try:
+            entries = json.load(f)
+        except ValueError as e:
+            raise ValueError("couldn't read ban file {}: {}".format(path, e))
+    if not isinstance(entries, list) or not all(isinstance(e, str) for e in entries):
+        raise ValueError('ban file {} should be a list of ban entries'.format(path))
+    return entries
+
+
+def save(path, entries):
+    if not path:
+        return
+    # write to a temp file first so a crash can't leave a half written ban file
+    tmp = path + '.tmp'
+    with open(tmp, 'w') as f:
+        json.dump(entries, f, indent=2)
+    os.replace(tmp, path)

pinhook/bot.py

@@ -0,0 +1,578 @@
+from collections import OrderedDict
+from datetime import datetime, timezone
+import difflib
+import functools
+import logging
+import socket
+import ssl
+import sys
+import time
+
+from . import bans
+from . import log
+from . import plugin
+
+import irc.bot
+
+
+irc.client.ServerConnection.buffer_class.errors = 'replace'
+
+
+class Bot(irc.bot.SingleServerIRCBot):
+    internal_commands = {
+        'join': 'join a channel',
+        'quit': 'force the bot to quit',
+        'reload': 'force bot to reload all plugins',
+        'enable': 'enable a plugin',
+        'disable': 'disable a plugin',
+        'op': 'add a user as bot operator',
+        'deop': 'remove a user as bot operator',
+        'ops': 'list all ops',
+        'ban': 'ban a user from using the bot, by account or host when possible',
+        'unban': 'remove bot ban for user',
+        'banlist': 'list current bans'
+    }
+    # keyword options Bot understands, subclasses can add their own
+    options = {
+        'port', 'ops', 'plugin_dir', 'ssl_required', 'ssl_verify', 'ns_pass',
+        'nickserv', 'log_level', 'log_file', 'server_pass', 'cmd_prefix',
+        'use_prefix_for_plugins', 'disable_help', 'banned_users', 'bot_mode',
+        'ban_file', 'require_account',
+    }
+    log_levels = {
+        'critical': logging.CRITICAL,
+        'error': logging.ERROR,
+        'warning': logging.WARNING,
+        'warn': logging.WARNING,
+        'info': logging.INFO,
+        'debug': logging.DEBUG,
+    }
+    # set once the server agrees to tag messages with the sender's account
+    account_tag = False
+    _negotiating_caps = False
+
+    def __init__(self, channels, nickname, server, **kwargs):
+        self.port = kwargs.get('port', 6667)
+        self.ops = kwargs.get('ops', [])
+        self.plugin_dir = kwargs.get('plugin_dir', 'plugins')
+        self.ssl_required = kwargs.get('ssl_required', False)
+        self.ssl_verify = kwargs.get('ssl_verify', True)
+        self.ns_pass = kwargs.get('ns_pass', None)
+        self.nickserv = kwargs.get('nickserv', 'NickServ')
+        self.log_level = kwargs.get('log_level', 'info')
+        self.log_file = kwargs.get('log_file', None)
+        self.server_pass = kwargs.get('server_pass', None)
+        self.cmd_prefix = kwargs.get('cmd_prefix', '!')
+        self.use_prefix_for_plugins = kwargs.get('use_prefix_for_plugins', False)
+        self.disable_help = kwargs.get('disable_help', False)
+        self.bot_mode = kwargs.get('bot_mode', True)
+        self.require_account = kwargs.get('require_account', False)
+        factory = self.ssl_factory(server) if self.ssl_required else irc.connection.Factory()
+        irc.bot.SingleServerIRCBot.__init__(self, [(server, self.port, self.server_pass)], nickname, nickname, connect_factory=self.cap_factory(factory))
+        self.chanlist = channels
+        self.bot_nick = nickname
+        self.start_logging()
+        self.warn_unknown_options(kwargs)
+        self.setup_bans(nickname, kwargs)
+        self.internal_commands = {self.cmd_prefix + k: v for k,v in self.internal_commands.items()}
+        plugin.load_plugins(self.plugin_dir, use_prefix=self.use_prefix_for_plugins, cmd_prefix=self.cmd_prefix, logger=self.logger)
+
+    class Message:
+        def __init__(self, bot, channel, nick, user, botnick, ops, logger, action, privmsg, notice, msg_type, cmd=None, arg=None, text=None, nick_list=None, is_op=False):
+            self.bot = bot
+            self.datetime = datetime.now(timezone.utc)
+            self.timestamp = self.datetime.timestamp()
+            self.channel = channel
+            self.nick = nick
+            self.user = user
+            self.nick_list = nick_list
+            self.botnick = botnick
+            self.ops = ops
+            self.is_op = is_op
+            self.logger = logger
+            self.action = action
+            self.privmsg = privmsg
+            self.notice = notice
+            self.msg_type = msg_type
+            if cmd:
+                self.cmd = cmd
+                self.arg = arg
+            if text != None:
+                self.text = text
+            if cmd is None and text is None:
+                raise TypeError('missing cmd or text parameter')
+
+    def connect(self, *args, **kwargs):
+        # the irc library quietly retries failed connections, so say why it failed
+        try:
+            super().connect(*args, **kwargs)
+        except irc.client.ServerConnectionError as e:
+            self.logger.error(self.connection_error_message(args[0], args[1], e))
+            raise
+
+    def connection_error_message(self, host, port, error):
+        cause = error.__cause__
+        start = "couldn't connect to {}:{}: ".format(host, port)
+        end = ' (will keep retrying every 1-5 minutes)'
+        if isinstance(cause, ssl.SSLCertVerificationError):
+            start += "the server's ssl certificate failed verification ({}). ".format(cause.verify_message.rstrip('.'))
+            # openssl codes for hostname and ip address mismatch, and expired
+            if cause.verify_code in (62, 64):
+                return start + 'Set server to the name the certificate was issued for, not an IP address or alias' + end
+            if cause.verify_code == 10:
+                return start + 'This needs fixing on the server' + end
+            return start + 'If this server uses a self-signed certificate, set ssl_verify to false' + end
+        if isinstance(cause, ssl.SSLError):
+            return (start + 'ssl handshake failed ({}). '
+                    "Check {} is the server's ssl port, usually 6697".format(getattr(cause, 'reason', None) or cause, port) + end)
+        if isinstance(cause, socket.gaierror):
+            return start + 'server name not found, check the server setting' + end
+        if isinstance(cause, ConnectionRefusedError):
+            return start + 'connection refused, check the server and port settings' + end
+        return start + str(cause or error) + end
+
+    def warn_unknown_options(self, kwargs):
+        for key in sorted(set(kwargs) - self.options):
+            close = difflib.get_close_matches(key, self.options, n=1)
+            hint = ", did you mean '{}'?".format(close[0]) if close else ''
+            self.logger.warning("unknown option '{}' ignored{}".format(key, hint))
+
+    def setup_bans(self, nickname, kwargs):
+        self.ban_file = kwargs.get('ban_file', '{}.bans.json'.format(nickname)) or None
+        self.config_bans = list(kwargs.get('banned_users', []))
+        self.banned_users = list(self.config_bans)
+        saved = bans.load(self.ban_file)
+        for entry in saved:
+            if not self.nick_in(entry, self.banned_users):
+                self.banned_users.append(entry)
+        if saved:
+            self.logger.info('loaded {} bans from {}'.format(len(saved), self.ban_file))
+        # recent nicks and who they are, so !ban troll can ban their account or host
+        self.seen = OrderedDict()
+
+    def save_bans(self):
+        # bans from the config stay in the config, the file keeps the ones made with !ban
+        bans.save(self.ban_file, [b for b in self.banned_users if not self.nick_in(b, self.config_bans)])
+
+    def remember(self, nick, user, host, account):
+        key = irc.strings.lower(nick)
+        self.seen[key] = (nick, user, host, account)
+        self.seen.move_to_end(key)
+        while len(self.seen) > 1000:
+            self.seen.popitem(last=False)
+
+    def ban_entry(self, target):
+        # a nick on its own is easy to change, so ban their account if they're
+        # logged in, or their user and host if not
+        if bans.is_account(target) or bans.is_mask(target):
+            return target, target
+        seen = self.seen.get(irc.strings.lower(target))
+        if not seen:
+            return target, "{} (nick only, they haven't spoken since the bot started)".format(target)
+        nick, user, host, account = seen
+        if account:
+            return '$a:' + account, '{} (account {})'.format(target, account)
+        entry = '*!*{}@{}'.format((user or '').lstrip('~'), host)
+        return entry, '{} ({})'.format(target, entry)
+
+    def remove_bans(self, target):
+        # the entry itself, plus anything banning the person last seen as target
+        seen = self.seen.get(irc.strings.lower(target))
+        removed = [b for b in self.banned_users if self.nick_in(b, [target]) or (seen and bans.matches(b, *seen))]
+        self.banned_users = [b for b in self.banned_users if b not in removed]
+        return removed
+
+    @staticmethod
+    def account_from_tags(tags):
+        for tag in tags or []:
+            if tag['key'] == 'account' and tag['value'] not in (None, '*'):
+                return tag['value']
+        return None
+
+    def cap_factory(self, factory):
+        # ask what the server supports before the irc library sends NICK and USER,
+        # some servers (like libera) only allow it before registration
+        def connect(address):
+            sock = factory(address)
+            sock.send(b'CAP LS 302\r\n')
+            self._negotiating_caps = True
+            self._server_caps = set()
+            self.account_tag = False
+            return sock
+        return connect
+
+    def on_cap(self, c, e):
+        if not self._negotiating_caps:
+            return
+        subcommand = e.arguments[0]
+        if subcommand == 'LS':
+            self._server_caps.update(cap.split('=')[0] for cap in e.arguments[-1].split())
+            # a * means the list carries on in another line
+            if len(e.arguments) > 2 and e.arguments[1] == '*':
+                return
+            if 'account-tag' in self._server_caps:
+                c.cap('REQ', 'account-tag')
+                return
+        elif subcommand in ('ACK', 'NAK'):
+            self.account_tag = subcommand == 'ACK' and 'account-tag' in e.arguments[-1].split()
+        else:
+            return
+        # registration waits until we say we're done
+        self._negotiating_caps = False
+        c.cap('END')
+
+    def ssl_factory(self, server):
+        context = ssl.create_default_context()
+        if not self.ssl_verify:
+            context.check_hostname = False
+            context.verify_mode = ssl.CERT_NONE
+        wrapper = functools.partial(context.wrap_socket, server_hostname=server)
+        return irc.connection.Factory(wrapper=wrapper)
+
+    @staticmethod
+    def nick_in(nick, nicks):
+        # irc nicks are case insensitive, so Troll and troll are the same person
+        nick = irc.strings.lower(nick)
+        return any(irc.strings.lower(n) == nick for n in nicks)
+
+    def start_logging(self):
+        self.logger = log.get_bot_logger(self.bot_nick)
+        log_level = str(self.log_level).lower()
+        if log_level == 'off':
+            self.logger.disabled = True
+            return
+        if log_level not in self.log_levels:
+            raise ValueError("log_level must be one of: off, {}".format(', '.join(self.log_levels)))
+        self.logger.disabled = False
+        if self.log_file:
+            log.set_log_file(self.log_file, self.logger)
+        else:
+            log.set_log_file('{}.log'.format(self.bot_nick), self.logger)
+        self.logger.setLevel(self.log_levels[log_level])
+        self.logger.info('Logging started!')
+
+    def on_welcome(self, c, e):
+        if self.require_account and not self.account_tag:
+            self.logger.error("require_account is on but this server doesn't tell the bot who is logged in (account-tag), so the bot will ignore everyone")
+        if self.ns_pass:
+            self.logger.info('identifying with nickserv')
+            c.privmsg(self.nickserv, 'identify {}'.format(self.ns_pass))
+        for channel in self.chanlist:
+            self.logger.info('joining channel {}'.format(channel.split()[0]))
+            c.join(*channel.split())
+
+    def on_nicknameinuse(self, c, e):
+        # servers call us * until we're registered, after that a failed
+        # nick change should just keep the nick we already have
+        if e.target != '*':
+            return
+        new_nick = e.arguments[0] + '_'
+        self.logger.warning('nickname {} in use, trying {}'.format(e.arguments[0], new_nick))
+        c.nick(new_nick)
+
+    def on_featurelist(self, c, e):
+        # servers that support bot mode advertise its letter as BOT=<mode>
+        # https://ircv3.net/specs/extensions/bot-mode
+        if not self.bot_mode:
+            return
+        for feature in e.arguments:
+            if feature.startswith('BOT='):
+                mode = feature[len('BOT='):]
+                self.logger.info('setting bot mode +{}'.format(mode))
+                c.mode(c.get_nickname(), '+' + mode)
+
+    def on_pubmsg(self, c, e):
+        self.process_event(c, e)
+
+    def on_privmsg(self, c, e):
+        self.process_event(c, e)
+
+    def on_action(self, c, e):
+        self.process_event(c, e)
+
+    def call_help(self, nick, op):
+        cmds = {k:v.help_text for k,v in plugin.cmds.items() if not (plugin.cmds[k].ops or plugin.cmds[k].hide) }
+        cmds.update({self.cmd_prefix + 'help': 'returns this output to private message'})
+        if op:
+            cmds.update({k:v.help_text for k,v in plugin.cmds.items() if plugin.cmds[k].ops})
+            cmds.update({k:v for k,v in self.internal_commands.items()})
+        helpout = OrderedDict(sorted(cmds.items()))
+        for h in helpout:
+            self.connection.privmsg(nick, '{} -- {}'.format(h, helpout[h]))
+            time.sleep(.1)
+        self.connection.privmsg(nick, 'List of listeners: {}'.format(', '.join([l for l in plugin.lstnrs])))
+        return None
+
+    def call_internal_commands(self, channel, nick, cmd, text, arg, c, op=None):
+        if not cmd.startswith(self.cmd_prefix):
+            return None
+        else:
+            cmd = cmd[len(self.cmd_prefix):]
+        output = None
+        if op is None:
+            op = self.nick_in(nick, self.ops)
+        if cmd == 'join' and op:
+            try:
+                c.join(*arg.split())
+                self.logger.info('joining {} per request of {}'.format(arg, nick))
+                output = plugin.message('{}: joined {}'.format(nick, arg.split()[0]))
+            except:
+                self.logger.exception('issue with join command: {}join #channel <channel key>'.format(self.cmd_prefix))
+        elif cmd == 'quit' and op:
+            self.logger.info('quitting per request of {}'.format(nick))
+            if not arg:
+                arg = "See y'all later!"
+            c.quit(arg)
+            sys.exit()
+        elif cmd == 'help' and not self.disable_help:
+            self.call_help(nick, op)
+        elif cmd == 'reload' and op:
+            self.logger.info('reloading plugins per request of {}'.format(nick))
+            plugin.load_plugins(self.plugin_dir, use_prefix=self.use_prefix_for_plugins, cmd_prefix=self.cmd_prefix, logger=self.logger)
+            output = plugin.message('Plugins reloaded')
+        elif cmd == 'enable' and op:
+            if arg in plugin.plugins:
+                if plugin.plugins[arg].enabled:
+                    output = plugin.message("{}: '{}' already enabled".format(nick, arg))
+                else:
+                    plugin.plugins[arg].enable()
+                    output = plugin.message("{}: '{}' enabled!".format(nick, arg))
+            else:
+                output = plugin.message("{}: '{}' not found".format(nick, arg))
+        elif cmd == 'disable' and op:
+            if arg in plugin.plugins:
+                if not plugin.plugins[arg].enabled:
+                    output = plugin.message("{}: '{}' already disabled".format(nick, arg))
+                else:
+                    plugin.plugins[arg].disable()
+                    output = plugin.message("{}: '{}' disabled!".format(nick, arg))
+            else:
+                output = plugin.message("{}: '{}' not found".format(nick, arg))
+        elif cmd in ('op', 'deop', 'ban', 'unban') and op and not arg.split():
+            output = plugin.message('{}: usage: {}{} <nick>'.format(nick, self.cmd_prefix, cmd))
+        elif cmd == 'op' and op:
+            for o in arg.split():
+                if not self.nick_in(o, self.ops):
+                    self.ops.append(o)
+            output = plugin.message('{}: {} added as op'.format(nick, arg))
+        elif cmd == 'deop' and op:
+            for o in arg.split():
+                self.ops = [i for i in self.ops if not self.nick_in(i, [o])]
+            output = plugin.message('{}: {} removed as op'.format(nick, arg))
+        elif cmd == 'ops' and op:
+            output = plugin.message('current ops: {}'.format(', '.join(self.ops)))
+        elif cmd == 'ban' and op:
+            banned = []
+            for target in arg.split():
+                entry, description = self.ban_entry(target)
+                if not self.nick_in(entry, self.banned_users):
+                    self.banned_users.append(entry)
+                banned.append(description)
+            self.save_bans()
+            output = plugin.message('{}: banned {}'.format(nick, ', '.join(banned)))
+        elif cmd == 'unban' and op:
+            removed = []
+            for target in arg.split():
+                removed += self.remove_bans(target)
+            self.save_bans()
+            if not removed:
+                output = plugin.message('{}: no ban found for {}'.format(nick, arg))
+            else:
+                reply = '{}: removed ban on {}'.format(nick, ', '.join(removed))
+                from_config = [b for b in removed if self.nick_in(b, self.config_bans)]
+                if from_config:
+                    reply += " ({} is in the config file, so it'll be back after a restart)".format(', '.join(from_config))
+                output = plugin.message(reply)
+        elif cmd == 'banlist' and op:
+            output = plugin.message('currently banned: {}'.format(', '.join(self.banned_users) or 'nobody'))
+        return output
+
+    def check_output(self, output):
+        if output and not isinstance(output, plugin.Output):
+            raise TypeError('plugins must return message() or action(), got {}'.format(type(output).__name__))
+        return output
+
+    def call_plugins(self, privmsg, action, notice, chan, cmd, text, nick_list, nick, user, arg, msg_type, botnick, op=None):
+        output = None
+        if op is None:
+            op = self.nick_in(nick, self.ops)
+        if cmd in plugin.cmds:
+            try:
+                if plugin.cmds[cmd].ops and not op:
+                    if plugin.cmds[cmd].ops_msg:
+                        output =  plugin.message(plugin.cmds[cmd].ops_msg)
+                elif plugin.cmds[cmd].enabled:
+                    self.logger.debug('executing {}'.format(cmd))
+                    output = self.check_output(plugin.cmds[cmd].run(self.Message(
+                        bot=self,
+                        channel=chan,
+                        cmd=cmd,
+                        nick_list=nick_list,
+                        nick=nick,
+                        user=user,
+                        arg=arg,
+                        privmsg=privmsg,
+                        action=action,
+                        notice=notice,
+                        botnick=botnick,
+                        ops=self.ops,
+                        logger=self.logger,
+                        msg_type=msg_type,
+                        is_op=op
+                    )))
+            except Exception:
+                self.logger.exception('issue with command {}'.format(cmd))
+        else:
+            for lstnr in plugin.lstnrs:
+                if plugin.lstnrs[lstnr].enabled:
+                    try:
+                        self.logger.debug('whispering to listener: {}'.format(lstnr))
+                        listen_output = self.check_output(plugin.lstnrs[lstnr].run(self.Message(
+                            bot=self,
+                            channel=chan,
+                            text=text,
+                            nick_list=nick_list,
+                            nick=nick,
+                            user=user,
+                            privmsg=privmsg,
+                            action=action,
+                            notice=notice,
+                            botnick=botnick,
+                            ops=self.ops,
+                            logger=self.logger,
+                            msg_type=msg_type,
+                            is_op=op
+                        )))
+                        if listen_output:
+                            output = listen_output
+                    except Exception:
+                        self.logger.exception('issue with listener {}'.format(lstnr))
+        if output:
+            self.logger.debug(f'returning output: {output.msg}')
+        return output
+
+    def process_event(self, c, e):
+        nick = e.source.nick
+        user = e.source.user
+        host = e.source.host
+        account = self.account_from_tags(e.tags)
+        self.remember(nick, user, host, account)
+        if bans.matches_any(self.banned_users, nick, user, host, account):
+            self.logger.debug('ignoring banned user {}'.format(nick))
+            return
+        botnick = c.get_nickname()
+        if irc.strings.lower(nick) == irc.strings.lower(botnick):
+            return
+        if self.require_account and not account:
+            self.logger.debug('ignoring {}, not logged in to an account'.format(nick))
+            return
+        op = bans.matches_any(self.ops, nick, user, host, account)
+        if e.arguments:
+            text = e.arguments[0]
+        else:
+            text = ''
+        if e.type == 'privmsg' or e.type == 'pubmsg':
+            msg_type = 'message'
+        else:
+            msg_type = e.type
+        if not irc.client.is_channel(e.target):
+            chan = nick
+            nick_list = [nick]
+        else:
+            chan = e.target
+            nick_list = list(self.channels[chan].users())
+        if e.type == 'action':
+            cmd = ''
+        else:
+            cmd = text.split(' ')[0]
+        self.logger.debug(
+            'Message info: channel: {}, nick: {}, cmd: {}, text: {}'.format(chan, nick, cmd, text)
+        )
+        if len(text.split(' ')) > 1:
+            arg = ''.join([i + ' ' for i in text.split(' ')[1:]]).strip()
+        else:
+            arg = ''
+        output = self.call_internal_commands(chan, nick, cmd, text, arg, c, op=op)
+        if not output:
+            plugin_info = {
+                'chan': chan,
+                'cmd': cmd,
+                'text': text,
+                'nick_list': nick_list,
+                'nick': nick,
+                'user': user,
+                'arg': arg,
+                'privmsg': c.privmsg,
+                'action': c.action,
+                'notice': c.notice,
+                'msg_type': msg_type,
+                'botnick': botnick,
+                'op': op
+            }
+            output = self.call_plugins(**plugin_info)
+        if output:
+            self.logger.debug(f'sending output: {output.msg}')
+            self.process_output(c, chan, output)
+
+    def process_output(self, c, chan, output):
+        if not output.msg:
+            return
+        for msg in output.msg:
+            if output.msg_type == plugin.OutputType.Message:
+                self.logger.debug('output message: {}'.format(msg))
+                try:
+                    c.privmsg(chan, msg)
+                except irc.client.MessageTooLong:
+                    self.logger.error('output message too long: {}'.format(msg))
+                    break
+            elif output.msg_type == plugin.OutputType.Action:
+                self.logger.debug('output action: {}'.format(msg))
+                try:
+                    c.action(chan, msg)
+                except irc.client.MessageTooLong:
+                    self.logger.error('output message too long: {}'.format(msg))
+                    break
+            else:
+                self.logger.warning("Unsupported output type '{}'".format(output.msg_type))
+            time.sleep(.5)
+
+
+class TwitchBot(Bot):
+    server = 'irc.chat.twitch.tv'
+    options = {
+        'port', 'ops', 'plugin_dir', 'log_level', 'log_file', 'cmd_prefix',
+        'use_prefix_for_plugins', 'disable_help', 'banned_users', 'bot_mode',
+        'ban_file',
+    }
+
+    def __init__(self, nickname, channel, token, **kwargs):
+        self.port = kwargs.get('port', 6697)
+        self.ssl_verify = True
+        self.ops = kwargs.get('ops', [])
+        self.plugin_dir = kwargs.get('plugin_dir', 'plugins')
+        self.log_level = kwargs.get('log_level', 'info')
+        self.log_file = kwargs.get('log_file', None)
+        self.server_pass = kwargs.get('server_pass', None)
+        self.cmd_prefix = kwargs.get('cmd_prefix', '!')
+        self.use_prefix_for_plugins = kwargs.get('use_prefix_for_plugins', False)
+        self.disable_help = kwargs.get('disable_help', False)
+        self.bot_mode = kwargs.get('bot_mode', True)
+        self.require_account = False
+        self.bot_nick = nickname
+        self.start_logging()
+        self.warn_unknown_options(kwargs)
+        self.setup_bans(nickname, kwargs)
+        self.channel = channel
+        self.logger.info('Joining Twitch Server')
+        # always use tls, the oauth token is a password
+        irc.bot.SingleServerIRCBot.__init__(self, [(self.server, self.port, 'oauth:'+token)], nickname, nickname, connect_factory=self.ssl_factory(self.server))
+        self.internal_commands = {self.cmd_prefix + k: v for k,v in self.internal_commands.items()}
+        plugin.load_plugins(self.plugin_dir, use_prefix=self.use_prefix_for_plugins, cmd_prefix=self.cmd_prefix, logger=self.logger)
+
+    def on_welcome(self, c, e):
+        self.logger.info('requesting permissions')
+        c.cap('REQ', ':twitch.tv/membership')
+        c.cap('REQ', ':twitch.tv/tags')
+        c.cap('REQ', ':twitch.tv/commands')
+        self.logger.info('Joining channel ' + self.channel)
+        c.join(self.channel)

pinhook/cli.py

@@ -0,0 +1,86 @@
+import click
+from .bot import Bot
+from marshmallow import Schema, fields, validate, INCLUDE, ValidationError
+
+class Config(Schema):
+    nickname = fields.Str(required=True)
+    channels = fields.List(fields.Str(), required=True)
+    server = fields.Str(required=True)
+    port = fields.Int()
+    ops = fields.List(fields.Str())
+    ssl_required = fields.Bool()
+    ssl_verify = fields.Bool()
+    plugin_dir = fields.Str()
+    ns_pass = fields.Str()
+    nickserv = fields.Str()
+    log_level = fields.Str(validate=validate.OneOf(['off'] + list(Bot.log_levels)))
+    log_file = fields.Str()
+    server_pass = fields.Str()
+    cmd_prefix = fields.Str()
+    use_prefix_for_plugins = fields.Bool()
+    disable_help = fields.Bool()
+    banned_users = fields.List(fields.Str())
+    bot_mode = fields.Bool()
+    ban_file = fields.Str(allow_none=True)
+    require_account = fields.Bool()
+
+    class Meta:
+        unknown = INCLUDE
+
+def check_conf(schema, data, name):
+    try:
+        return schema.load(data)
+    except ValidationError as e:
+        problems = ['  {}: {}'.format(key, ' '.join(msgs) if isinstance(msgs, list) else msgs) for key, msgs in sorted(e.messages.items())]
+        raise click.ClickException('{} has problems:\n{}'.format(name, '\n'.join(problems)))
+
+def read_conf(config, conf_format):
+    schema = Config()
+    if not conf_format:
+        if config.name.endswith('.json'):
+            conf_format = 'json'
+        elif config.name.endswith(('.yaml', '.yml')):
+            conf_format = 'yaml'
+        elif config.name.endswith(('.toml', '.tml')):
+            conf_format = 'toml'
+        else:
+            raise click.ClickException('Could not detect file format, please supply using --format option')
+    if conf_format == 'json':
+        import json
+        to_json = json.loads(config.read())
+        output = check_conf(schema, to_json, config.name)
+    elif conf_format == 'yaml':
+        try:
+            import yaml
+        except ImportError:
+            raise click.ClickException('yaml not installed, please use `pip3 install pinhook[yaml]` to install')
+        else:
+            to_yaml = yaml.load(config.read(), Loader=yaml.FullLoader)
+            output = check_conf(schema, to_yaml, config.name)
+    elif conf_format == 'toml':
+        try:
+            # built in from python 3.11
+            import tomllib
+        except ImportError:
+            try:
+                import toml
+            except ImportError:
+                raise click.ClickException('toml not installed, please use `pip3 install pinhook[toml]` to install')
+            to_toml = toml.load(config.name)
+        else:
+            to_toml = tomllib.load(config)
+        output = check_conf(schema, to_toml, config.name)
+    return output
+
+@click.command()
+@click.argument('config', type=click.File('rb'))
+@click.option('--format', '-f', 'conf_format', type=click.Choice(['json', 'yaml', 'toml']))
+def cli(config, conf_format):
+    config = read_conf(config, conf_format)
+    try:
+        bot = Bot(**config)
+    except ValueError as e:
+        # a bad log_level or ban file, say what's wrong without a traceback
+        raise click.ClickException(str(e))
+    bot.start()
+

pinhook/log.py

@@ -0,0 +1,24 @@
+import logging
+
+logger = logging.getLogger('bot')
+formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(name)s - %(module)s - %(message)s')
+# Set console logger
+streamhandler = logging.StreamHandler()
+streamhandler.setFormatter(formatter)
+logger.addHandler(streamhandler)
+
+def get_bot_logger(nickname):
+    # each bot gets its own child of the 'bot' logger so it can have its own
+    # level and log file, console output still goes through the parent
+    bot_logger = logger.getChild(nickname)
+    # a new bot with the same nick replaces the old one's log file
+    for handler in list(bot_logger.handlers):
+        bot_logger.removeHandler(handler)
+        handler.close()
+    return bot_logger
+
+def set_log_file(filename, target=logger):
+    # Set file logger
+    filehandler = logging.FileHandler(filename)
+    filehandler.setFormatter(formatter)
+    target.addHandler(filehandler)

pinhook/plugin.py

@@ -0,0 +1,183 @@
+from enum import Enum
+from functools import wraps
+import importlib.util
+import os
+import sys
+
+from .log import logger
+
+plugins = {}
+cmds = {}
+lstnrs = {}
+
+class OutputType(Enum):
+    Message = 'message'
+    Action = 'action'
+
+
+class Output:
+    def __init__(self, msg_type, msg):
+        self.msg_type = msg_type
+        self.msg = self.sanitize(msg)
+
+    def sanitize(self, msg):
+        if isinstance(msg, str):
+            return msg.splitlines()
+        if isinstance(msg, (list, tuple)):
+            # items in a list can have newlines too
+            return [line for m in msg for line in str(m).splitlines()]
+        return msg
+
+
+class _BasePlugin:
+    enabled = True
+    logger = logger
+
+    def enable(self):
+        self.enabled = True
+
+    def disable(self):
+        self.enabled = False
+
+
+class Listener(_BasePlugin):
+    def __init__(self, name, run=None):
+        self.name = name
+        if run:
+            self.run = run
+        self._add_listener()
+
+    def __str__(self):
+        return self.name
+
+    def run(self):
+        pass
+
+    def _add_listener(self):
+        lstnrs[self.name] = self
+        plugins[self.name] = self
+
+
+class Command(_BasePlugin):
+    def __init__(self, cmd, **kwargs):
+        self.cmd = cmd
+        self.help_text = kwargs.get('help_text', 'N/A')
+        self.ops = kwargs.get('ops', False)
+        self.ops_msg = kwargs.get('ops_msg', '')
+        self.hide = kwargs.get('hide', False)
+        self.run = kwargs.get('run', self.run)
+        self._add_command()
+
+    def __str__(self):
+        return self.cmd
+    
+    def run(self, msg):
+        pass
+
+    def _enable_ops(self, ops_msg):
+        self.ops = True
+        self.ops_msg = ops_msg
+
+    def _update_plugin(self, **kwargs):
+        self.help_text = kwargs.get('help_text', 'N/A')
+        self.run = kwargs.get('run', self.run)
+
+    def _add_command(self):
+        cmds[self.cmd] = self
+        plugins[self.cmd] = self
+
+
+def action(msg):
+    return Output(OutputType.Action, msg)
+
+def message(msg):
+    return Output(OutputType.Message, msg)
+
+def _add_command(command, help_text, func,  ops=False, ops_msg='', hide=False):
+    if command not in cmds:
+        Command(command, help_text=help_text, ops=ops, ops_msg=ops_msg, hide=hide, run=func)
+    else:
+        cmds[command]._update_plugin(help_text=help_text, run=func)
+
+def _ops_plugin(command, ops_msg, func):
+    if command not in cmds:
+        Command(command, ops=True, ops_msg=ops_msg)
+    else:
+        cmds[command]._enable_ops(ops_msg)
+
+def _add_listener(name, func):
+    Listener(name, run=func)
+
+def clear_plugins():
+    cmds.clear()
+    lstnrs.clear()
+    plugins.clear()
+
+def load_plugins(plugin_dir, use_prefix=False, cmd_prefix='!', logger=logger):
+    # i'm not sure why i need this but i do
+    global cmds
+    global plugins
+    global lstnrs
+    #check for all the disabled plugins so that we don't re-enable them
+    disabled_plugins = [i for i in plugins if not plugins[i].enabled]
+    logger.debug(disabled_plugins)
+    # clear plugin list to ensure no old plugins remain
+    logger.info('clearing plugin cache')
+    clear_plugins()
+    # ensure plugin folder exists
+    logger.info('checking plugin directory')
+    if not os.path.exists(plugin_dir):
+        logger.info('plugin directory {} not found, creating'.format(plugin_dir))
+        os.makedirs(plugin_dir)
+    # load all plugins
+    for m in os.listdir(plugin_dir):
+        if m.endswith('.py'):
+            try:
+                name = m[:-3]
+                logger.info('loading plugin {}'.format(name))
+                # load under our own name so a plugin called json.py can't replace the real json module
+                spec = importlib.util.spec_from_file_location('pinhook_plugins.' + name, os.path.join(plugin_dir, m))
+                module = importlib.util.module_from_spec(spec)
+                sys.modules[spec.name] = module
+                spec.loader.exec_module(module)
+            except Exception:
+                logger.exception('could not load plugin')
+    # gather all commands and listeners
+    if use_prefix: # use prefixes if needed
+        cmds = {cmd_prefix + k: v for k,v in cmds.items()}
+    for p in plugins:
+        if p in disabled_plugins:
+            plugins[p].disable()
+    for cmd in cmds:
+        logger.debug('adding command {}'.format(cmd))
+    for lstnr in lstnrs:
+        logger.debug('adding listener {}'.format(lstnr))
+
+def command(command, help_text='N/A', ops=False, ops_msg='', hide=False):
+    @wraps(command)
+    def register_for_command(func):
+        _add_command(command, help_text, func, ops=ops, ops_msg=ops_msg, hide=hide)
+        return func
+    return register_for_command
+
+def register(command, help_text='N/A'):
+    logger.warning('@register decorator has been deprecated in favor of @command. This will cause errors in future versions.')
+    @wraps(command)
+    def register_for_command(func):
+        _add_command(command, help_text, func)
+        return func
+    return register_for_command
+
+def listener(name):
+    def register_as_listener(func):
+        _add_listener(name, func)
+        return func
+    return register_as_listener
+
+def ops(command, msg=None):
+    logger.warning('use of the @ops decorator has been deprecated in favor of using the @command decorator with the ops and ops_msg options. Use will cause errors in future versions.')
+    @wraps(command)
+    def register_ops_command(func):
+        _ops_plugin(command, msg, func)
+        return func
+    return register_ops_command

pinhook-1.11.0.dist-info/METADATA

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: pinhook
+Version: 1.11.0
+Summary: a pluggable irc bot framework in python
+Home-page: https://github.com/archangelic/pinhook
+Author: M. Hancock
+Author-email: mhancock@archangelic.space
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: irc
+Requires-Dist: click
+Requires-Dist: marshmallow
+Provides-Extra: toml
+Requires-Dist: toml; python_version < "3.11" and extra == "toml"
+Provides-Extra: yaml
+Requires-Dist: pyyaml; extra == "yaml"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+
+# pinhook
+
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/pinhook.svg)](https://pypi.org/project/pinhook) [![Package License](https://img.shields.io/pypi/l/pinhook.svg)](https://github.com/archangelic/pinhook/blob/master/LICENSE) [![PyPI package format](https://img.shields.io/pypi/format/pinhook.svg)](https://pypi.org/project/pinhook) [![Package development status](https://img.shields.io/pypi/status/pinhook.svg)](https://pypi.org/project/pinhook) [![With love from tilde.town](https://img.shields.io/badge/with%20love%20from-tilde%20town-e0b0ff.svg)](https://tilde.town)
+
+The pluggable python framework for IRC bots and Twitch bots
+
+**Documentation: https://archangelic.github.io/pinhook/**
+
+## Installation
+
+``` bash
+pip install pinhook
+```
+
+## Quick start
+
+Make a `plugins` folder with this in `plugins/hello.py`:
+
+```python
+import pinhook.plugin
+
+@pinhook.plugin.command('!hello', help_text='says hello back')
+def hello(msg):
+    return pinhook.plugin.message('hi {}!'.format(msg.nick))
+```
+
+Then start a bot, from a python file:
+
+```python
+from pinhook.bot import Bot
+
+bot = Bot(
+    channels=['#foo'],
+    nickname='ph-bot',
+    server='irc.libera.chat',
+    port=6697,
+    ssl_required=True,
+)
+bot.start()
+```
+
+or from a config file, with `pinhook config.yaml`:
+
+```yaml
+nickname: "ph-bot"
+server: "irc.libera.chat"
+port: 6697
+ssl_required: true
+channels:
+    - "#foo"
+```
+
+Say `!hello` in `#foo` and the bot answers.
+
+## Learn more
+
+* [Getting started](https://archangelic.github.io/pinhook/latest/getting-started/)
+* [Options](https://archangelic.github.io/pinhook/latest/options/)
+* [Built-in commands](https://archangelic.github.io/pinhook/latest/commands/)
+* [Writing plugins](https://archangelic.github.io/pinhook/latest/plugins/)
+* [Bans and ops](https://archangelic.github.io/pinhook/latest/bans-and-ops/)
+* [Twitch bots](https://archangelic.github.io/pinhook/latest/twitch/)
+* [Troubleshooting](https://archangelic.github.io/pinhook/latest/troubleshooting/)
+* [Upgrading to 1.11](https://archangelic.github.io/pinhook/latest/upgrading/)
+
+## Examples
+
+There are some basic examples in the `examples` directory in this repository.
+
+Here is a list of live bots using pinhook:
+
+* [pinhook-tilde](https://github.com/archangelic/pinhook-tilde) - fun bot for tilde.town
+* [adminbot](https://github.com/tildetown/adminbot) - admin helper bot for tilde.town, featuring some of the ways you can change the Bot class to suit your needs

pinhook-1.11.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+pinhook/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pinhook/__version__.py,sha256=glAkwZsi0Hbv-R1Jbe-2qECv-6AWHNGvlRS_cgbvCTU,23
+pinhook/bans.py,sha256=vyIrHN4ejANac9fd3aXvcmF81Ki9zOf0px8I7vU8MNs,1704
+pinhook/bot.py,sha256=5Uty6gSxC1EUptfwkOhWeGxLF5geSXENOrIS1_NUGKw,25804
+pinhook/cli.py,sha256=WAjIlWqZK_5f_kQfNQtMvpVjJFkvIXmU4lXPfILjn5U,3176
+pinhook/log.py,sha256=BQGFAia0fXsOBzBI4cD4QMdOx99rEewExCxg71tjczw,892
+pinhook/plugin.py,sha256=_pz2dRiurZROeGS3QRmyw44pVGJFaNRh39pKaBibz50,5498
+pinhook-1.11.0.dist-info/licenses/LICENSE,sha256=K_nYx_j4vZZEkXPmnBlsg9sKMBvwXtU3n-98ITmQ5lo,1067
+pinhook-1.11.0.dist-info/METADATA,sha256=o8HGwPlOIXtrGJaUU5xO0C-7TBqUO_fgR6WLuWrjBtE,3803
+pinhook-1.11.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+pinhook-1.11.0.dist-info/entry_points.txt,sha256=cntGw5Ri3rD8RStghG4nJYXQhAvnHG9qZyi3_1Euglk,44
+pinhook-1.11.0.dist-info/top_level.txt,sha256=beywy3YHJ9gxBRkXCzfJHp6CRoUawHfts_qkYMNqWms,8
+pinhook-1.11.0.dist-info/RECORD,,

pinhook-1.11.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pinhook-1.11.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pinhook = pinhook.cli:cli

pinhook-1.11.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 M. Hancock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pinhook-1.11.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pinhook