##// END OF EJS Templates
Complete documenting magic module, as per review....
Fernando Perez -
Show More
@@ -299,8 +299,9 b' class MagicsManager(Configurable):'
299
299
300 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
300 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
301
301
302 auto_magic = Bool
302 auto_magic = Bool(True, config=True, help=
303
303 "Automatically call line magics without requiring explicit % prefix")
304
304 _auto_status = [
305 _auto_status = [
305 'Automagic is OFF, % prefix IS needed for line magics.',
306 'Automagic is OFF, % prefix IS needed for line magics.',
306 'Automagic is ON, % prefix IS NOT needed for line magics.']
307 'Automagic is ON, % prefix IS NOT needed for line magics.']
@@ -330,6 +331,23 b' class MagicsManager(Configurable):'
330
331
331 def register(self, *magic_objects):
332 def register(self, *magic_objects):
332 """Register one or more instances of Magics.
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 # Start by validating them to ensure they have all had their magic
352 # Start by validating them to ensure they have all had their magic
335 # methods registered at the instance level
353 # methods registered at the instance level
@@ -348,7 +366,30 b' class MagicsManager(Configurable):'
348 self.magics[mtype].update(m.magics[mtype])
366 self.magics[mtype].update(m.magics[mtype])
349
367
350 def register_function(self, func, magic_kind='line', magic_name=None):
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 # Create the new method in the user_magics and register it in the
395 # Create the new method in the user_magics and register it in the
@@ -359,10 +400,17 b' class MagicsManager(Configurable):'
359 record_magic(self.magics, magic_kind, magic_name, func)
400 record_magic(self.magics, magic_kind, magic_name, func)
360
401
361 def define_magic(self, name, func):
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.
413 ip.define_magic('foo',foo_impl)
365 It will eventually be removed. Deliberately not documented further.
366 """
414 """
367 meth = types.MethodType(func, self.user_magics)
415 meth = types.MethodType(func, self.user_magics)
368 setattr(self.user_magics, name, meth)
416 setattr(self.user_magics, name, meth)
General Comments 0
You need to be logged in to leave comments. Login now