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.

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: