### Navigation

- index
- modules |
- next |
- previous |
- home|
- search|
- documentation »
- The IPython API »

# 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 'argparse.HelpFormatter'>, 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 'argparse.HelpFormatter'>, 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)

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

### Navigation

- index
- modules |
- next |
- previous |
- home|
- search|
- documentation »
- The IPython API »