Module: core.magic_arguments
¶
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:
digraph inheritance20cd358b90 { rankdir=LR; size="8.0, 12.0"; "argparse.ArgumentParser" [fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",tooltip="Object for parsing command line strings into Python objects."]; "argparse.HelpFormatter" [fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",tooltip="Formatter for generating usage messages and argument help strings."]; "argparse.RawDescriptionHelpFormatter" [fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",tooltip="Help message formatter which retains any formatting in descriptions."]; "argparse.HelpFormatter" -> "argparse.RawDescriptionHelpFormatter" [arrowsize=0.5,style="setlinewidth(0.5)"]; "core.magic_arguments.ArgDecorator" [URL="#IPython.core.magic_arguments.ArgDecorator",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="Base class for decorators to add ArgumentParser information to a method."]; "core.magic_arguments.ArgMethodWrapper" [URL="#IPython.core.magic_arguments.ArgMethodWrapper",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="Base class to define a wrapper for ArgumentParser method."]; "core.magic_arguments.ArgDecorator" -> "core.magic_arguments.ArgMethodWrapper" [arrowsize=0.5,style="setlinewidth(0.5)"]; "core.magic_arguments.MagicArgumentParser" [URL="#IPython.core.magic_arguments.MagicArgumentParser",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="An ArgumentParser tweaked for use by IPython magics."]; "argparse.ArgumentParser" -> "core.magic_arguments.MagicArgumentParser" [arrowsize=0.5,style="setlinewidth(0.5)"]; "core.magic_arguments.MagicHelpFormatter" [fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",tooltip="A HelpFormatter with a couple of changes to meet our needs."]; "argparse.RawDescriptionHelpFormatter" -> "core.magic_arguments.MagicHelpFormatter" [arrowsize=0.5,style="setlinewidth(0.5)"]; "core.magic_arguments.argument" [URL="#IPython.core.magic_arguments.argument",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="Store arguments and keywords to pass to add_argument()."]; "core.magic_arguments.ArgMethodWrapper" -> "core.magic_arguments.argument" [arrowsize=0.5,style="setlinewidth(0.5)"]; "core.magic_arguments.argument_group" [URL="#IPython.core.magic_arguments.argument_group",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="Store arguments and keywords to pass to add_argument_group()."]; "core.magic_arguments.ArgMethodWrapper" -> "core.magic_arguments.argument_group" [arrowsize=0.5,style="setlinewidth(0.5)"]; "core.magic_arguments.defaults" [URL="#IPython.core.magic_arguments.defaults",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="Store arguments and keywords to pass to set_defaults()."]; "core.magic_arguments.ArgMethodWrapper" -> "core.magic_arguments.defaults" [arrowsize=0.5,style="setlinewidth(0.5)"]; "core.magic_arguments.kwds" [URL="#IPython.core.magic_arguments.kwds",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="Provide other keywords to the sub-parser constructor."]; "core.magic_arguments.ArgDecorator" -> "core.magic_arguments.kwds" [arrowsize=0.5,style="setlinewidth(0.5)"]; "core.magic_arguments.magic_arguments" [URL="#IPython.core.magic_arguments.magic_arguments",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="Mark the magic as having argparse arguments and possibly adjust the"]; "core.magic_arguments.ArgDecorator" -> "core.magic_arguments.magic_arguments" [arrowsize=0.5,style="setlinewidth(0.5)"]; }8 Classes¶
-
class
IPython.core.magic_arguments.
MagicArgumentParser
(prog=None, usage=None, description=None, epilog=None, parents=None, formatter_class=<class 'IPython.core.magic_arguments.MagicHelpFormatter'>, prefix_chars='-', argument_default=None, conflict_handler='error', add_help=False)¶ Bases:
argparse.ArgumentParser
An ArgumentParser tweaked for use by IPython magics.
-
__init__
(prog=None, usage=None, description=None, epilog=None, parents=None, formatter_class=<class 'IPython.core.magic_arguments.MagicHelpFormatter'>, prefix_chars='-', argument_default=None, conflict_handler='error', add_help=False)¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
error
(message)¶ Raise a catchable error instead of exiting.
-
parse_argstring
(argstring)¶ Split a string into an argument list and parse that argument list.
-
-
class
IPython.core.magic_arguments.
ArgDecorator
¶ Bases:
object
Base class for decorators to add ArgumentParser information to a method.
-
add_to_parser
(parser, group)¶ Add this object’s information to the parser, if necessary.
-
-
class
IPython.core.magic_arguments.
magic_arguments
(name=None)¶ Bases:
IPython.core.magic_arguments.ArgDecorator
Mark the magic as having argparse arguments and possibly adjust the name.
-
__init__
(name=None)¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
-
class
IPython.core.magic_arguments.
ArgMethodWrapper
(*args, **kwds)¶ Bases:
IPython.core.magic_arguments.ArgDecorator
Base class to define a wrapper for ArgumentParser method.
Child class must define either
_method_name
oradd_to_parser
.-
__init__
(*args, **kwds)¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
add_to_parser
(parser, group)¶ Add this object’s information to the parser.
-
-
class
IPython.core.magic_arguments.
argument
(*args, **kwds)¶ Bases:
IPython.core.magic_arguments.ArgMethodWrapper
Store arguments and keywords to pass to add_argument().
Instances also serve to decorate command methods.
-
class
IPython.core.magic_arguments.
defaults
(*args, **kwds)¶ Bases:
IPython.core.magic_arguments.ArgMethodWrapper
Store arguments and keywords to pass to set_defaults().
Instances also serve to decorate command methods.
-
class
IPython.core.magic_arguments.
argument_group
(*args, **kwds)¶ Bases:
IPython.core.magic_arguments.ArgMethodWrapper
Store arguments and keywords to pass to add_argument_group().
Instances also serve to decorate command methods.
-
add_to_parser
(parser, group)¶ Add this object’s information to the parser.
-
-
class
IPython.core.magic_arguments.
kwds
(**kwds)¶ Bases:
IPython.core.magic_arguments.ArgDecorator
Provide other keywords to the sub-parser constructor.
-
__init__
(**kwds)¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
3 Functions¶
-
IPython.core.magic_arguments.
construct_parser
(magic_func)¶ Construct an argument parser using the function decorations.
-
IPython.core.magic_arguments.
parse_argstring
(magic_func, argstring)¶ Parse the string of arguments for the given magic function.
-
IPython.core.magic_arguments.
real_name
(magic_func)¶ Find the real name of the magic.