hooke/engine.py

   1 # Copyright (C) 2010-2012 W. Trevor King <wking@tremily.us>
   2 #
   3 # This file is part of Hooke.
   4 #
   5 # Hooke is free software: you can redistribute it and/or modify it under the
   6 # terms of the GNU Lesser General Public License as published by the Free
   7 # Software Foundation, either version 3 of the License, or (at your option) any
   8 # later version.
   9 #
  10 # Hooke is distributed in the hope that it will be useful, but WITHOUT ANY
  11 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  12 # A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
  13 # details.
  14 #
  15 # You should have received a copy of the GNU Lesser General Public License
  16 # along with Hooke.  If not, see <http://www.gnu.org/licenses/>.
  17
  18 """The `engine` module provides :class:`CommandEngine` for executing
  19 :class:`hooke.command.Command`\s.
  20 """
  21
  22 import logging
  23 from Queue import Queue, Empty
  24
  25 from .command import NullQueue
  26
  27
  28 class QueueMessage (object):
  29     def __str__(self):
  30         return self.__class__.__name__
  31
  32
  33 class CloseEngine (QueueMessage):
  34     pass
  35
  36
  37 class CommandMessage (QueueMessage):
  38     """A message storing a command to run, `command` should be the
  39     name of a :class:`hooke.command.Command` instance, and `arguments`
  40     should be a :class:`dict` with `argname` keys and `value` values
  41     to be passed to the command.
  42     """
  43     def __init__(self, command, arguments=None):
  44         self.command = command
  45         if arguments == None:
  46             arguments = {}
  47         self.arguments = arguments
  48         self.explicit_user_call = True
  49         """Message is explicitly user-executed.  This is useful for
  50         distinguishing auto-generated calls (for which
  51         `explicit_user_call` should be `False` such as the GUIs
  52         current status requests.
  53         """
  54
  55     def __str__(self):
  56         return str(self.__unicode__())
  57
  58     def __unicode__(self):
  59         """Return a unicode representation of the `CommandMessage`.
  60
  61         Examples
  62         --------
  63         >>> from .compat.odict import odict
  64         >>> cm = CommandMessage('command A')
  65         >>> print(unicode(cm))
  66         <CommandMessage command A>
  67         >>> cm.arguments = odict([('param a','value a'), ('param b', 'value b')])
  68         >>> print(unicode(cm))
  69         <CommandMessage command A {param a: value a, param b: value b}>
  70
  71         The parameters are sorted by name, so you won't be surprised
  72         in any doctests, etc.
  73
  74         >>> cm.arguments = odict([('param b','value b'), ('param a', 'value a')])
  75         >>> print(unicode(cm))
  76         <CommandMessage command A {param a: value a, param b: value b}>
  77         """
  78         if len(self.arguments) > 0:
  79             return u'<%s %s {%s}>' % (
  80                 self.__class__.__name__, self.command,
  81                 ', '.join(['%s: %s' % (key, value)
  82                            for key,value in sorted(self.arguments.items())]))
  83         return u'<%s %s>' % (self.__class__.__name__, self.command)
  84
  85     def __repr__(self):
  86         return self.__str__()
  87
  88
  89 class CommandEngine (object):
  90     def run(self, hooke, ui_to_command_queue, command_to_ui_queue):
  91         """Get a :class:`QueueMessage` from the incoming
  92         `ui_to_command_queue` and act accordingly.
  93
  94         If the message is a :class:`CommandMessage` instance, the
  95         command run may read subsequent input from
  96         `ui_to_command_queue` (if it is an interactive command).  The
  97         command may also put assorted data into `command_to_ui_queue`.
  98
  99         When the command completes, it will put a
 100         :class:`hooke.command.CommandExit` instance into
 101         `command_to_ui_queue`, at which point the `CommandEngine` will
 102         be ready to receive the next :class:`QueueMessage`.
 103         """
 104         log = logging.getLogger('hooke')
 105         log.debug('engine starting')
 106         for playlist in hooke.playlists:  # Curve._hooke is not pickled.
 107             for curve in playlist:
 108                 curve.set_hooke(hooke)
 109         while True:
 110             log.debug('engine waiting for command')
 111             msg = ui_to_command_queue.get()
 112             if isinstance(msg, CloseEngine):
 113                 command_to_ui_queue.put(hooke)
 114                 log.debug(
 115                     'engine closing, placed hooke instance in return queue')
 116                 break
 117             assert isinstance(msg, CommandMessage), type(msg)
 118             log.debug('engine running %s' % msg)
 119             cmd = hooke.command_by_name[msg.command]
 120             cmd.run(hooke, ui_to_command_queue, command_to_ui_queue,
 121                     **msg.arguments)
 122
 123     def run_command(self, hooke, command, arguments):
 124         """Run the command named `command` with `arguments` using
 125         :meth:`~hooke.engine.CommandEngine.run_command`.
 126
 127         This allows commands to execute sub commands and enables
 128         :class:`~hooke.command_stack.CommandStack` execution.
 129
 130         Note that these commands *do not* have access to the usual UI
 131         communication queues, so make sure they will not need user
 132         interaction.
 133         """
 134         log = logging.getLogger('hooke')
 135         log.debug('engine running internal %s'
 136                   % CommandMessage(command, arguments))
 137         outqueue = Queue()
 138         cmd = hooke.command_by_name[command]
 139         cmd.run(hooke, NullQueue(), outqueue, **arguments)
 140         while True:
 141             try:
 142                 msg = outqueue.get(block=False)
 143             except Empty:
 144                 break
 145             log.debug('engine message from %s (%s): %s' % (command, type(msg), msg))