# Erebus IRC bot - Author: John Runyon
+# vim: fileencoding=utf-8
# module helper functions, see modules/modtest.py for usage
# This file is released into the public domain; see http://unlicense.org/
+import abc
+import sys
+import socket
+from functools import wraps
+
+if sys.version_info.major < 3:
+ stringbase = basestring
+else:
+ stringbase = str
+
+"""Used to return an error to the bot core."""
class error(object):
def __init__(self, desc):
self.errormsg = desc
def __nonzero__(self):
return False #object will test to False
+ __bool__ = __nonzero__ #py3 compat
def __repr__(self):
return '<modlib.error %r>' % self.errormsg
def __str__(self):
MANAGER = 99
ADMIN = 75
STAFF = 50
- AUTHED = 0
- ANYONE = -1
+ KNOWN = 1
+ AUTHED = 0 # Users which have are known to be authed
+ ANYONE = -1 # non-authed users have glevel set to -1
+ IGNORED = -2 # If the user is IGNORED, no hooks or chanhooks will fire for their messages. numhooks can still be fired.
+ glevs = {
+ 'OWNER': OWNER,
+ 'MANAGER': MANAGER,
+ 'ADMIN': ADMIN,
+ 'STAFF': STAFF,
+ 'KNOWN': KNOWN,
+ 'AUTHED': AUTHED,
+ 'ANYONE': ANYONE,
+ 'IGNORED': IGNORED,
+ }
# (channel) access levels
- OWNER = 5
+ COWNER = 5
MASTER = 4
OP = 3
VOICE = 2
- KNOWN = 1
- PUBLIC = 0 #anyone (use glevel to control auth-needed)
+ FRIEND = 1
+ PUBLIC = 0 # Anyone (use glevel to control whether auth is needed)
+ BANNED = -1 # The default reqclevel is PUBLIC, so any commands which needchan will be ignored from BANNED users unless the command reqclevel=-1
+ # [ 0 1 2 3 4 5 -1]
+ clevs = [None, 'Friend', 'Voice', 'Op', 'Master', 'Owner', 'Banned']
# messages
WRONGARGS = "Wrong number of arguments."
def __init__(self, name):
- self.hooks = {}
- self.numhooks = {}
- self.chanhooks = {}
+ self.Socketlike = Socketlike
+ self.hooks = {} # {command:handler}
+ self.chanhooks = {} # {channel:handler}
+ self.exceptionhooks = [] # [(exception,handler)]
+ self.numhooks = {} # {numeric:handler}
+ self.sockhooks = [] # [(af,ty,address,handler_class)]
+ self.sockets = [] # [(sock,obj)]
+ self.helps = []
self.parent = None
- self.name = name
+ self.name = (name.split("."))[-1]
def modstart(self, parent):
+ #modstart can return a few things...
+ # None: unspecified success
+ # False: unspecified error
+ # modlib.error (or anything else False-y): specified error
+ # True: unspecified success
+ # non-empty string (or anything else True-y): specified success
+ #"specified" values will be printed. unspecified values will result in "OK" or "failed"
self.parent = parent
- for cmd, func in self.hooks.iteritems():
- self.parent.hook(cmd, func)
- for num, func in self.numhooks.iteritems():
- self.parent.hooknum(num, func)
- for chan, func in self.chanhooks.iteritems():
- self.parent.hookchan(chan, func)
+ for cmd, func in self.hooks.items():
+ parent.hook(cmd, func)
+ parent.hook("%s.%s" % (self.name, cmd), func)
+ for chan, func in self.chanhooks.items():
+ parent.hookchan(chan, func)
+ for exc, func in self.exceptionhooks:
+ parent.hookexception(exc, func)
+ for num, func in self.numhooks.items():
+ parent.hooknum(num, func)
+ for hookdata in self.sockhooks:
+ self._create_socket(*hookdata)
+
+ for func, args, kwargs in self.helps:
+ try:
+ self.mod('help').reghelp(func, *args, **kwargs)
+ except:
+ pass
return True
def modstop(self, parent):
- for cmd, func in self.hooks.iteritems():
- self.parent.unhook(cmd, func)
- for num, func in self.numhooks.iteritems():
- self.parent.unhooknum(num, func)
- for chan, func in self.chanhooks.iteritems():
- self.parent.unhookchan(chan, func)
+ for cmd, func in self.hooks.items():
+ parent.unhook(cmd, func)
+ parent.unhook("%s.%s" % (self.name, cmd), func)
+ for chan, func in self.chanhooks.items():
+ parent.unhookchan(chan, func)
+ for exc, func in self.exceptionhooks:
+ parent.unhookexception(exc, func)
+ for num, func in self.numhooks.items():
+ parent.unhooknum(num, func)
+ for sock, obj in self.sockets:
+ self._destroy_socket(sock, obj)
+
+ for func, args, kwargs in self.helps:
+ try:
+ self.mod('help').dereghelp(func, *args, **kwargs)
+ except:
+ pass
return True
- def hooknum(self, num):
+ def hook(self, cmd=None, needchan=True, glevel=ANYONE, clevel=PUBLIC, wantchan=None):
+ if wantchan is None: wantchan = needchan
+ _cmd = cmd #save this since it gets wiped out...
def realhook(func):
- self.numhooks[str(num)] = func
- if self.parent is not None:
- self.parent.hooknum(str(num), func)
+ cmd = _cmd #...and restore it
+ if cmd is None:
+ cmd = func.__name__ # default to function name
+ if isinstance(cmd, stringbase):
+ cmd = (cmd,)
+
+ if clevel > self.PUBLIC and not needchan:
+ raise Exception('clevel must be left at default if needchan is False')
+
+ func.needchan = needchan
+ func.wantchan = wantchan
+ func.reqglevel = glevel
+ func.reqclevel = clevel
+ func.cmd = cmd
+ func.module = func.__module__.split('.')[1]
+
+ for c in cmd:
+ self.hooks[c] = func
+ if self.parent is not None:
+ self.parent.hook(c, func)
+ self.parent.hook("%s.%s" % (self.name, c), func)
return func
return realhook
return func
return realhook
- def hook(self, cmd=None, needchan=True, glevel=ANYONE, clevel=PUBLIC):
- _cmd = cmd #save this since it gets wiped out...
+ def hookexception(self, exc):
def realhook(func):
- cmd = _cmd #...and restore it
- if cmd is None:
- cmd = func.__name__ # default to function name
-
- func.needchan = needchan
- func.reqglevel = glevel
- func.reqclevel = clevel
+ self.exceptionhooks.append((exc, func))
+ if self.parent is not None:
+ self.parent.hookexception(exc, func)
+ return func
+ return realhook
- self.hooks[cmd] = func
+ def hooknum(self, num):
+ def realhook(func):
+ self.numhooks[str(num)] = func
if self.parent is not None:
- self.parent.hook(cmd, func)
+ self.parent.hooknum(str(num), func)
return func
return realhook
+ def bind(self, bindto, data=None):
+ """Used as a decorator on a class which implements getdata and parse methods.
+ See modules/sockets.py for an example.
+ Takes an arg like:
+ [unix:]/foo/bar
+ [udp|tcp:][ip:]port
+ """
+ if len(bindto) == 0:
+ raise Exception('bindto must have a value')
+ if bindto[0] == '/':
+ return self._hooksocket(socket.AF_UNIX, socket.SOCK_STREAM, bindto)
+ if len(bindto) > 5 and bindto[0:5] == 'unix:':
+ return self._hooksocket(socket.AF_UNIX, socket.SOCK_STREAM, bindto[5:])
+ af = socket.AF_INET
+ ty = socket.SOCK_STREAM
+ host = '0.0.0.0'
+ if len(bindto) > 4 and bindto[0:4] == 'udp:':
+ ty = socket.SOCK_DGRAM
+ bindto = bindto[4:]
+ if len(bindto) > 4 and bindto[0:4] == 'tcp:':
+ bindto = bindto[4:]
+ if ':' in bindto:
+ pieces = bindto.rsplit(':', 1)
+ host = pieces[0]
+ bindto = pieces[1]
+ port = int(bindto)
+ return self._hooksocket(af, ty, (host, port), data)
+
+ def bind_tcp(self, host, port, data=None):
+ return self._hooksocket(socket.AF_INET, socket.SOCK_STREAM, (host, port), data)
+ def bind_udp(self, host, port, data=None):
+ return self._hooksocket(socket.AF_INET, socket.SOCK_DGRAM, (host, port), data)
+ def bind_unix(self, path, data=None):
+ return self._hooksocket(socket.AF_UNIX, socket.SOCK_STREAM, path, data)
+ def _hooksocket(self, af, ty, address, data):
+ def realhook(cls):
+ if not issubclass(cls, Socketlike):
+ raise Exception('Attempted to hook a socket without a class to process data')
+ self.sockhooks.append((af, ty, address, cls, data))
+ if self.parent is not None:
+ self._create_socket(af, ty, address, cls, data)
+ return cls
+ return realhook
+ def _create_socket(self, af, ty, address, cls, data):
+ ty = ty | socket.SOCK_NONBLOCK
+ sock = socket.socket(af, ty)
+ sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+ sock.bind(address)
+ obj = _ListenSocket(self, sock, cls, data)
+ self.sockets.append((sock,obj))
+ sock.listen(5)
+ self.parent.newfd(obj, sock.fileno())
+ self.parent.log(repr(obj), '?', 'Socket ready to accept new connections (%r, %r, %r, %r)' % (af, ty, address, cls))
+ def _destroy_socket(self, sock, obj):
+ obj.close()
+
def mod(self, modname):
if self.parent is not None:
return self.parent.module(modname)
else:
return error('unknown parent')
+
+ def flags(self, *flags):
+ """Parses out "flags" to a command, like `MODUNLOAD -AUTOLOAD somemodule`
+ @lib.hook()
+ @lib.flags('autoload', 'force')
+ def baz(bot, user, chan, realtarget, flags, *args)
+
+ Note the added `flags` argument, which will be a dict - in this case `{'autounload':true,'force':false}`."""
+ def realhook(func):
+ func.flags = [f.lower() for f in flags]
+
+ @wraps(func)
+ def parseargs(bot, user, chan, realtarget, *_args):
+ args = list(_args) # we need a copy, also need a list, iterate over _args-tuple, mutate args-list
+ found_flags = {f: False for f in flags}
+ for arg in _args:
+ if arg[0] == "-" and len(arg) > 1:
+ found_prefix = None
+ possible_flag = arg[1:].lower()
+ for f in flags:
+ if possible_flag == f: # Exact match?
+ found_flags[possible_flag] = True
+ args.remove(arg)
+ found_prefix = None
+ break
+ elif f.find(possible_flag) == 0: # Is the current word a prefix of a flag?
+ if found_prefix is not None: # Is it also a prefix of another flag?
+ return 'Error: %s is a prefix of multiple flags (%s, %s).' % (possible_flag, found_prefix[1], f)
+ else:
+ found_prefix = (arg,f)
+ if found_prefix is not None: # found (only one) prefix
+ found_flags[found_prefix[1]] = True
+ args.remove(found_prefix[0])
+ return func(bot, user, chan, realtarget, found_flags, *args)
+
+ return parseargs
+ return realhook
+
+
def argsEQ(self, num):
def realhook(func):
+ @wraps(func)
def checkargs(bot, user, chan, realtarget, *args):
- if len(args) == num:
+ adjuster = 0
+ if hasattr(checkargs, 'flags'):
+ adjuster = 1
+ if len(args)-adjuster == num:
return func(bot, user, chan, realtarget, *args)
else:
bot.msg(user, self.WRONGARGS)
- checkargs.__name__ = func.__name__
return checkargs
return realhook
def argsGE(self, num):
def realhook(func):
+ @wraps(func)
def checkargs(bot, user, chan, realtarget, *args):
- if len(args) >= num:
+ adjuster = 0
+ if hasattr(checkargs, 'flags'):
+ adjuster = 1
+ if len(args)-adjuster >= num:
return func(bot, user, chan, realtarget, *args)
else:
bot.msg(user, self.WRONGARGS)
- checkargs.__name__ = func.__name__
return checkargs
return realhook
- def help(*args, **kwargs):
- """help(args, shorthelp, longhelp, more lines longhelp, cmd=...?)
+ def help(self, *args, **kwargs):
+ """help(syntax, shorthelp, longhelp?, more lines longhelp?, cmd=...?)
Example:
help("<user> <pass>", "login")
^ Help will only be one line. Command name determined based on function name.
^ Command takes no args. Short description (in overall HELP listing) is "do stuff".
Long description (HELP <command>) will say "<command> - do stuff", newline, "This command is really complicated."
"""
- try:
- self.mod('help').reghelp(*args, **kwargs)
- except:
- pass
+ def realhook(func):
+ if self.parent is not None:
+ try:
+ self.mod('help').reghelp(func, *args, **kwargs)
+ except:
+ pass
+ self.helps.append((func, args, kwargs))
+ return func
+ return realhook
+
+class Socketlike(abc.ABC):
+ def __init__(self, sock, data):
+ """This default method saves the socket in self.sock and creates self.buffer for getdata(). The data is discarded."""
+ self.sock = sock
+ self.buffer = b''
+
+ def getdata(self):
+ """This default method gets LF or CRLF separated lines from the socket and returns an array of completely-seen lines to the core.
+ This should work well for most line-based protocols (like IRC)."""
+ recvd = self.sock.recv(8192)
+ if recvd == b"": # EOF
+ if len(self.buffer) != 0:
+ # Process what's left in the buffer. We'll get called again after.
+ remaining_buf = self.buffer.decode('utf-8', 'backslashreplace')
+ self.buffer = b""
+ return [remaining_buf]
+ else:
+ # Nothing left in the buffer. Return None to signal the core to close this socket.
+ return None
+ self.buffer += recvd
+ lines = []
+
+ while b"\n" in self.buffer:
+ pieces = self.buffer.split(b"\n", 1)
+ s = pieces[0].decode('utf-8', 'backslashreplace').rstrip("\r")
+ lines.append(pieces[0].decode('utf-8', 'backslashreplace'))
+ self.buffer = pieces[1]
+
+ return lines
+
+ def __str__(self):
+ return '%s#%d' % (self.__class__.__name__, self.sock.fileno())
+ def __repr__(self):
+ return '<%s.%s #%d %s:%d>' % ((self.__class__.__module__, self.__class__.__name__, self.sock.fileno())+self.sock.getpeername())
+
+ @abc.abstractmethod
+ def parse(self, chunk): pass
+
+ @classmethod
+ def __subclasshook__(cls, C):
+ if cls is Socketlike:
+ if any('parse' in B.__dict__ and 'getdata' in B.__dict__ for B in C.__mro__):
+ return True
+ return NotImplemented
+
+class _ListenSocket(Socketlike):
+ def __init__(self, lib, sock, cls, data):
+ self.clients = []
+ self.lib = lib
+ self.sock = sock
+ self.cls = cls
+ self.data = data
+
+ def _make_closer(self, obj, client):
+ def close():
+ self.lib.parent.log(repr(self), '?', 'Closing child socket #%d' % (client.fileno()))
+ try:
+ obj.closing()
+ except AttributeError:
+ pass
+ self.lib.parent.delfd(client.fileno())
+ client.shutdown(socket.SHUT_RDWR)
+ client.close()
+ self.clients.remove((client,obj))
+ return close
+
+ def parse(self):
+ # getdata will never return a non-empty array, so parse will never be called; but Socketlike requires this method
+ pass
+
+ def getdata(self):
+ client, addr = self.sock.accept()
+ obj = self.cls(client, self.data)
+ obj.close = self._make_closer(obj, client)
+ self.lib.parent.log(repr(self), '?', 'New connection #%d from %s' % (client.fileno(), addr))
+ self.clients.append((client,obj))
+ self.lib.parent.newfd(obj, client.fileno())
+ return []
+
+ def close(self):
+ self.lib.parent.log(repr(self), '?', 'Socket closing')
+ if self.sock.fileno() != -1:
+ self.lib.parent.delfd(self.sock.fileno())
+ self.sock.shutdown(socket.SHUT_RDWR)
+ self.sock.close()
+ for client, obj in self.clients:
+ obj.close()
+
+ def __repr__(self): return '<_ListenSocket #%d>' % (self.sock.fileno())