modlib.py

   1 # Erebus IRC bot - Author: John Runyon
   2 # vim: fileencoding=utf-8
   3 # module helper functions, see modules/modtest.py for usage
   4 # This file is released into the public domain; see http://unlicense.org/
   5
   6 import sys
   7 from functools import wraps
   8
   9 if sys.version_info.major < 3:
  10         stringbase = basestring
  11 else:
  12         stringbase = str
  13
  14 """Used to return an error to the bot core."""
  15 class error(object):
  16         def __init__(self, desc):
  17                 self.errormsg = desc
  18         def __nonzero__(self):
  19                 return False #object will test to False
  20         __bool__ = __nonzero__ #py3 compat
  21         def __repr__(self):
  22                 return '<modlib.error %r>' % self.errormsg
  23         def __str__(self):
  24                 return str(self.errormsg)
  25
  26 class modlib(object):
  27         # default (global) access levels
  28         OWNER   = 100
  29         MANAGER =  99
  30         ADMIN   =  75
  31         STAFF   =  50
  32         KNOWN   =   1
  33         AUTHED  =   0 # Users which have are known to be authed
  34         ANYONE  =  -1 # non-authed users have glevel set to -1
  35         IGNORED =  -2 # The default reqglevel is ANYONE, so any commands will be ignored from IGNORED users unless the command reglevel=-2
  36         glevs   = {
  37                 'OWNER': OWNER,
  38                 'MANAGER': MANAGER,
  39                 'ADMIN': ADMIN,
  40                 'STAFF': STAFF,
  41                 'KNOWN': KNOWN,
  42                 'AUTHED': AUTHED,
  43                 'ANYONE': ANYONE,
  44                 'IGNORED': IGNORED,
  45         }
  46
  47         # (channel) access levels
  48         COWNER  =   5
  49         MASTER  =   4
  50         OP      =   3
  51         VOICE   =   2
  52         #KNOWN  =   1 is set above by glevels
  53         PUBLIC  =   0 # Anyone (use glevel to control whether auth is needed)
  54         BANNED  =  -1 # The default reqclevel is PUBLIC, so any commands which needchan will be ignored from BANNED users unless the command reqclevel=-1
  55         #         [   0         1        2     3         4        5    -1]
  56         clevs   = [None, 'Friend', 'Voice', 'Op', 'Master', 'Owner', None]
  57
  58         # messages
  59         WRONGARGS = "Wrong number of arguments."
  60
  61         def __init__(self, name):
  62                 self.hooks = {}
  63                 self.chanhooks = {}
  64                 self.exceptionhooks = []
  65                 self.numhooks = {}
  66                 self.helps = []
  67                 self.parent = None
  68
  69                 self.name = (name.split("."))[-1]
  70
  71         def modstart(self, parent):
  72                 #modstart can return a few things...
  73                 # None: unspecified success
  74                 # False: unspecified error
  75                 # modlib.error (or anything else False-y): specified error
  76                 # True: unspecified success
  77                 # non-empty string (or anything else True-y): specified success
  78                 #"specified" values will be printed. unspecified values will result in "OK" or "failed"
  79                 self.parent = parent
  80                 for cmd, func in self.hooks.items():
  81                         parent.hook(cmd, func)
  82                         parent.hook("%s.%s" % (self.name, cmd), func)
  83                 for chan, func in self.chanhooks.items():
  84                         parent.hookchan(chan, func)
  85                 for exc, func in self.exceptionhooks:
  86                         parent.hookexception(exc, func)
  87                 for num, func in self.numhooks.items():
  88                         parent.hooknum(num, func)
  89
  90                 for func, args, kwargs in self.helps:
  91                         try:
  92                                 self.mod('help').reghelp(func, *args, **kwargs)
  93                         except:
  94                                 pass
  95                 return True
  96         def modstop(self, parent):
  97                 for cmd, func in self.hooks.items():
  98                         parent.unhook(cmd, func)
  99                         parent.unhook("%s.%s" % (self.name, cmd), func)
 100                 for chan, func in self.chanhooks.items():
 101                         parent.unhookchan(chan, func)
 102                 for exc, func in self.exceptionhooks:
 103                         parent.unhookexception(exc, func)
 104                 for num, func in self.numhooks.items():
 105                         parent.unhooknum(num, func)
 106
 107                 for func, args, kwargs in self.helps:
 108                         try:
 109                                 self.mod('help').dereghelp(func, *args, **kwargs)
 110                         except:
 111                                 pass
 112                 return True
 113
 114         def hook(self, cmd=None, needchan=True, glevel=ANYONE, clevel=PUBLIC, wantchan=None):
 115                 if wantchan is None: wantchan = needchan
 116                 _cmd = cmd #save this since it gets wiped out...
 117                 def realhook(func):
 118                         cmd = _cmd #...and restore it
 119                         if cmd is None:
 120                                 cmd = func.__name__ # default to function name
 121                         if isinstance(cmd, stringbase):
 122                                 cmd = (cmd,)
 123
 124                         if clevel > self.PUBLIC and not needchan:
 125                                 raise Exception('clevel must be left at default if needchan is False')
 126
 127                         func.needchan = needchan
 128                         func.wantchan = wantchan
 129                         func.reqglevel = glevel
 130                         func.reqclevel = clevel
 131                         func.cmd = cmd
 132                         func.module = func.__module__.split('.')[1]
 133
 134                         for c in cmd:
 135                                 self.hooks[c] = func
 136                                 if self.parent is not None:
 137                                         self.parent.hook(c, func)
 138                                         self.parent.hook("%s.%s" % (self.name, c), func)
 139                         return func
 140                 return realhook
 141
 142         def hookchan(self, chan, glevel=ANYONE, clevel=PUBLIC):
 143                 def realhook(func):
 144                         self.chanhooks[chan] = func
 145                         if self.parent is not None:
 146                                 self.parent.hookchan(chan, func)
 147                         return func
 148                 return realhook
 149
 150         def hookexception(self, exc):
 151                 def realhook(func):
 152                         self.exceptionhooks.append((exc, func))
 153                         if self.parent is not None:
 154                                 self.parent.hookexception(exc, func)
 155                         return func
 156                 return realhook
 157
 158         def hooknum(self, num):
 159                 def realhook(func):
 160                         self.numhooks[str(num)] = func
 161                         if self.parent is not None:
 162                                 self.parent.hooknum(str(num), func)
 163                         return func
 164                 return realhook
 165
 166         def mod(self, modname):
 167                 if self.parent is not None:
 168                         return self.parent.module(modname)
 169                 else:
 170                         return error('unknown parent')
 171
 172         def argsEQ(self, num):
 173                 def realhook(func):
 174                         @wraps(func)
 175                         def checkargs(bot, user, chan, realtarget, *args):
 176                                 if len(args) == num:
 177                                         return func(bot, user, chan, realtarget, *args)
 178                                 else:
 179                                         bot.msg(user, self.WRONGARGS)
 180                         return checkargs
 181                 return realhook
 182
 183         def argsGE(self, num):
 184                 def realhook(func):
 185                         @wraps(func)
 186                         def checkargs(bot, user, chan, realtarget, *args):
 187                                 if len(args) >= num:
 188                                         return func(bot, user, chan, realtarget, *args)
 189                                 else:
 190                                         bot.msg(user, self.WRONGARGS)
 191                         return checkargs
 192                 return realhook
 193
 194         def help(self, *args, **kwargs):
 195                 """help(syntax, shorthelp, longhelp?, more lines longhelp?, cmd=...?)
 196                 Example:
 197                 help("<user> <pass>", "login")
 198                         ^ Help will only be one line. Command name determined based on function name.
 199                 help("<user> <level>", "add a user", cmd=("adduser", "useradd"))
 200                         ^ Help will be listed under ADDUSER; USERADD will say "alias for adduser"
 201                 help(None, "do stuff", "This command is really complicated.")
 202                         ^ Command takes no args. Short description (in overall HELP listing) is "do stuff".
 203                         Long description (HELP <command>) will say "<command> - do stuff", newline, "This command is really complicated."
 204                 """
 205                 def realhook(func):
 206                         if self.parent is not None:
 207                                 try:
 208                                         self.mod('help').reghelp(func, *args, **kwargs)
 209                                 except:
 210                                         pass
 211                         self.helps.append((func, args, kwargs))
 212                         return func
 213                 return realhook