##// END OF EJS Templates
adjust MagicManager.register to handle Configurable magics...
MinRK -
Show More
@@ -1,576 +1,576 b''
1 1 # encoding: utf-8
2 2 """Magic functions for InteractiveShell.
3 3 """
4 4
5 5 #-----------------------------------------------------------------------------
6 6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
7 7 # Copyright (C) 2001 Fernando Perez <fperez@colorado.edu>
8 8 # Copyright (C) 2008 The IPython Development Team
9 9
10 10 # Distributed under the terms of the BSD License. The full license is in
11 11 # the file COPYING, distributed as part of this software.
12 12 #-----------------------------------------------------------------------------
13 13
14 14 #-----------------------------------------------------------------------------
15 15 # Imports
16 16 #-----------------------------------------------------------------------------
17 17 # Stdlib
18 18 import os
19 19 import re
20 20 import sys
21 21 import types
22 22 from getopt import getopt, GetoptError
23 23
24 24 # Our own
25 25 from IPython.config.configurable import Configurable
26 26 from IPython.core import oinspect
27 27 from IPython.core.error import UsageError
28 28 from IPython.core.prefilter import ESC_MAGIC
29 29 from IPython.external.decorator import decorator
30 30 from IPython.utils.ipstruct import Struct
31 31 from IPython.utils.process import arg_split
32 32 from IPython.utils.text import dedent
33 from IPython.utils.traitlets import Bool, Dict, Instance
33 from IPython.utils.traitlets import Bool, Dict, Instance, MetaHasTraits
34 34 from IPython.utils.warn import error, warn
35 35
36 36 #-----------------------------------------------------------------------------
37 37 # Globals
38 38 #-----------------------------------------------------------------------------
39 39
40 40 # A dict we'll use for each class that has magics, used as temporary storage to
41 41 # pass information between the @line/cell_magic method decorators and the
42 42 # @magics_class class decorator, because the method decorators have no
43 43 # access to the class when they run. See for more details:
44 44 # http://stackoverflow.com/questions/2366713/can-a-python-decorator-of-an-instance-method-access-the-class
45 45
46 46 magics = dict(line={}, cell={})
47 47
48 48 magic_kinds = ('line', 'cell')
49 49 magic_spec = ('line', 'cell', 'line_cell')
50 50
51 51 #-----------------------------------------------------------------------------
52 52 # Utility classes and functions
53 53 #-----------------------------------------------------------------------------
54 54
55 55 class Bunch: pass
56 56
57 57
58 58 def on_off(tag):
59 59 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
60 60 return ['OFF','ON'][tag]
61 61
62 62
63 63 def compress_dhist(dh):
64 64 """Compress a directory history into a new one with at most 20 entries.
65 65
66 66 Return a new list made from the first and last 10 elements of dhist after
67 67 removal of duplicates.
68 68 """
69 69 head, tail = dh[:-10], dh[-10:]
70 70
71 71 newhead = []
72 72 done = set()
73 73 for h in head:
74 74 if h in done:
75 75 continue
76 76 newhead.append(h)
77 77 done.add(h)
78 78
79 79 return newhead + tail
80 80
81 81
82 82 def needs_local_scope(func):
83 83 """Decorator to mark magic functions which need to local scope to run."""
84 84 func.needs_local_scope = True
85 85 return func
86 86
87 87 #-----------------------------------------------------------------------------
88 88 # Class and method decorators for registering magics
89 89 #-----------------------------------------------------------------------------
90 90
91 91 def magics_class(cls):
92 92 """Class decorator for all subclasses of the main Magics class.
93 93
94 94 Any class that subclasses Magics *must* also apply this decorator, to
95 95 ensure that all the methods that have been decorated as line/cell magics
96 96 get correctly registered in the class instance. This is necessary because
97 97 when method decorators run, the class does not exist yet, so they
98 98 temporarily store their information into a module global. Application of
99 99 this class decorator copies that global data to the class instance and
100 100 clears the global.
101 101
102 102 Obviously, this mechanism is not thread-safe, which means that the
103 103 *creation* of subclasses of Magic should only be done in a single-thread
104 104 context. Instantiation of the classes has no restrictions. Given that
105 105 these classes are typically created at IPython startup time and before user
106 106 application code becomes active, in practice this should not pose any
107 107 problems.
108 108 """
109 109 cls.registered = True
110 110 cls.magics = dict(line = magics['line'],
111 111 cell = magics['cell'])
112 112 magics['line'] = {}
113 113 magics['cell'] = {}
114 114 return cls
115 115
116 116
117 117 def record_magic(dct, magic_kind, magic_name, func):
118 118 """Utility function to store a function as a magic of a specific kind.
119 119
120 120 Parameters
121 121 ----------
122 122 dct : dict
123 123 A dictionary with 'line' and 'cell' subdicts.
124 124
125 125 magic_kind : str
126 126 Kind of magic to be stored.
127 127
128 128 magic_name : str
129 129 Key to store the magic as.
130 130
131 131 func : function
132 132 Callable object to store.
133 133 """
134 134 if magic_kind == 'line_cell':
135 135 dct['line'][magic_name] = dct['cell'][magic_name] = func
136 136 else:
137 137 dct[magic_kind][magic_name] = func
138 138
139 139
140 140 def validate_type(magic_kind):
141 141 """Ensure that the given magic_kind is valid.
142 142
143 143 Check that the given magic_kind is one of the accepted spec types (stored
144 144 in the global `magic_spec`), raise ValueError otherwise.
145 145 """
146 146 if magic_kind not in magic_spec:
147 147 raise ValueError('magic_kind must be one of %s, %s given' %
148 148 magic_kinds, magic_kind)
149 149
150 150
151 151 # The docstrings for the decorator below will be fairly similar for the two
152 152 # types (method and function), so we generate them here once and reuse the
153 153 # templates below.
154 154 _docstring_template = \
155 155 """Decorate the given {0} as {1} magic.
156 156
157 157 The decorator can be used with or without arguments, as follows.
158 158
159 159 i) without arguments: it will create a {1} magic named as the {0} being
160 160 decorated::
161 161
162 162 @deco
163 163 def foo(...)
164 164
165 165 will create a {1} magic named `foo`.
166 166
167 167 ii) with one string argument: which will be used as the actual name of the
168 168 resulting magic::
169 169
170 170 @deco('bar')
171 171 def foo(...)
172 172
173 173 will create a {1} magic named `bar`.
174 174 """
175 175
176 176 # These two are decorator factories. While they are conceptually very similar,
177 177 # there are enough differences in the details that it's simpler to have them
178 178 # written as completely standalone functions rather than trying to share code
179 179 # and make a single one with convoluted logic.
180 180
181 181 def _method_magic_marker(magic_kind):
182 182 """Decorator factory for methods in Magics subclasses.
183 183 """
184 184
185 185 validate_type(magic_kind)
186 186
187 187 # This is a closure to capture the magic_kind. We could also use a class,
188 188 # but it's overkill for just that one bit of state.
189 189 def magic_deco(arg):
190 190 call = lambda f, *a, **k: f(*a, **k)
191 191
192 192 if callable(arg):
193 193 # "Naked" decorator call (just @foo, no args)
194 194 func = arg
195 195 name = func.func_name
196 196 retval = decorator(call, func)
197 197 record_magic(magics, magic_kind, name, name)
198 198 elif isinstance(arg, basestring):
199 199 # Decorator called with arguments (@foo('bar'))
200 200 name = arg
201 201 def mark(func, *a, **kw):
202 202 record_magic(magics, magic_kind, name, func.func_name)
203 203 return decorator(call, func)
204 204 retval = mark
205 205 else:
206 206 raise TypeError("Decorator can only be called with "
207 207 "string or function")
208 208 return retval
209 209
210 210 # Ensure the resulting decorator has a usable docstring
211 211 magic_deco.__doc__ = _docstring_template.format('method', magic_kind)
212 212 return magic_deco
213 213
214 214
215 215 def _function_magic_marker(magic_kind):
216 216 """Decorator factory for standalone functions.
217 217 """
218 218 validate_type(magic_kind)
219 219
220 220 # This is a closure to capture the magic_kind. We could also use a class,
221 221 # but it's overkill for just that one bit of state.
222 222 def magic_deco(arg):
223 223 call = lambda f, *a, **k: f(*a, **k)
224 224
225 225 # Find get_ipython() in the caller's namespace
226 226 caller = sys._getframe(1)
227 227 for ns in ['f_locals', 'f_globals', 'f_builtins']:
228 228 get_ipython = getattr(caller, ns).get('get_ipython')
229 229 if get_ipython is not None:
230 230 break
231 231 else:
232 232 raise NameError('Decorator can only run in context where '
233 233 '`get_ipython` exists')
234 234
235 235 ip = get_ipython()
236 236
237 237 if callable(arg):
238 238 # "Naked" decorator call (just @foo, no args)
239 239 func = arg
240 240 name = func.func_name
241 241 ip.register_magic_function(func, magic_kind, name)
242 242 retval = decorator(call, func)
243 243 elif isinstance(arg, basestring):
244 244 # Decorator called with arguments (@foo('bar'))
245 245 name = arg
246 246 def mark(func, *a, **kw):
247 247 ip.register_magic_function(func, magic_kind, name)
248 248 return decorator(call, func)
249 249 retval = mark
250 250 else:
251 251 raise TypeError("Decorator can only be called with "
252 252 "string or function")
253 253 return retval
254 254
255 255 # Ensure the resulting decorator has a usable docstring
256 256 ds = _docstring_template.format('function', magic_kind)
257 257
258 258 ds += dedent("""
259 259 Note: this decorator can only be used in a context where IPython is already
260 260 active, so that the `get_ipython()` call succeeds. You can therefore use
261 261 it in your startup files loaded after IPython initializes, but *not* in the
262 262 IPython configuration file itself, which is executed before IPython is
263 263 fully up and running. Any file located in the `startup` subdirectory of
264 264 your configuration profile will be OK in this sense.
265 265 """)
266 266
267 267 magic_deco.__doc__ = ds
268 268 return magic_deco
269 269
270 270
271 271 # Create the actual decorators for public use
272 272
273 273 # These three are used to decorate methods in class definitions
274 274 line_magic = _method_magic_marker('line')
275 275 cell_magic = _method_magic_marker('cell')
276 276 line_cell_magic = _method_magic_marker('line_cell')
277 277
278 278 # These three decorate standalone functions and perform the decoration
279 279 # immediately. They can only run where get_ipython() works
280 280 register_line_magic = _function_magic_marker('line')
281 281 register_cell_magic = _function_magic_marker('cell')
282 282 register_line_cell_magic = _function_magic_marker('line_cell')
283 283
284 284 #-----------------------------------------------------------------------------
285 285 # Core Magic classes
286 286 #-----------------------------------------------------------------------------
287 287
288 288 class MagicsManager(Configurable):
289 289 """Object that handles all magic-related functionality for IPython.
290 290 """
291 291 # Non-configurable class attributes
292 292
293 293 # A two-level dict, first keyed by magic type, then by magic function, and
294 294 # holding the actual callable object as value. This is the dict used for
295 295 # magic function dispatch
296 296 magics = Dict
297 297
298 298 # A registry of the original objects that we've been given holding magics.
299 299 registry = Dict
300 300
301 301 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
302 302
303 303 auto_magic = Bool(True, config=True, help=
304 304 "Automatically call line magics without requiring explicit % prefix")
305 305
306 306 _auto_status = [
307 307 'Automagic is OFF, % prefix IS needed for line magics.',
308 308 'Automagic is ON, % prefix IS NOT needed for line magics.']
309 309
310 310 user_magics = Instance('IPython.core.magics.UserMagics')
311 311
312 312 def __init__(self, shell=None, config=None, user_magics=None, **traits):
313 313
314 314 super(MagicsManager, self).__init__(shell=shell, config=config,
315 315 user_magics=user_magics, **traits)
316 316 self.magics = dict(line={}, cell={})
317 317 # Let's add the user_magics to the registry for uniformity, so *all*
318 318 # registered magic containers can be found there.
319 319 self.registry[user_magics.__class__.__name__] = user_magics
320 320
321 321 def auto_status(self):
322 322 """Return descriptive string with automagic status."""
323 323 return self._auto_status[self.auto_magic]
324 324
325 325 def lsmagic(self):
326 326 """Return a dict of currently available magic functions.
327 327
328 328 The return dict has the keys 'line' and 'cell', corresponding to the
329 329 two types of magics we support. Each value is a list of names.
330 330 """
331 331 return self.magics
332 332
333 333 def register(self, *magic_objects):
334 334 """Register one or more instances of Magics.
335 335
336 336 Take one or more classes or instances of classes that subclass the main
337 337 `core.Magic` class, and register them with IPython to use the magic
338 338 functions they provide. The registration process will then ensure that
339 339 any methods that have decorated to provide line and/or cell magics will
340 340 be recognized with the `%x`/`%%x` syntax as a line/cell magic
341 341 respectively.
342 342
343 343 If classes are given, they will be instantiated with the default
344 344 constructor. If your classes need a custom constructor, you should
345 345 instanitate them first and pass the instance.
346 346
347 347 The provided arguments can be an arbitrary mix of classes and instances.
348 348
349 349 Parameters
350 350 ----------
351 351 magic_objects : one or more classes or instances
352 352 """
353 353 # Start by validating them to ensure they have all had their magic
354 354 # methods registered at the instance level
355 355 for m in magic_objects:
356 356 if not m.registered:
357 357 raise ValueError("Class of magics %r was constructed without "
358 "the @register_macics class decorator")
359 if type(m) is type:
358 "the @register_magics class decorator")
359 if type(m) in (type, MetaHasTraits):
360 360 # If we're given an uninstantiated class
361 m = m(self.shell)
361 m = m(shell=self.shell)
362 362
363 363 # Now that we have an instance, we can register it and update the
364 364 # table of callables
365 365 self.registry[m.__class__.__name__] = m
366 366 for mtype in magic_kinds:
367 367 self.magics[mtype].update(m.magics[mtype])
368 368
369 369 def register_function(self, func, magic_kind='line', magic_name=None):
370 370 """Expose a standalone function as magic function for IPython.
371 371
372 372 This will create an IPython magic (line, cell or both) from a
373 373 standalone function. The functions should have the following
374 374 signatures:
375 375
376 376 * For line magics: `def f(line)`
377 377 * For cell magics: `def f(line, cell)`
378 378 * For a function that does both: `def f(line, cell=None)`
379 379
380 380 In the latter case, the function will be called with `cell==None` when
381 381 invoked as `%f`, and with cell as a string when invoked as `%%f`.
382 382
383 383 Parameters
384 384 ----------
385 385 func : callable
386 386 Function to be registered as a magic.
387 387
388 388 magic_kind : str
389 389 Kind of magic, one of 'line', 'cell' or 'line_cell'
390 390
391 391 magic_name : optional str
392 392 If given, the name the magic will have in the IPython namespace. By
393 393 default, the name of the function itself is used.
394 394 """
395 395
396 396 # Create the new method in the user_magics and register it in the
397 397 # global table
398 398 validate_type(magic_kind)
399 399 magic_name = func.func_name if magic_name is None else magic_name
400 400 setattr(self.user_magics, magic_name, func)
401 401 record_magic(self.magics, magic_kind, magic_name, func)
402 402
403 403 def define_magic(self, name, func):
404 404 """[Deprecated] Expose own function as magic function for IPython.
405 405
406 406 Example::
407 407
408 408 def foo_impl(self, parameter_s=''):
409 409 'My very own magic!. (Use docstrings, IPython reads them).'
410 410 print 'Magic function. Passed parameter is between < >:'
411 411 print '<%s>' % parameter_s
412 412 print 'The self object is:', self
413 413
414 414 ip.define_magic('foo',foo_impl)
415 415 """
416 416 meth = types.MethodType(func, self.user_magics)
417 417 setattr(self.user_magics, name, meth)
418 418 record_magic(self.magics, 'line', name, meth)
419 419
420 420 # Key base class that provides the central functionality for magics.
421 421
422 422 class Magics(object):
423 423 """Base class for implementing magic functions.
424 424
425 425 Shell functions which can be reached as %function_name. All magic
426 426 functions should accept a string, which they can parse for their own
427 427 needs. This can make some functions easier to type, eg `%cd ../`
428 428 vs. `%cd("../")`
429 429
430 430 Classes providing magic functions need to subclass this class, and they
431 431 MUST:
432 432
433 433 - Use the method decorators `@line_magic` and `@cell_magic` to decorate
434 434 individual methods as magic functions, AND
435 435
436 436 - Use the class decorator `@magics_class` to ensure that the magic
437 437 methods are properly registered at the instance level upon instance
438 438 initialization.
439 439
440 440 See :mod:`magic_functions` for examples of actual implementation classes.
441 441 """
442 442 # Dict holding all command-line options for each magic.
443 443 options_table = None
444 444 # Dict for the mapping of magic names to methods, set by class decorator
445 445 magics = None
446 446 # Flag to check that the class decorator was properly applied
447 447 registered = False
448 448 # Instance of IPython shell
449 449 shell = None
450 450
451 451 def __init__(self, shell):
452 452 if not(self.__class__.registered):
453 453 raise ValueError('Magics subclass without registration - '
454 454 'did you forget to apply @magics_class?')
455 455 self.shell = shell
456 456 self.options_table = {}
457 457 # The method decorators are run when the instance doesn't exist yet, so
458 458 # they can only record the names of the methods they are supposed to
459 459 # grab. Only now, that the instance exists, can we create the proper
460 460 # mapping to bound methods. So we read the info off the original names
461 461 # table and replace each method name by the actual bound method.
462 462 for mtype in magic_kinds:
463 463 tab = self.magics[mtype]
464 464 # must explicitly use keys, as we're mutating this puppy
465 465 for magic_name in tab.keys():
466 466 meth_name = tab[magic_name]
467 467 if isinstance(meth_name, basestring):
468 468 tab[magic_name] = getattr(self, meth_name)
469 469
470 470 def arg_err(self,func):
471 471 """Print docstring if incorrect arguments were passed"""
472 472 print 'Error in arguments:'
473 473 print oinspect.getdoc(func)
474 474
475 475 def format_latex(self, strng):
476 476 """Format a string for latex inclusion."""
477 477
478 478 # Characters that need to be escaped for latex:
479 479 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
480 480 # Magic command names as headers:
481 481 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
482 482 re.MULTILINE)
483 483 # Magic commands
484 484 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
485 485 re.MULTILINE)
486 486 # Paragraph continue
487 487 par_re = re.compile(r'\\$',re.MULTILINE)
488 488
489 489 # The "\n" symbol
490 490 newline_re = re.compile(r'\\n')
491 491
492 492 # Now build the string for output:
493 493 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
494 494 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
495 495 strng)
496 496 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
497 497 strng = par_re.sub(r'\\\\',strng)
498 498 strng = escape_re.sub(r'\\\1',strng)
499 499 strng = newline_re.sub(r'\\textbackslash{}n',strng)
500 500 return strng
501 501
502 502 def parse_options(self, arg_str, opt_str, *long_opts, **kw):
503 503 """Parse options passed to an argument string.
504 504
505 505 The interface is similar to that of getopt(), but it returns back a
506 506 Struct with the options as keys and the stripped argument string still
507 507 as a string.
508 508
509 509 arg_str is quoted as a true sys.argv vector by using shlex.split.
510 510 This allows us to easily expand variables, glob files, quote
511 511 arguments, etc.
512 512
513 513 Options:
514 514 -mode: default 'string'. If given as 'list', the argument string is
515 515 returned as a list (split on whitespace) instead of a string.
516 516
517 517 -list_all: put all option values in lists. Normally only options
518 518 appearing more than once are put in a list.
519 519
520 520 -posix (True): whether to split the input line in POSIX mode or not,
521 521 as per the conventions outlined in the shlex module from the
522 522 standard library."""
523 523
524 524 # inject default options at the beginning of the input line
525 525 caller = sys._getframe(1).f_code.co_name
526 526 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
527 527
528 528 mode = kw.get('mode','string')
529 529 if mode not in ['string','list']:
530 530 raise ValueError,'incorrect mode given: %s' % mode
531 531 # Get options
532 532 list_all = kw.get('list_all',0)
533 533 posix = kw.get('posix', os.name == 'posix')
534 534 strict = kw.get('strict', True)
535 535
536 536 # Check if we have more than one argument to warrant extra processing:
537 537 odict = {} # Dictionary with options
538 538 args = arg_str.split()
539 539 if len(args) >= 1:
540 540 # If the list of inputs only has 0 or 1 thing in it, there's no
541 541 # need to look for options
542 542 argv = arg_split(arg_str, posix, strict)
543 543 # Do regular option processing
544 544 try:
545 545 opts,args = getopt(argv, opt_str, long_opts)
546 546 except GetoptError,e:
547 547 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
548 548 " ".join(long_opts)))
549 549 for o,a in opts:
550 550 if o.startswith('--'):
551 551 o = o[2:]
552 552 else:
553 553 o = o[1:]
554 554 try:
555 555 odict[o].append(a)
556 556 except AttributeError:
557 557 odict[o] = [odict[o],a]
558 558 except KeyError:
559 559 if list_all:
560 560 odict[o] = [a]
561 561 else:
562 562 odict[o] = a
563 563
564 564 # Prepare opts,args for return
565 565 opts = Struct(odict)
566 566 if mode == 'string':
567 567 args = ' '.join(args)
568 568
569 569 return opts,args
570 570
571 571 def default_option(self, fn, optstr):
572 572 """Make an entry in the options_table for fn, with value optstr"""
573 573
574 574 if fn not in self.lsmagic():
575 575 error("%s is not a magic function" % fn)
576 576 self.options_table[fn] = optstr
General Comments 0
You need to be logged in to leave comments. Login now