Important

This documentation covers IPython versions 6.0 and higher. Beginning with version 6.0, IPython stopped supporting compatibility with Python versions lower than 3.3 including all versions of Python 2.7.

If you are looking for an IPython version compatible with Python 2.7, please use the IPython 5.x LTS release and refer to its documentation (LTS is the long term support release).

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.

Here is an elaborated example that uses default parameters in argument and calls the args in the cell magic:

from IPython.core.magic import register_cell_magic
from IPython.core.magic_arguments import (argument, magic_arguments,
                                        parse_argstring)


@magic_arguments()
@argument(
    "--option",
    "-o",
    help=("Add an option here"),
)
@argument(
    "--style",
    "-s",
    default="foo",
    help=("Add some style arguments"),
)
@register_cell_magic
def my_cell_magic(line, cell):
    args = parse_argstring(my_cell_magic, line)
    print(f"{args.option=}")
    print(f"{args.style=}")
    print(f"{cell=}")

In a jupyter notebook, this cell magic can be executed like this:

%%my_cell_magic -o Hello
print("bar")
i = 42

Inheritance diagram:

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

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

Mark the magic as having argparse arguments and possibly adjust the name.

__init__(name=None)

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

Bases: ArgDecorator

Base class to define a wrapper for ArgumentParser method.

Child class must define either _method_name or add_to_parser.

__init__(*args, **kwds)

add_to_parser(parser, group)

Add this object’s information to the parser.

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

Bases: 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: 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: 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: ArgDecorator

Provide other keywords to the sub-parser constructor.

__init__(**kwds)

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.