[IPython-dev] Using argparse for %magics

[Robert Kern]

I have updated my personal collection of %magics today:

   http://www.enthought.com/~rkern/cgi-bin/hgwebdir.cgi/kernmagic

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 
docstrings:

 
http://www.enthought.com/~rkern/cgi-bin/hgwebdir.cgi/kernmagic/raw-file/tip/help.txt

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

@magic_arguments()
@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)
Docstring:
     %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