##// END OF EJS Templates
Complete documenting magic module, as per review....
Fernando Perez -
Show More
@@ -1,527 +1,575 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 33 from IPython.utils.traitlets import Bool, Dict, Instance
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 ValueError("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('Decorator can only run in context where `get_ipython` exists')
233 233
234 234 ip = get_ipython()
235 235
236 236 if callable(arg):
237 237 # "Naked" decorator call (just @foo, no args)
238 238 func = arg
239 239 name = func.func_name
240 240 ip.register_magic_function(func, magic_kind, name)
241 241 retval = decorator(call, func)
242 242 elif isinstance(arg, basestring):
243 243 # Decorator called with arguments (@foo('bar'))
244 244 name = arg
245 245 def mark(func, *a, **kw):
246 246 ip.register_magic_function(func, magic_kind, name)
247 247 return decorator(call, func)
248 248 retval = mark
249 249 else:
250 250 raise ValueError("Decorator can only be called with "
251 251 "string or function")
252 252 return retval
253 253
254 254 # Ensure the resulting decorator has a usable docstring
255 255 ds = _docstring_template.format('function', magic_kind)
256 256
257 257 ds += dedent("""
258 258 Note: this decorator can only be used in a context where IPython is already
259 259 active, so that the `get_ipython()` call succeeds. You can therefore use
260 260 it in your startup files loaded after IPython initializes, but *not* in the
261 261 IPython configuration file itself, which is executed before IPython is
262 262 fully up and running. Any file located in the `startup` subdirectory of
263 263 your configuration profile will be OK in this sense.
264 264 """)
265 265
266 266 magic_deco.__doc__ = ds
267 267 return magic_deco
268 268
269 269
270 270 # Create the actual decorators for public use
271 271
272 272 # These three are used to decorate methods in class definitions
273 273 line_magic = _method_magic_marker('line')
274 274 cell_magic = _method_magic_marker('cell')
275 275 line_cell_magic = _method_magic_marker('line_cell')
276 276
277 277 # These three decorate standalone functions and perform the decoration
278 278 # immediately. They can only run where get_ipython() works
279 279 register_line_magic = _function_magic_marker('line')
280 280 register_cell_magic = _function_magic_marker('cell')
281 281 register_line_cell_magic = _function_magic_marker('line_cell')
282 282
283 283 #-----------------------------------------------------------------------------
284 284 # Core Magic classes
285 285 #-----------------------------------------------------------------------------
286 286
287 287 class MagicsManager(Configurable):
288 288 """Object that handles all magic-related functionality for IPython.
289 289 """
290 290 # Non-configurable class attributes
291 291
292 292 # A two-level dict, first keyed by magic type, then by magic function, and
293 293 # holding the actual callable object as value. This is the dict used for
294 294 # magic function dispatch
295 295 magics = Dict
296 296
297 297 # A registry of the original objects that we've been given holding magics.
298 298 registry = Dict
299 299
300 300 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
301 301
302 auto_magic = Bool
303
302 auto_magic = Bool(True, config=True, help=
303 "Automatically call line magics without requiring explicit % prefix")
304
304 305 _auto_status = [
305 306 'Automagic is OFF, % prefix IS needed for line magics.',
306 307 'Automagic is ON, % prefix IS NOT needed for line magics.']
307 308
308 309 user_magics = Instance('IPython.core.magics.UserMagics')
309 310
310 311 def __init__(self, shell=None, config=None, user_magics=None, **traits):
311 312
312 313 super(MagicsManager, self).__init__(shell=shell, config=config,
313 314 user_magics=user_magics, **traits)
314 315 self.magics = dict(line={}, cell={})
315 316 # Let's add the user_magics to the registry for uniformity, so *all*
316 317 # registered magic containers can be found there.
317 318 self.registry[user_magics.__class__.__name__] = user_magics
318 319
319 320 def auto_status(self):
320 321 """Return descriptive string with automagic status."""
321 322 return self._auto_status[self.auto_magic]
322 323
323 324 def lsmagic(self):
324 325 """Return a dict of currently available magic functions.
325 326
326 327 The return dict has the keys 'line' and 'cell', corresponding to the
327 328 two types of magics we support. Each value is a list of names.
328 329 """
329 330 return self.magics
330 331
331 332 def register(self, *magic_objects):
332 333 """Register one or more instances of Magics.
334
335 Take one or more classes or instances of classes that subclass the main
336 `core.Magic` class, and register them with IPython to use the magic
337 functions they provide. The registration process will then ensure that
338 any methods that have decorated to provide line and/or cell magics will
339 be recognized with the `%x`/`%%x` syntax as a line/cell magic
340 respectively.
341
342 If classes are given, they will be instantiated with the default
343 constructor. If your classes need a custom constructor, you should
344 instanitate them first and pass the instance.
345
346 The provided arguments can be an arbitrary mix of classes and instances.
347
348 Parameters
349 ----------
350 magic_objects : one or more classes or instances
333 351 """
334 352 # Start by validating them to ensure they have all had their magic
335 353 # methods registered at the instance level
336 354 for m in magic_objects:
337 355 if not m.registered:
338 356 raise ValueError("Class of magics %r was constructed without "
339 357 "the @register_macics class decorator")
340 358 if type(m) is type:
341 359 # If we're given an uninstantiated class
342 360 m = m(self.shell)
343 361
344 362 # Now that we have an instance, we can register it and update the
345 363 # table of callables
346 364 self.registry[m.__class__.__name__] = m
347 365 for mtype in magic_kinds:
348 366 self.magics[mtype].update(m.magics[mtype])
349 367
350 368 def register_function(self, func, magic_kind='line', magic_name=None):
351 """Expose a standalone function as magic function for ipython.
369 """Expose a standalone function as magic function for IPython.
370
371 This will create an IPython magic (line, cell or both) from a
372 standalone function. The functions should have the following
373 signatures:
374
375 * For line magics: `def f(line)`
376 * For cell magics: `def f(line, cell)`
377 * For a function that does both: `def f(line, cell=None)`
378
379 In the latter case, the function will be called with `cell==None` when
380 invoked as `%f`, and with cell as a string when invoked as `%%f`.
381
382 Parameters
383 ----------
384 func : callable
385 Function to be registered as a magic.
386
387 magic_kind : str
388 Kind of magic, one of 'line', 'cell' or 'line_cell'
389
390 magic_name : optional str
391 If given, the name the magic will have in the IPython namespace. By
392 default, the name of the function itself is used.
352 393 """
353 394
354 395 # Create the new method in the user_magics and register it in the
355 396 # global table
356 397 validate_type(magic_kind)
357 398 magic_name = func.func_name if magic_name is None else magic_name
358 399 setattr(self.user_magics, magic_name, func)
359 400 record_magic(self.magics, magic_kind, magic_name, func)
360 401
361 402 def define_magic(self, name, func):
362 """Support for deprecated API.
403 """[Deprecated] Expose own function as magic function for IPython.
404
405 Example::
406
407 def foo_impl(self, parameter_s=''):
408 'My very own magic!. (Use docstrings, IPython reads them).'
409 print 'Magic function. Passed parameter is between < >:'
410 print '<%s>' % parameter_s
411 print 'The self object is:', self
363 412
364 This method exists only to support the old-style definition of magics.
365 It will eventually be removed. Deliberately not documented further.
413 ip.define_magic('foo',foo_impl)
366 414 """
367 415 meth = types.MethodType(func, self.user_magics)
368 416 setattr(self.user_magics, name, meth)
369 417 record_magic(self.magics, 'line', name, meth)
370 418
371 419 # Key base class that provides the central functionality for magics.
372 420
373 421 class Magics(object):
374 422 """Base class for implementing magic functions.
375 423
376 424 Shell functions which can be reached as %function_name. All magic
377 425 functions should accept a string, which they can parse for their own
378 426 needs. This can make some functions easier to type, eg `%cd ../`
379 427 vs. `%cd("../")`
380 428
381 429 Classes providing magic functions need to subclass this class, and they
382 430 MUST:
383 431
384 432 - Use the method decorators `@line_magic` and `@cell_magic` to decorate
385 433 individual methods as magic functions, AND
386 434
387 435 - Use the class decorator `@magics_class` to ensure that the magic
388 436 methods are properly registered at the instance level upon instance
389 437 initialization.
390 438
391 439 See :mod:`magic_functions` for examples of actual implementation classes.
392 440 """
393 441 # Dict holding all command-line options for each magic.
394 442 options_table = None
395 443 # Dict for the mapping of magic names to methods, set by class decorator
396 444 magics = None
397 445 # Flag to check that the class decorator was properly applied
398 446 registered = False
399 447 # Instance of IPython shell
400 448 shell = None
401 449
402 450 def __init__(self, shell):
403 451 if not(self.__class__.registered):
404 452 raise ValueError('Magics subclass without registration - '
405 453 'did you forget to apply @magics_class?')
406 454 self.shell = shell
407 455 self.options_table = {}
408 456 # The method decorators are run when the instance doesn't exist yet, so
409 457 # they can only record the names of the methods they are supposed to
410 458 # grab. Only now, that the instance exists, can we create the proper
411 459 # mapping to bound methods. So we read the info off the original names
412 460 # table and replace each method name by the actual bound method.
413 461 for mtype in magic_kinds:
414 462 tab = self.magics[mtype]
415 463 # must explicitly use keys, as we're mutating this puppy
416 464 for magic_name in tab.keys():
417 465 meth_name = tab[magic_name]
418 466 if isinstance(meth_name, basestring):
419 467 tab[magic_name] = getattr(self, meth_name)
420 468
421 469 def arg_err(self,func):
422 470 """Print docstring if incorrect arguments were passed"""
423 471 print 'Error in arguments:'
424 472 print oinspect.getdoc(func)
425 473
426 474 def format_latex(self, strng):
427 475 """Format a string for latex inclusion."""
428 476
429 477 # Characters that need to be escaped for latex:
430 478 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
431 479 # Magic command names as headers:
432 480 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
433 481 re.MULTILINE)
434 482 # Magic commands
435 483 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
436 484 re.MULTILINE)
437 485 # Paragraph continue
438 486 par_re = re.compile(r'\\$',re.MULTILINE)
439 487
440 488 # The "\n" symbol
441 489 newline_re = re.compile(r'\\n')
442 490
443 491 # Now build the string for output:
444 492 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
445 493 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
446 494 strng)
447 495 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
448 496 strng = par_re.sub(r'\\\\',strng)
449 497 strng = escape_re.sub(r'\\\1',strng)
450 498 strng = newline_re.sub(r'\\textbackslash{}n',strng)
451 499 return strng
452 500
453 501 def parse_options(self, arg_str, opt_str, *long_opts, **kw):
454 502 """Parse options passed to an argument string.
455 503
456 504 The interface is similar to that of getopt(), but it returns back a
457 505 Struct with the options as keys and the stripped argument string still
458 506 as a string.
459 507
460 508 arg_str is quoted as a true sys.argv vector by using shlex.split.
461 509 This allows us to easily expand variables, glob files, quote
462 510 arguments, etc.
463 511
464 512 Options:
465 513 -mode: default 'string'. If given as 'list', the argument string is
466 514 returned as a list (split on whitespace) instead of a string.
467 515
468 516 -list_all: put all option values in lists. Normally only options
469 517 appearing more than once are put in a list.
470 518
471 519 -posix (True): whether to split the input line in POSIX mode or not,
472 520 as per the conventions outlined in the shlex module from the
473 521 standard library."""
474 522
475 523 # inject default options at the beginning of the input line
476 524 caller = sys._getframe(1).f_code.co_name
477 525 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
478 526
479 527 mode = kw.get('mode','string')
480 528 if mode not in ['string','list']:
481 529 raise ValueError,'incorrect mode given: %s' % mode
482 530 # Get options
483 531 list_all = kw.get('list_all',0)
484 532 posix = kw.get('posix', os.name == 'posix')
485 533 strict = kw.get('strict', True)
486 534
487 535 # Check if we have more than one argument to warrant extra processing:
488 536 odict = {} # Dictionary with options
489 537 args = arg_str.split()
490 538 if len(args) >= 1:
491 539 # If the list of inputs only has 0 or 1 thing in it, there's no
492 540 # need to look for options
493 541 argv = arg_split(arg_str, posix, strict)
494 542 # Do regular option processing
495 543 try:
496 544 opts,args = getopt(argv,opt_str,*long_opts)
497 545 except GetoptError,e:
498 546 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
499 547 " ".join(long_opts)))
500 548 for o,a in opts:
501 549 if o.startswith('--'):
502 550 o = o[2:]
503 551 else:
504 552 o = o[1:]
505 553 try:
506 554 odict[o].append(a)
507 555 except AttributeError:
508 556 odict[o] = [odict[o],a]
509 557 except KeyError:
510 558 if list_all:
511 559 odict[o] = [a]
512 560 else:
513 561 odict[o] = a
514 562
515 563 # Prepare opts,args for return
516 564 opts = Struct(odict)
517 565 if mode == 'string':
518 566 args = ' '.join(args)
519 567
520 568 return opts,args
521 569
522 570 def default_option(self, fn, optstr):
523 571 """Make an entry in the options_table for fn, with value optstr"""
524 572
525 573 if fn not in self.lsmagic():
526 574 error("%s is not a magic function" % fn)
527 575 self.options_table[fn] = optstr
General Comments 0
You need to be logged in to leave comments. Login now