1 """The plugin module provides optional submodules that add new Hooke
4 All of the science happens in here.
7 import ConfigParser as configparser
10 from ..config import Setting
11 from ..util.graph import Node, Graph
15 # ('curvetools', True),
18 # ('flatfilts-rolf', True),
19 # ('flatfilts', True),
20 # ('generalclamp', True),
21 # ('generaltccd', True),
22 # ('generalvclamp', True),
25 # ('massanalysis', True),
26 # ('multidistance', True),
29 # ('procplots', True),
31 # ('showconvoluted', True),
32 # ('superimpose', True),
36 """List of plugin modules and whether they should be included by
37 default. TODO: autodiscovery
43 """List of builtin modules. TODO: autodiscovery
47 # Plugins and settings
49 class Plugin (object):
50 """A pluggable collection of Hooke commands.
52 Fulfills the same role for Hooke that a software package does for
55 def __init__(self, name):
57 self.setting_section = '%s plugin' % self.name
60 def dependencies(self):
61 """Return a list of :class:`Plugin`\s we require."""
64 def default_settings(self):
65 """Return a list of :class:`hooke.config.Setting`\s for any
66 configurable plugin settings.
68 The suggested section setting is::
70 Setting(section=self.setting_section, help=self.__doc__)
75 """Return a list of :class:`Commands` provided."""
78 class Builtin (Plugin):
79 """A required collection of Hooke commands.
81 These "core" plugins provide essential administrative commands
82 (playlist handling, etc.).
86 # Commands and arguments
88 class CommandExit (Exception):
90 return self.__class__.__name__
92 class Success (CommandExit):
95 class Failure (CommandExit):
98 class Command (object):
99 """One-line command description here.
101 >>> c = Command(name='test', help='An example Command.')
102 >>> status = c.run(NullQueue(), PrintQueue(), help=True) # doctest: +REPORT_UDIFF
107 help BOOL (bool) Print a help message.
113 def __init__(self, name, aliases=None, arguments=[], help=''):
117 self.aliases = aliases
119 Argument(name='help', type='bool', default=False, count=1,
120 callback=StoreValue(True), help='Print a help message.'),
124 def run(self, inqueue=None, outqueue=None, **kwargs):
125 """`Normalize inputs and handle <Argument help> before punting
129 inqueue = NullQueue()
131 outqueue = NullQueue()
133 params = self.handle_arguments(inqueue, outqueue, kwargs)
134 if params['help'] == True:
135 outqueue.put(self.help())
137 self._run(inqueue, outqueue, params)
138 except CommandExit, e:
139 if isinstance(e, Failure):
140 outqueue.put(e.message)
146 def _run(self, inqueue, outqueue, params):
147 """This is where the command-specific magic will happen.
151 def handle_arguments(self, inqueue, outqueue, params):
152 """Normalize and validate input parameters (:class:`Argument` values).
154 for argument in self.arguments:
155 names = [argument.name] + argument.aliases
156 settings = [(name,v) for name,v in params.items() if name in names]
157 if len(settings) == 0:
158 if argument.optional == True or argument.count == 0:
159 settings = [(argument.name, argument.default)]
161 raise Failure('Required argument %s not set.'
163 if len(settings) > 1:
164 raise Failure('Multiple settings for %s:\n %s'
166 '\n '.join(['%s: %s' % (name,value)
167 for name,value in sorted(settings)])))
168 name,value = settings[0]
169 if name != argument.name:
171 params[argument.name] = value
172 if argument.callback != None:
173 value = argument.callback(self, argument, value)
174 params[argument.name] = value
175 argument.validate(value)
178 def help(self, *args):
179 name_part = 'Command: %s' % self.name
180 if len(self.aliases) > 0:
181 name_part += ' (%s)' % ', '.join(self.aliases)
182 argument_part = ['Arguments:'] + [a.help() for a in self.arguments]
183 argument_part = '\n'.join(argument_part)
184 help_part = self._help
185 return '\n\n'.join([name_part, argument_part, help_part])
187 class Argument (object):
188 """Structured user input for :class:`Command`\s.
190 TODO: ranges for `count`?
192 def __init__(self, name, aliases=None, type='string', metavar=None,
193 default=None, optional=True, count=1,
194 completion_callback=None, callback=None, help=''):
198 self.aliases = aliases
201 metavar = type.upper()
202 self.metavar = metavar
203 self.default = default
204 self.optional = optional
206 self.completion_callback = completion_callback
207 self.callback = callback
211 return '<%s %s>' % (self.__class__.__name__, self.name)
214 return self.__str__()
217 parts = ['%s ' % self.name]
218 if self.metavar != None:
219 parts.append('%s ' % self.metavar)
220 parts.extend(['(%s) ' % self.type, self._help])
221 return ''.join(parts)
223 def validate(self, value):
224 """If `value` is not appropriate, raise `ValueError`.
226 pass # TODO: validation
228 # TODO: type conversion
230 # TODO: type extensions?
234 class StoreValue (object):
235 def __init__(self, value):
237 def __call__(self, command, argument, fragment=None):
240 class NullQueue (queue.Queue):
241 """The :class:`queue.Queue` equivalent of `/dev/null`.
243 This is a bottomless pit. Items go in, but never come out.
245 def get(self, block=True, timeout=None):
246 """Raise queue.Empty.
248 There's really no need to override the base Queue.get, but I
249 want to know if someone tries to read from a NullQueue. With
250 the default implementation they would just block silently
255 def put(self, item, block=True, timeout=None):
256 """Dump an item into the void.
258 Block and timeout are meaningless, because there is always a
259 free slot available in a bottomless pit.
263 class PrintQueue (NullQueue):
264 """Debugging :class:`NullQueue` that prints items before dropping
267 def put(self, item, block=True, timeout=None):
268 """Print `item` and then dump it into the void.
270 print 'ITEM:\n%s' % item
273 # Construct plugin dependency graph and load plugin instances.
275 def construct_graph(this_modname, submodnames, class_selector,
276 assert_name_match=True):
277 """Search the submodules `submodnames` of a module `this_modname`
278 for class objects for which `class_selector(class)` returns
279 `True`. These classes are instantiated, and the `instance.name`
280 is compared to the `submodname` (if `assert_name_match` is
283 The instances are further arranged into a dependency
284 :class:`hooke.util.graph.Graph` according to their
285 `instance.dependencies()` values. The topologically sorted graph
289 for submodname in submodnames:
290 count = len([s for s in submodnames if s == submodname])
291 assert count > 0, 'No %s entries: %s' % (submodname, submodnames)
292 assert count == 1, 'Multiple (%d) %s entries: %s' \
293 % (count, submodname, submodnames)
294 this_mod = __import__(this_modname, fromlist=[submodname])
295 submod = getattr(this_mod, submodname)
296 for objname in dir(submod):
297 obj = getattr(submod, objname)
298 if class_selector(obj):
300 if assert_name_match == True and instance.name != submodname:
302 'Instance name %s does not match module name %s'
303 % (instance.name, submodname))
304 instances[instance.name] = instance
305 graph = Graph([Node([instances[name] for name in i.dependencies()],
307 for i in instances.values()])
308 graph.topological_sort()
311 class IsSubclass (object):
312 """A safe subclass comparator.
317 >>> class A (object):
322 >>> is_subclass = IsSubclass(A)
325 >>> is_subclass = IsSubclass(A, blacklist=[A])
333 def __init__(self, base_class, blacklist=None):
334 self.base_class = base_class
335 if blacklist == None:
337 self.blacklist = blacklist
338 def __call__(self, other):
340 subclass = issubclass(other, self.base_class)
343 if other in self.blacklist:
347 PLUGIN_GRAPH = construct_graph(
348 this_modname=__name__,
349 submodnames=[name for name,include in PLUGIN_MODULES] + BUILTIN_MODULES,
350 class_selector=IsSubclass(Plugin, blacklist=[Plugin, Builtin]))
351 """Topologically sorted list of all possible :class:`Plugin`\s and
355 def default_settings():
357 'plugins', help='Enable/disable default plugins.')]
358 for pnode in PLUGIN_GRAPH:
359 if pnode.data.name in BUILTIN_MODULES:
360 continue # builtin inclusion is not optional
362 default_include = [di for mod_name,di in PLUGIN_MODULES
363 if mod_name == plugin.name][0]
364 help = 'Commands: ' + ', '.join([c.name for c in plugin.commands()])
365 settings.append(Setting(
368 value=str(default_include),
371 for pnode in PLUGIN_GRAPH:
373 settings.extend(plugin.default_settings())
376 def load_graph(graph, config, include_section):
381 include = config.getboolean(include_section, item.name)
382 except configparser.NoOptionError:
383 include = True # non-optional include (e.g. a Builtin)
387 config.items(item.setting_section))
388 except configparser.NoSectionError: