[IPython-dev] Using argparse for %magics

Robert Kern robert.kern@gmail....
Sun Apr 5 03:50:29 CDT 2009

I have updated my personal collection of %magics today:


Not all of them are aimed at inclusion into IPython proper, but I think most of 
them would be useful as Extensions, at least. Here are all of the collected 


The recently added magics are

   %push_err/%pop_err for controlling numpy's error handling options via a 
stack. These complement %push_print/%pop_print, which control numpy's printing 
options the same way.

   %print_methods (optional alias %pm) for printing the methods of an object, 
grouped by the defining class.

   %print_traits (optional alias %pt) for printing the traits of a HasTraits 
object, grouped by the defining class. Crazy-useful.

One thing you might want to consider for IPython proper is the mini-framework I 
use for parsing the arguments. I made some decorators which use argparse (now in 
IPython.externals, amen) to build parsers for those magics that take CLI-style 
--options. It's nicely declarative and makes the option parsing and help text 
style uniform across all of the magics. We've discussed having a standard for 
all of the --option-taking %magics that come with IPython, and I put this 
forward as an improvement over the current manual getopt code.

Here is the start of one of my %magics, to demonstrate:

from kernmagic.magic_arguments import magic_arguments, argument, parse_argstring

@argument('-e', '--encoding', default='utf-8',
     help="the encoding to use for unicode objects; no effect on str objects "
         "[default: %(default)s]")
@argument('-m', '--mode', default='wb',
     help="the file mode to use when opening the file for writing")
@argument('variable', help="the name of the variable")
@argument('filename', nargs='?',
     help="the filename to write [default: the variable's name]")
def magic_fwrite(self, arg):
     """ Write text out to a file.

     args = parse_argstring(magic_fwrite, arg)
     if args.filename is None:
         args.filename = args.variable
     filename = os.path.expanduser(args.filename)

Here is the generated help:

In [7]: %fwrite?
Type:           Magic function
Base Class:     <type 'instancemethod'>
Namespace:      IPython internal
File:           /Users/rkern/hg/kernmagic/kernmagic/mymagics.py
Definition:     %fwrite(self, arg)
     %fwrite [-e ENCODING] [-m MODE] variable [filename]

     Write text out to a file.

     positional arguments:
       variable              the name of the variable
       filename              the filename to write [default: the variable's name]

     optional arguments:
       -e ENCODING, --encoding ENCODING
                             the encoding to use for unicode objects; no effect on
                             str objects [default: utf-8]
       -m MODE, --mode MODE  the file mode to use when opening the file for writing

I also have a cross-platform terminal_size() function in utils.py that should 
probably be made part of the ipapi (hookable by GUI frontends, of course).

Robert Kern

"I have come to believe that the whole world is an enigma, a harmless enigma
  that is made terrible by our own mad attempt to interpret it as though it had
  an underlying truth."
   -- Umberto Eco

More information about the IPython-dev mailing list