core.magic_arguments

Module: core.magic_arguments

Inheritance diagram for IPython.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.

Classes

ArgDecorator

class IPython.core.magic_arguments.ArgDecorator

Bases: object

Base class for decorators to add ArgumentParser information to a method.

__init__()

x.__init__(...) initializes x; see help(type(x)) for signature

add_to_parser(parser, group)

Add this object’s information to the parser, if necessary.

MagicArgumentParser

class IPython.core.magic_arguments.MagicArgumentParser(prog=None, usage=None, description=None, epilog=None, version=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, version=None, parents=None, formatter_class=<class 'IPython.core.magic_arguments.MagicHelpFormatter'>, prefix_chars='-', argument_default=None, conflict_handler='error', add_help=False)

add_argument(dest, ..., name=value, ...) add_argument(option_string, option_string, ..., name=value, ...)

add_argument_group(*args, **kwargs)

add_mutually_exclusive_group(**kwargs)

add_subparsers(**kwargs)

convert_arg_line_to_args(arg_line)

error(message)

Raise a catchable error instead of exiting.

exit(status=0, message=None)

format_help()

format_usage()

format_version()

get_default(dest)

parse_args(args=None, namespace=None)

parse_argstring(argstring)

Split a string into an argument list and parse that argument list.

parse_known_args(args=None, namespace=None)

print_help(file=None)

print_usage(file=None)

print_version(file=None)

register(registry_name, value, object)

set_defaults(**kwargs)

MagicHelpFormatter

class IPython.core.magic_arguments.MagicHelpFormatter(prog, indent_increment=2, max_help_position=24, width=None)

Bases: argparse.RawDescriptionHelpFormatter

A HelpFormatter which dedents but otherwise preserves indentation.

__init__(prog, indent_increment=2, max_help_position=24, width=None)

add_argument(action)

add_arguments(actions)

add_text(text)

add_usage(usage, actions, groups, prefix=None)

end_section()

format_help()

start_section(heading)

argument

class IPython.core.magic_arguments.argument(*args, **kwds)

Bases: IPython.core.magic_arguments.ArgDecorator

Store arguments and keywords to pass to add_argument().

Instances also serve to decorate command methods.

__init__(*args, **kwds)

add_to_parser(parser, group)

Add this object’s information to the parser.

argument_group

class IPython.core.magic_arguments.argument_group(*args, **kwds)

Bases: IPython.core.magic_arguments.ArgDecorator

Store arguments and keywords to pass to add_argument_group().

Instances also serve to decorate command methods.

__init__(*args, **kwds)

add_to_parser(parser, group)

Add this object’s information to the parser.

kwds

class IPython.core.magic_arguments.kwds(**kwds)

Bases: IPython.core.magic_arguments.ArgDecorator

Provide other keywords to the sub-parser constructor.

__init__(**kwds)

add_to_parser(parser, group)

Add this object’s information to the parser, if necessary.

magic_arguments

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)

add_to_parser(parser, group)

Add this object’s information to the parser, if necessary.

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.