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 sys
   7 import textwrap
   8 import traceback
   9
  10
  11 class CommandExit (Exception):
  12     pass
  13
  14 class Success (CommandExit):
  15     pass
  16
  17 class Exit (Success):
  18     """The command requests an end to the interpreter session.
  19     """
  20     pass
  21
  22 class Failure (CommandExit):
  23     pass
  24
  25 class UncaughtException (Failure):
  26     def __init__(self, exception, traceback_string=None):
  27         super(UncaughtException, self).__init__()
  28         if traceback_string == None:
  29             traceback_string = traceback.format_exc()
  30             sys.exc_clear()
  31         self.exception = exception
  32         self.traceback = traceback_string
  33         self.__setstate__(self.__getstate__())
  34
  35     def __getstate__(self):
  36         """Return a picklable representation of the objects state.
  37
  38         :mod:`pickle`'s doesn't call a :meth:`__init__` when
  39         rebuilding a class instance.  To preserve :attr:`args` through
  40         a pickle cycle, we use :meth:`__getstate__` and
  41         :meth:`__setstate__`.
  42
  43         See `pickling class instances`_ and `pickling examples`_.
  44
  45         .. _pickling class instances:
  46           http://docs.python.org/library/pickle.html#pickling-and-unpickling-normal-class-instances
  47         .. _pickling examples:
  48           http://docs.python.org/library/pickle.html#example
  49         """
  50         return {'exception':self.exception, 'traceback':self.traceback}
  51
  52     def __setstate__(self, state):
  53         """Apply the picklable state from :meth:`__getstate__` to
  54         reconstruct the instance.
  55         """
  56         for key,value in state.items():
  57             setattr(self, key, value)
  58         self.args = (self.traceback + str(self.exception),)
  59
  60 class InList (list):
  61     """:class:`Request` validator class.
  62
  63     Examples
  64     --------
  65
  66     >>> i = InList(['abc', 'def', 5, True])
  67     >>> i('abc')
  68     >>> i(5)
  69     >>> i(False)
  70     Traceback (most recent call last):
  71       ...
  72     ValueError: False
  73     """
  74     def __init__(self, *args, **kwargs):
  75         list.__init__(self, *args, **kwargs)
  76
  77     def __call__(self, value):
  78         """Raises ValueError if a given `value` is not in our internal
  79         list.
  80         """
  81         if value not in self:
  82             raise ValueError(value)
  83
  84 class Interaction (object):
  85     """Mid-command inter-process interaction.
  86
  87     Stores :attr:`type`, a string representing the interaction type
  88     ('boolean', 'string', ...).
  89     """
  90     def __init__(self, type):
  91         self.type = type
  92
  93 class Request (Interaction):
  94     """Command engine requests for information from the UI.
  95     """
  96     def __init__(self, type, response_class,
  97                  msg, default=None, validator=None):
  98         super(Request, self).__init__(type)
  99         self.response_class = response_class
 100         self.msg = msg
 101         self.default = default
 102         self.validator = validator
 103
 104     def response(self, value):
 105         if self.validator != None:
 106             self.validator(value)
 107         return self.response_class(value)
 108
 109 class Response (Interaction):
 110     """UI response to a :class:`Request`.
 111     """
 112     def __init__(self, type, value):
 113         super(Response, self).__init__(type)
 114         self.value = value
 115
 116 class BooleanRequest (Request):
 117     def __init__(self, msg, default=None):
 118         super(BooleanRequest, self).__init__(
 119             'boolean', BooleanResponse, msg, default,
 120             validator = InList([True, False, default]))
 121
 122 class BooleanResponse (Response):
 123     def __init__(self, value):
 124         super(BooleanResponse, self).__init__('boolean', value)
 125
 126 class StringRequest (Request):
 127     def __init__(self, msg, default=None):
 128         super(StringRequest, self).__init__(
 129             'string', StringResponse, msg, default)
 130
 131 class StringResponse (Response):
 132     def __init__(self, value):
 133         super(StringResponse, self).__init__('string', value)
 134
 135 class FloatRequest (Request):
 136     def __init__(self, msg, default=None):
 137         super(FloatRequest, self).__init__(
 138             'float', FloatResponse, msg, default)
 139
 140 class FloatResponse (Response):
 141     def __init__(self, value):
 142         super(FloatResponse, self).__init__('float', value)
 143
 144 class SelectionRequest (Request):
 145     def __init__(self, msg, default=None, options=[]):
 146         super(SelectionRequest, self).__init__(
 147             'selection', SelectionResponse, msg, default)
 148         self.options = options
 149
 150 class SelectionResponse (Response):
 151     def __init__(self, value):
 152         super(SelectionResponse, self).__init__('selection', value)
 153
 154
 155 class Command (object):
 156     """One-line command description here.
 157
 158     >>> c = Command(name='test', help='An example Command.')
 159     >>> hooke = None
 160     >>> status = c.run(hooke, NullQueue(), PrintQueue(),
 161     ...                help=True) # doctest: +REPORT_UDIFF
 162     ITEM:
 163     Command: test
 164     <BLANKLINE>
 165     Arguments:
 166     <BLANKLINE>
 167     help BOOL (bool) Print a help message.
 168     <BLANKLINE>
 169     An example Command.
 170     ITEM:
 171     <BLANKLINE>
 172     """
 173     def __init__(self, name, aliases=None, arguments=[], help=''):
 174         self.name = name
 175         if aliases == None:
 176             aliases = []
 177         self.aliases = aliases
 178         self.arguments = [
 179             Argument(name='help', type='bool', default=False, count=1,
 180                      callback=StoreValue(True), help='Print a help message.'),
 181             ] + arguments
 182         self._help = help
 183
 184     def run(self, hooke, inqueue=None, outqueue=None, **kwargs):
 185         """`Normalize inputs and handle <Argument help> before punting
 186         to :meth:`_run`.
 187         """
 188         if inqueue == None:
 189             inqueue = NullQueue()
 190         if outqueue == None:
 191             outqueue = NullQueue()
 192         try:
 193             params = self.handle_arguments(hooke, inqueue, outqueue, kwargs)
 194             if params['help'] == True:
 195                 outqueue.put(self.help())
 196                 raise(Success())
 197             self._run(hooke, inqueue, outqueue, params)
 198         except CommandExit, e:
 199             if isinstance(e, Failure):
 200                 outqueue.put(e)
 201                 return 1
 202             # other CommandExit subclasses fall through to the end
 203         except Exception, e:
 204             x = UncaughtException(e)
 205             outqueue.put(x)
 206             return 1
 207         else:
 208             e = Success()
 209         outqueue.put(e)
 210         return 0
 211
 212     def _run(self, inqueue, outqueue, params):
 213         """This is where the command-specific magic will happen.
 214         """
 215         pass
 216
 217     def handle_arguments(self, hooke, inqueue, outqueue, params):
 218         """Normalize and validate input parameters (:class:`Argument` values).
 219         """
 220         for argument in self.arguments:
 221             names = [argument.name] + argument.aliases
 222             settings = [(name,v) for name,v in params.items() if name in names]
 223             num_provided = len(settings)
 224             if num_provided == 0:
 225                 if argument.optional == True or argument.count == 0:
 226                     settings = [(argument.name, argument.default)]
 227                 else:
 228                     raise Failure('Required argument %s not set.'
 229                                   % argument.name)
 230             if num_provided > 1:
 231                 raise Failure('Multiple settings for %s:\n  %s'
 232                     % (argument.name,
 233                        '\n  '.join(['%s: %s' % (name,value)
 234                                     for name,value in sorted(settings)])))
 235             name,value = settings[0]
 236             if num_provided == 0:
 237                 params[argument.name] = value
 238             else:
 239                 if name != argument.name:
 240                     params.remove(name)
 241                     params[argument.name] = value
 242                 if argument.callback != None:
 243                     value = argument.callback(hooke, self, argument, value)
 244                     params[argument.name] = value
 245             argument.validate(value)
 246         return params
 247
 248     def help(self, name_fn=lambda name:name):
 249         """Return a help message describing the `Command`.
 250
 251         `name_fn(internal_name) -> external_name` gives calling
 252         :class:`hooke.ui.UserInterface`\s a means of changing the
 253         display names if it wants (e.g. to remove spaces from command
 254         line tokens).
 255         """
 256         name_part = 'Command: %s' % name_fn(self.name)
 257         if len(self.aliases) > 0:
 258             name_part += ' (%s)' % ', '.join(
 259                 [name_fn(n) for n in self.aliases])
 260         parts = [name_part]
 261         if len(self.arguments) > 0:
 262             argument_part = ['Arguments:', '']
 263             for a in self.arguments:
 264                 argument_part.append(textwrap.fill(
 265                         a.help(name_fn),
 266                         initial_indent="",
 267                         subsequent_indent="    "))
 268             argument_part = '\n'.join(argument_part)
 269             parts.append(argument_part)
 270         parts.append(self._help) # help part
 271         return '\n\n'.join(parts)
 272
 273 class Argument (object):
 274     """Structured user input for :class:`Command`\s.
 275
 276     TODO: ranges for `count`?
 277     """
 278     def __init__(self, name, aliases=None, type='string', metavar=None,
 279                  default=None, optional=True, count=1,
 280                  completion_callback=None, callback=None, help=''):
 281         self.name = name
 282         if aliases == None:
 283             aliases = []
 284         self.aliases = aliases
 285         self.type = type
 286         if metavar == None:
 287             metavar = type.upper()
 288         self.metavar = metavar
 289         self.default = default
 290         self.optional = optional
 291         self.count = count
 292         self.completion_callback = completion_callback
 293         self.callback = callback
 294         self._help = help
 295
 296     def __str__(self):
 297         return '<%s %s>' % (self.__class__.__name__, self.name)
 298
 299     def __repr__(self):
 300         return self.__str__()
 301
 302     def help(self, name_fn=lambda name:name):
 303         """Return a help message describing the `Argument`.
 304
 305         `name_fn(internal_name) -> external_name` gives calling
 306         :class:`hooke.ui.UserInterface`\s a means of changing the
 307         display names if it wants (e.g. to remove spaces from command
 308         line tokens).
 309         """
 310         parts = ['%s ' % name_fn(self.name)]
 311         if self.metavar != None:
 312             parts.append('%s ' % self.metavar)
 313         parts.extend(['(%s) ' % self.type, self._help])
 314         return ''.join(parts)
 315
 316     def validate(self, value):
 317         """If `value` is not appropriate, raise `ValueError`.
 318         """
 319         pass # TODO: validation
 320
 321     # TODO: type conversion
 322
 323 # TODO: type extensions?
 324
 325 # Useful callbacks
 326
 327 class StoreValue (object):
 328     def __init__(self, value):
 329         self.value = value
 330     def __call__(self, hooke, command, argument, fragment=None):
 331         return self.value
 332
 333 class NullQueue (queue.Queue):
 334     """The :class:`queue.Queue` equivalent of `/dev/null`.
 335
 336     This is a bottomless pit.  Items go in, but never come out.
 337     """
 338     def get(self, block=True, timeout=None):
 339         """Raise queue.Empty.
 340
 341         There's really no need to override the base Queue.get, but I
 342         want to know if someone tries to read from a NullQueue.  With
 343         the default implementation they would just block silently
 344         forever :(.
 345         """
 346         raise queue.Empty
 347
 348     def put(self, item, block=True, timeout=None):
 349         """Dump an item into the void.
 350
 351         Block and timeout are meaningless, because there is always a
 352         free slot available in a bottomless pit.
 353         """
 354         pass
 355
 356 class PrintQueue (NullQueue):
 357     """Debugging :class:`NullQueue` that prints items before dropping
 358     them.
 359     """
 360     def put(self, item, block=True, timeout=None):
 361         """Print `item` and then dump it into the void.
 362         """
 363         print 'ITEM:\n%s' % item