Warning
This documentation is for an old version of IPython. You can find docs for newer versions here.
A decorator-based method of constructing IPython magics with argparse option handling.
New magic functions can be defined like so:
from IPython.core.magic_arguments import (argument, magic_arguments,
parse_argstring)
@magic_arguments()
@argument('-o', '--option', help='An optional argument.')
@argument('arg', type=int, help='An integer positional argument.')
def magic_cool(self, arg):
""" A really cool magic command.
"""
args = parse_argstring(magic_cool, arg)
...
The @magic_arguments decorator marks the function as having argparse arguments. The @argument decorator adds an argument using the same syntax as argparse’s add_argument() method. More sophisticated uses may also require the @argument_group or @kwds decorator to customize the formatting and the parsing.
Help text for the magic is automatically generated from the docstring and the arguments:
In[1]: %cool?
%cool [-o OPTION] arg
A really cool magic command.
positional arguments:
arg An integer positional argument.
optional arguments:
-o OPTION, --option OPTION
An optional argument.
Inheritance diagram:
Bases: argparse.RawDescriptionHelpFormatter
A HelpFormatter which dedents but otherwise preserves indentation.
Bases: argparse.ArgumentParser
An ArgumentParser tweaked for use by IPython magics.
Raise a catchable error instead of exiting.
Split a string into an argument list and parse that argument list.
Bases: object
Base class for decorators to add ArgumentParser information to a method.
Add this object’s information to the parser, if necessary.
Bases: IPython.core.magic_arguments.ArgDecorator
Mark the magic as having argparse arguments and possibly adjust the name.
Bases: IPython.core.magic_arguments.ArgDecorator
Base class to define a wrapper for ArgumentParser method.
Child class must define either _method_name or add_to_parser.
Add this object’s information to the parser.
Bases: IPython.core.magic_arguments.ArgMethodWrapper
Store arguments and keywords to pass to add_argument().
Instances also serve to decorate command methods.
Bases: IPython.core.magic_arguments.ArgMethodWrapper
Store arguments and keywords to pass to set_defaults().
Instances also serve to decorate command methods.
Bases: IPython.core.magic_arguments.ArgMethodWrapper
Store arguments and keywords to pass to add_argument_group().
Instances also serve to decorate command methods.
Add this object’s information to the parser.
Bases: IPython.core.magic_arguments.ArgDecorator
Provide other keywords to the sub-parser constructor.
Construct an argument parser using the function decorations.
Parse the string of arguments for the given magic function.
Find the real name of the magic.