Module: core.magic_arguments — IPython 5.1.0 documentation

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

## 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)
  `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)

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

## 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.