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