hooke/plugin/__init__.py

   1 """The plugin module provides optional submodules that add new Hooke
   2 commands.
   3
   4 All of the science happens in here.
   5 """
   6
   7 import os.path
   8 import Queue as queue
   9
  10 from ..config import Setting
  11 from ..util.graph import Node, Graph
  12
  13 PLUGIN_MODULES = [
  14 #    ('autopeak', True),
  15 #    ('curvetools', True),
  16 #    ('cut', True),
  17 #    ('fit', True),
  18 #    ('flatfilts-rolf', True),
  19 #    ('flatfilts', True),
  20 #    ('generalclamp', True),
  21 #    ('generaltccd', True),
  22 #    ('generalvclamp', True),
  23 #    ('jumpstat', True),
  24 #    ('macro', True),
  25 #    ('massanalysis', True),
  26 #    ('multidistance', True),
  27 #    ('multifit', True),
  28 #    ('pcluster', True),
  29 #    ('procplots', True),
  30 #    ('review', True),
  31 #    ('showconvoluted', True),
  32 #    ('superimpose', True),
  33 #    ('tutorial', True),
  34 #    ('viewer', True),
  35     ]
  36 """List of plugin modules and whether they should be included by
  37 default.  TODO: autodiscovery
  38 """
  39
  40 # Plugins and settings
  41
  42 def Plugin (object):
  43     """The pluggable collection of Hooke commands.
  44
  45     Fulfills the same role for Hooke that a software package does for
  46     an operating system.
  47     """
  48     def __init__(self, name):
  49         self.name = name
  50
  51     def dependencies(self):
  52         """Return a list of Plugins we require."""
  53         return []
  54
  55     def default_settings(self):
  56         """Return a list of hooke.config.Settings() for any
  57         configurable module settings."""
  58         return []
  59
  60     def commands(self):
  61         """Return a list of Commands provided."""
  62         return []
  63
  64 PLUGINS = {}
  65 """(name,instance) :class:`dict` of all possible :class:`Plugin`\s.
  66 """
  67
  68 print __name__
  69 for plugin_modname,value in PLUGIN_MODULES:
  70     this_mod = __import__(__name__, fromlist=[plugin_modname])
  71     plugin_mod = getattr(this_mod, plugin_modname)
  72     for objname in dir(plugin_mod):
  73         obj = getattr(plugin_mod, objname)
  74         if type(obj) == Plugin:
  75             obj.module_name = plugin_modname
  76             PLUGINS[p.name] = p
  77
  78 PLUGIN_GRAPH = Graph([Node([PLUGINS[name] for name in p.dependencies()])
  79                       for p in PLUGINS.values()])
  80 PLUGIN_GRAPH.topological_sort()
  81
  82
  83 def default_settings(self):
  84     settings = [Setting(
  85             'plugins', help='Enable/disable default plugins.')]
  86     for pnode in PLUGIN_GRAPH:
  87         settings.append(Setting(p.name, str(PLUGIN_MODULES[p.module_name][1])))
  88     for pnode in PLUGIN_GRAPH:
  89         plugin = pnode.data
  90         settings.extend(plugin.default_settings())
  91     return settings
  92
  93
  94 # Commands and arguments
  95
  96 class CommandExit (Exception):
  97     def __str__(self):
  98         return self.__class__.__name__
  99
 100 class Success (CommandExit):
 101     pass
 102
 103 class Failure (CommandExit):
 104     pass
 105
 106 class Command (object):
 107     """One-line command description here.
 108
 109     >>> c = Command(name='test', help='An example Command.')
 110     >>> status = c.run(NullQueue(), PrintQueue(), help=True)
 111     ITEM:
 112     Command: test
 113     <BLANKLINE>
 114     Arguments:
 115     help HELP (bool) Print a help message.
 116     <BLANKLINE>
 117     An example Command.
 118     ITEM:
 119     Success
 120     """
 121     def __init__(self, name, aliases=None, arguments=[], help=''):
 122         self.name = name
 123         if aliases == None:
 124             aliases = []
 125         self.aliases = aliases
 126         self.arguments = [
 127             Argument(name='help', type='bool', default=False, count=1,
 128                      callback=StoreValue(True), help='Print a help message.'),
 129             ] + arguments
 130         self._help = help
 131
 132     def run(self, inqueue=None, outqueue=None, **kwargs):
 133         """`Normalize inputs and handle <Argument help> before punting
 134         to :meth:`_run`.
 135         """
 136         if inqueue == None:
 137             inqueue = NullQueue()
 138         if outqueue == None:
 139             outqueue = NullQueue()
 140         try:
 141             params = self.handle_arguments(inqueue, outqueue, kwargs)
 142             if params['help'] == True:
 143                 outqueue.put(self.help())
 144                 raise(Success())
 145             self._run(inqueue, outqueue, params)
 146         except CommandExit, e:
 147             if isinstance(e, Failure):
 148                 outqueue.put(e.message)
 149                 outqueue.put(e)
 150                 return 1
 151         outqueue.put(e)
 152         return 0
 153
 154     def _run(self, inqueue, outqueue, params):
 155         """This is where the command-specific magic will happen.
 156         """
 157         pass
 158
 159     def handle_arguments(self, inqueue, outqueue, params):
 160         """Normalize and validate input parameters (:class:`Argument` values).
 161         """
 162         for argument in self.arguments:
 163             names = [argument.name] + argument.aliases
 164             settings = [(name,v) for name,v in params.items() if name in names]
 165             if len(settings) == 0:
 166                 if argument.optional == True or argument.count == 0:
 167                     settings = [(argument.name, argument.default)]
 168                 else:
 169                     raise Failure('Required argument %s not set.'
 170                                   % argument.name)
 171             if len(settings) > 1:
 172                 raise Failure('Multiple settings for %s:\n  %s'
 173                     % (argument.name,
 174                        '\n  '.join(['%s: %s' % (name,value)
 175                                     for name,value in sorted(settings)])))
 176             name,value = settings[0]
 177             if name != argument.name:
 178                 params.remove(name)
 179                 params[argument.name] = value
 180             if argument.callback != None:
 181                 value = argument.callback(self, argument, value)
 182                 params[argument.name] = value
 183             argument.validate(value)
 184         return params
 185
 186     def help(self, *args):
 187         name_part = 'Command: %s' % self.name
 188         if len(self.aliases) > 0:
 189             name_part += ' (%s)' % ', '.join(self.aliases)
 190         argument_part = ['Arguments:'] + [a.help() for a in self.arguments]
 191         argument_part = '\n'.join(argument_part)
 192         help_part = self._help
 193         return '\n\n'.join([name_part, argument_part, help_part])
 194
 195 class Argument (object):
 196     """Structured user input for :class:`Command`\s.
 197
 198     TODO: ranges for `count`?
 199     """
 200     def __init__(self, name, aliases=None, type='string', metavar=None,
 201                  default=None, optional=True, count=1,
 202                  completion_callback=None, callback=None, help=''):
 203         self.name = name
 204         if aliases == None:
 205             aliases = []
 206         self.aliases = aliases
 207         self.type = type
 208         if metavar == None:
 209             metavar = type.upper()
 210         self.metavar = metavar
 211         self.default = default
 212         self.optional = optional
 213         self.count = count
 214         self.completion_callback = completion_callback
 215         self.callback = callback
 216         self._help = help
 217
 218     def __str__(self):
 219         return '<%s %s>' % (self.__class__.__name__, self.name)
 220
 221     def __repr__(self):
 222         return self.__str__()
 223
 224     def help(self):
 225         parts = ['%s ' % self.name]
 226         if self.metavar != None:
 227             parts.append('%s ' % self.metavar)
 228         parts.extend(['(%s) ' % self.type, self._help])
 229         return ''.join(parts)
 230
 231     def validate(self, value):
 232         """If `value` is not appropriate, raise `ValueError`.
 233         """
 234         pass # TODO: validation
 235
 236     # TODO: type conversion
 237
 238 # TODO: type extensions?
 239
 240 # Useful callbacks
 241
 242 class StoreValue (object):
 243     def __init__(self, value):
 244         self.value = value
 245     def __call__(self, command, argument, fragment=None):
 246         return self.value
 247
 248 class NullQueue (queue.Queue):
 249     """The :class:`queue.Queue` equivalent of `/dev/null`.
 250
 251     This is a bottomless pit.  Items go in, but never come out.
 252     """
 253     def get(self, block=True, timeout=None):
 254         """Raise queue.Empty.
 255
 256         There's really no need to override the base Queue.get, but I
 257         want to know if someone tries to read from a NullQueue.  With
 258         the default implementation they would just block silently
 259         forever :(.
 260         """
 261         raise queue.Empty
 262
 263     def put(self, item, block=True, timeout=None):
 264         """Dump an item into the void.
 265
 266         Block and timeout are meaningless, because there is always a
 267         free slot available in a bottomless pit.
 268         """
 269         pass
 270
 271 class PrintQueue (NullQueue):
 272     """Debugging :class:`NullQueue` that prints items before dropping
 273     them.
 274     """
 275     def put(self, item, block=True, timeout=None):
 276         """Print `item` and then dump it into the void.
 277         """
 278         print 'ITEM:\n%s' % item