hooke/command.py

   1 """The `command` module provides :class:`Command`\s and
   2 :class:`Argument`\s for defining commands.
   3 """
   4
   5 import Queue as queue
   6
   7
   8 class CommandExit (Exception):
   9     def __str__(self):
  10         return self.__class__.__name__
  11
  12 class Success (CommandExit):
  13     pass
  14
  15 class Failure (CommandExit):
  16     pass
  17
  18 class Command (object):
  19     """One-line command description here.
  20
  21     >>> c = Command(name='test', help='An example Command.')
  22     >>> status = c.run(NullQueue(), PrintQueue(), help=True) # doctest: +REPORT_UDIFF
  23     ITEM:
  24     Command: test
  25     <BLANKLINE>
  26     Arguments:
  27     help BOOL (bool) Print a help message.
  28     <BLANKLINE>
  29     An example Command.
  30     ITEM:
  31     Success
  32     """
  33     def __init__(self, name, aliases=None, arguments=[], help=''):
  34         self.name = name
  35         if aliases == None:
  36             aliases = []
  37         self.aliases = aliases
  38         self.arguments = [
  39             Argument(name='help', type='bool', default=False, count=1,
  40                      callback=StoreValue(True), help='Print a help message.'),
  41             ] + arguments
  42         self._help = help
  43
  44     def run(self, inqueue=None, outqueue=None, **kwargs):
  45         """`Normalize inputs and handle <Argument help> before punting
  46         to :meth:`_run`.
  47         """
  48         if inqueue == None:
  49             inqueue = NullQueue()
  50         if outqueue == None:
  51             outqueue = NullQueue()
  52         try:
  53             params = self.handle_arguments(inqueue, outqueue, kwargs)
  54             if params['help'] == True:
  55                 outqueue.put(self.help())
  56                 raise(Success())
  57             self._run(inqueue, outqueue, params)
  58         except CommandExit, e:
  59             if isinstance(e, Failure):
  60                 outqueue.put(e.message)
  61                 outqueue.put(e)
  62                 return 1
  63         outqueue.put(e)
  64         return 0
  65
  66     def _run(self, inqueue, outqueue, params):
  67         """This is where the command-specific magic will happen.
  68         """
  69         pass
  70
  71     def handle_arguments(self, inqueue, outqueue, params):
  72         """Normalize and validate input parameters (:class:`Argument` values).
  73         """
  74         for argument in self.arguments:
  75             names = [argument.name] + argument.aliases
  76             settings = [(name,v) for name,v in params.items() if name in names]
  77             if len(settings) == 0:
  78                 if argument.optional == True or argument.count == 0:
  79                     settings = [(argument.name, argument.default)]
  80                 else:
  81                     raise Failure('Required argument %s not set.'
  82                                   % argument.name)
  83             if len(settings) > 1:
  84                 raise Failure('Multiple settings for %s:\n  %s'
  85                     % (argument.name,
  86                        '\n  '.join(['%s: %s' % (name,value)
  87                                     for name,value in sorted(settings)])))
  88             name,value = settings[0]
  89             if name != argument.name:
  90                 params.remove(name)
  91                 params[argument.name] = value
  92             if argument.callback != None:
  93                 value = argument.callback(self, argument, value)
  94                 params[argument.name] = value
  95             argument.validate(value)
  96         return params
  97
  98     def help(self, *args):
  99         name_part = 'Command: %s' % self.name
 100         if len(self.aliases) > 0:
 101             name_part += ' (%s)' % ', '.join(self.aliases)
 102         parts = [name_part]
 103         if len(self.arguments) > 0:
 104             argument_part = ['Arguments:'] + [a.help() for a in self.arguments]
 105             argument_part = '\n'.join(argument_part)
 106             parts.append(argument_part)
 107         parts.append(self._help) # help part
 108         return '\n\n'.join(parts)
 109
 110 class Argument (object):
 111     """Structured user input for :class:`Command`\s.
 112
 113     TODO: ranges for `count`?
 114     """
 115     def __init__(self, name, aliases=None, type='string', metavar=None,
 116                  default=None, optional=True, count=1,
 117                  completion_callback=None, callback=None, help=''):
 118         self.name = name
 119         if aliases == None:
 120             aliases = []
 121         self.aliases = aliases
 122         self.type = type
 123         if metavar == None:
 124             metavar = type.upper()
 125         self.metavar = metavar
 126         self.default = default
 127         self.optional = optional
 128         self.count = count
 129         self.completion_callback = completion_callback
 130         self.callback = callback
 131         self._help = help
 132
 133     def __str__(self):
 134         return '<%s %s>' % (self.__class__.__name__, self.name)
 135
 136     def __repr__(self):
 137         return self.__str__()
 138
 139     def help(self):
 140         parts = ['%s ' % self.name]
 141         if self.metavar != None:
 142             parts.append('%s ' % self.metavar)
 143         parts.extend(['(%s) ' % self.type, self._help])
 144         return ''.join(parts)
 145
 146     def validate(self, value):
 147         """If `value` is not appropriate, raise `ValueError`.
 148         """
 149         pass # TODO: validation
 150
 151     # TODO: type conversion
 152
 153 # TODO: type extensions?
 154
 155 # Useful callbacks
 156
 157 class StoreValue (object):
 158     def __init__(self, value):
 159         self.value = value
 160     def __call__(self, command, argument, fragment=None):
 161         return self.value
 162
 163 class NullQueue (queue.Queue):
 164     """The :class:`queue.Queue` equivalent of `/dev/null`.
 165
 166     This is a bottomless pit.  Items go in, but never come out.
 167     """
 168     def get(self, block=True, timeout=None):
 169         """Raise queue.Empty.
 170
 171         There's really no need to override the base Queue.get, but I
 172         want to know if someone tries to read from a NullQueue.  With
 173         the default implementation they would just block silently
 174         forever :(.
 175         """
 176         raise queue.Empty
 177
 178     def put(self, item, block=True, timeout=None):
 179         """Dump an item into the void.
 180
 181         Block and timeout are meaningless, because there is always a
 182         free slot available in a bottomless pit.
 183         """
 184         pass
 185
 186 class PrintQueue (NullQueue):
 187     """Debugging :class:`NullQueue` that prints items before dropping
 188     them.
 189     """
 190     def put(self, item, block=True, timeout=None):
 191         """Print `item` and then dump it into the void.
 192         """
 193         print 'ITEM:\n%s' % item