1 """The `command` module provides :class:`Command`\s and
2 :class:`Argument`\s for defining commands.
4 It also provides :class:`CommandExit` and subclasses for communicating
5 command completion information between
6 :class:`hooke.engine.CommandEngine`\s and
7 :class:`hooke.ui.UserInterface`\s.
16 class CommandExit (Exception):
19 class Success (CommandExit):
23 """The command requests an end to the interpreter session.
27 class Failure (CommandExit):
30 class UncaughtException (Failure):
31 def __init__(self, exception, traceback_string=None):
32 super(UncaughtException, self).__init__()
33 if traceback_string == None:
34 traceback_string = traceback.format_exc()
36 self.exception = exception
37 self.traceback = traceback_string
38 self.__setstate__(self.__getstate__())
40 def __getstate__(self):
41 """Return a picklable representation of the objects state.
43 :mod:`pickle`'s doesn't call a :meth:`__init__` when
44 rebuilding a class instance. To preserve :attr:`args` through
45 a pickle cycle, we use :meth:`__getstate__` and
48 See `pickling class instances`_ and `pickling examples`_.
50 .. _pickling class instances:
51 http://docs.python.org/library/pickle.html#pickling-and-unpickling-normal-class-instances
52 .. _pickling examples:
53 http://docs.python.org/library/pickle.html#example
55 return {'exception':self.exception, 'traceback':self.traceback}
57 def __setstate__(self, state):
58 """Apply the picklable state from :meth:`__getstate__` to
59 reconstruct the instance.
61 for key,value in state.items():
62 setattr(self, key, value)
63 self.args = (self.traceback + str(self.exception),)
66 class Command (object):
67 """One-line command description here.
69 >>> c = Command(name='test', help='An example Command.')
71 >>> status = c.run(hooke, NullQueue(), PrintQueue(),
72 ... help=True) # doctest: +REPORT_UDIFF
78 help BOOL (bool) Print a help message.
84 def __init__(self, name, aliases=None, arguments=[], help=''):
88 self.aliases = aliases
90 Argument(name='help', type='bool', default=False, count=1,
91 help='Print a help message.'),
95 def run(self, hooke, inqueue=None, outqueue=None, **kwargs):
96 """`Normalize inputs and handle <Argument help> before punting
100 inqueue = NullQueue()
102 outqueue = NullQueue()
104 params = self.handle_arguments(hooke, inqueue, outqueue, kwargs)
105 if params['help'] == True:
106 outqueue.put(self.help())
108 self._run(hooke, inqueue, outqueue, params)
109 except CommandExit, e:
110 if isinstance(e, Failure):
113 # other CommandExit subclasses fall through to the end
115 x = UncaughtException(e)
123 def _run(self, inqueue, outqueue, params):
124 """This is where the command-specific magic will happen.
128 def handle_arguments(self, hooke, inqueue, outqueue, params):
129 """Normalize and validate input parameters (:class:`Argument` values).
131 for argument in self.arguments:
132 names = [argument.name] + argument.aliases
133 settings = [(name,v) for name,v in params.items() if name in names]
134 num_provided = len(settings)
135 if num_provided == 0:
136 if argument.optional == True or argument.count == 0:
137 settings = [(argument.name, argument.default)]
139 raise Failure('Required argument %s not set.'
142 raise Failure('Multiple settings for %s:\n %s'
144 '\n '.join(['%s: %s' % (name,value)
145 for name,value in sorted(settings)])))
146 name,value = settings[0]
147 if num_provided == 0:
148 params[argument.name] = value
150 if name != argument.name:
152 params[argument.name] = value
153 if argument.callback != None:
154 value = argument.callback(hooke, self, argument, value)
155 params[argument.name] = value
156 argument.validate(value)
159 def help(self, name_fn=lambda name:name):
160 """Return a help message describing the `Command`.
162 `name_fn(internal_name) -> external_name` gives calling
163 :class:`hooke.ui.UserInterface`\s a means of changing the
164 display names if it wants (e.g. to remove spaces from command
167 name_part = 'Command: %s' % name_fn(self.name)
168 if len(self.aliases) > 0:
169 name_part += ' (%s)' % ', '.join(
170 [name_fn(n) for n in self.aliases])
172 if len(self.arguments) > 0:
173 argument_part = ['Arguments:', '']
174 for a in self.arguments:
175 argument_part.append(textwrap.fill(
178 subsequent_indent=" "))
179 argument_part = '\n'.join(argument_part)
180 parts.append(argument_part)
181 parts.append(self._help) # help part
182 return '\n\n'.join(parts)
184 class Argument (object):
185 """Structured user input for :class:`Command`\s.
187 TODO: ranges for `count`?
189 def __init__(self, name, aliases=None, type='string', metavar=None,
190 default=None, optional=True, count=1,
191 completion_callback=None, callback=None, help=''):
195 self.aliases = aliases
198 metavar = type.upper()
199 self.metavar = metavar
200 self.default = default
201 self.optional = optional
203 self.completion_callback = completion_callback
204 self.callback = callback
208 return '<%s %s>' % (self.__class__.__name__, self.name)
211 return self.__str__()
213 def help(self, name_fn=lambda name:name):
214 """Return a help message describing the `Argument`.
216 `name_fn(internal_name) -> external_name` gives calling
217 :class:`hooke.ui.UserInterface`\s a means of changing the
218 display names if it wants (e.g. to remove spaces from command
221 parts = ['%s ' % name_fn(self.name)]
222 if self.metavar != None:
223 parts.append('%s ' % self.metavar)
224 parts.extend(['(%s) ' % self.type, self._help])
225 return ''.join(parts)
227 def validate(self, value):
228 """If `value` is not appropriate, raise `ValueError`.
230 pass # TODO: validation
232 # TODO: type conversion
234 # TODO: type extensions?
238 class StoreValue (object):
239 def __init__(self, value):
241 def __call__(self, hooke, command, argument, fragment=None):
244 class NullQueue (queue.Queue):
245 """The :class:`queue.Queue` equivalent of `/dev/null`.
247 This is a bottomless pit. Items go in, but never come out.
249 def get(self, block=True, timeout=None):
250 """Raise queue.Empty.
252 There's really no need to override the base Queue.get, but I
253 want to know if someone tries to read from a NullQueue. With
254 the default implementation they would just block silently
259 def put(self, item, block=True, timeout=None):
260 """Dump an item into the void.
262 Block and timeout are meaningless, because there is always a
263 free slot available in a bottomless pit.
267 class PrintQueue (NullQueue):
268 """Debugging :class:`NullQueue` that prints items before dropping
271 def put(self, item, block=True, timeout=None):
272 """Print `item` and then dump it into the void.
274 print 'ITEM:\n%s' % item