Usage¶

Defining commands¶

A command is a function decorated with @command. mando tries to extract as much as information as possible from the function’s docstring and its signature.

The paragraph of the docstring is the command’s help. For optimal results it shouldn’t be longer than one line. The second paragraph contains the command’s description, which can be as long as needed. If only one paragraph is present, it is used for both the help and the description. You can document the parameters with the common Sphinx’s :param:: syntax.

For example, this program generates the following helps:

from mando import command, main

@command
def cmd(foo, bar):
    '''Here stands the help.

    And here the description of this useless command.

    :param foo: Well, the first arg.
    :param bar: Obviously the second arg. Nonsense.'''

    print(arg, bar)

if __name__ == '__main__':
    main()

$ python command.py -h
usage: command.py [-h] {cmd} ...

positional arguments:
  {cmd}
    cmd       Here stands the help.

optional arguments:
  -h, --help  show this help message and exit
$ python command.py cmd -h
usage: command.py cmd [-h] foo bar

And here the description of this useless command.

positional arguments:
  foo         Well, the first arg.
  bar         Obviously the second arg. Nonsense.

optional arguments:
  -h, --help  show this help message and exit

Long and short options (flags)¶

You can specify short options in the docstring as well, with the :param: syntax. The recognized formats are these:

:param -O: Option help

:param --option: Option help

:param -o, --output: Option help

Example:

from mando import command, main


@command
def ex(foo, b=None, spam=None):
    '''Nothing interesting.

    :param foo: Bla bla.
    :param -b: A little flag.
    :param -s, --spam: Spam spam spam spam.'''

    print(foo, b, spam)

if __name__ == '__main__':
    main()

Usage:

$ python short_options.py ex -h
usage: short_options.py ex [-h] [-b B] [-s SPAM] foo

Nothing interesting.

positional arguments:
  foo                   Bla bla.

optional arguments:
  -h, --help            show this help message and exit
  -b B                  A little flag.
  -s SPAM, --spam SPAM  Spam spam spam spam.
$ python short_options.py ex 2
('2', None, None)
$ python short_options.py ex 2 -b 8
('2', '8', None)
$ python short_options.py ex 2 -b 8 -s 9
('2', '8', '9')
$ python short_options.py ex 2 -b 8 --spam 9
('2', '8', '9')

How default arguments are handled¶

If an argument has a default, then mando takes it as an optional argument, while those which do not have a default are interpreted as positional arguments. Here are the actions taken by mando when a default argument is encountered:

Default argument type	What mando specifies in `add_argument()`
bool	action `store_true` or `store_false` is added
list	action `append` is added.
int	type `int()` is added.
float	type `float()` is added.
str	type `str()` is added.

So, for example, if a default argument is an integer, mando will automatically convert command line arguments to int():

from mando import command, main


@command
def po(a=2, b=3):
    print(a ** b)


if __name__ == '__main__':
    main()

$ python default_args.py po -h
usage: default_args.py po [-h] [-a A] [-b B]

optional arguments:
  -h, --help  show this help message and exit
  -a A
  -b B
$ python default_args.py po -a 4 -b 9
262144

Note that passing the arguments positionally does not work, because argparse expects optional args and a and b are already filled with defaults:

$ python default_args.py po
8
$ python default_args.py po 9 8
usage: default_args.py [-h] {po} ...
default_args.py: error: unrecognized arguments: 9 8

To overcome this, mando allows you to specify positional arguments’ types in the docstring, as explained in the next section.

Adding type and metavar in the docstring¶

This is especially useful for positional arguments, but it is usually used for all type of arguments. The notation is this: :param {opt-name} <type>: Help. <type> must be a built-in type among the following:

<i>, <int>, <integer> to cast to int();

also <n>, <num>, <number> to cast to int();

<s>, <str>, <string> to cast to str();

<f>, <float> to cast to float().

mando also adds <type> as a metavar. Actual usage:

from mando import command, main


@command
def pow(a, b, mod=None):
    '''Mimic Python's pow() function.

    :param a <float>: The base.
    :param b <float>: The exponent.
    :param -m, --mod <int>: Modulus.'''

    if mod is not None:
        print((a ** b) % mod)
    else:
        print(a ** b)


if __name__ == '__main__':
    main()

$ python types.py pow -h
usage: types.py pow [-h] [-m <int>] a b

Mimic Python's pow() function.

positional arguments:
a                     The base.
b                     The exponent.

optional arguments:
-h, --help            show this help message and exit
-m <int>, --mod <int>
                    Modulus.
$ python types.py pow 5 8
390625.0
$ python types.py pow 4.5 8.3
264036.437449
$ python types.py pow 5 8 -m 8
1.0

Adding type in the signature¶

If running Python 3, mando can use type annotations to convert argument types. Since type annotations can be any callable, this allows more flexibility than the hard-coded list of types permitted by the docstring method:

from mando import command, main

# Note: don't actually do this.
def double_int(n):
    return int(n) * 2


@command
def dup(string, times: double_int):
    """
    Duplicate text.

    :param string: The text to duplicate.
    :param times: How many times to duplicate.
    """
    print(string * times)


if __name__ == "__main__":
    main()

$ python3 test.py dup "test " 2
test test test test
$ python3 test.py dup "test " foo
usage: test.py dup [-h] string times
test.py dup: error: argument times: invalid double_int value: 'foo'

Overriding arguments with `@arg`¶

You may need to specify some argument to argparse, and it is not possible to include in the docstring. mando provides the @arg decorator to accomplish this. Its signature is as follows: @arg(arg_name, *args, **kwargs), where arg_name must be among the function’s arguments, while the remaining arguments will be directly passed to argparse.add_argument(). Note that this decorator will override other arguments that mando inferred either from the defaults or from the docstring.

`@command` Arguments¶

There are three special arguments to the @command() decorator to allow for special processing for the decorated function. The first argument, also available as keyword name='alias_name' will allow for an alias of the command. The second argument, also available as keyword doctype='rest' allows for Numpy or Google formatted docstrings to be used. The third is only available as keyword formatter_class='argparse_formatter_class' to format the display of the docstring.

Aliasing Commands¶

A common use-case for this is represented by a function with underscores in it. Usually commands have dashes instead. So, you may specify the aliasing name to the @command() decorator, this way:

@command('very-powerful-cmd')
def very_powerful_cmd(arg, verbose=False):
    pass

And call it as follows:

$ python prog.py very-powerful-cmd 2 --verbose

Note that the original name will be discarded and won’t be usable.

Other Docstring Formats¶

There are three commonly accepted formats for docstrings. The Sphinx docstring, and the mando dialect of Sphinx described in this documentation are treated equally and is the default documentation style named rest for REStructured Text. The other two available styles are numpy and google. This allows projects that use mando, but already have docstrings in these other formats not to have to convert the docstrings.

An example of using a Numpy formatted docstring in mando:

@command(doctype='numpy')
def simple_numpy_docstring(arg1, arg2="string"):
    '''One line summary.

    Extended description.

    Parameters
    ----------
    arg1 : int
        Description of `arg1`
    arg2 : str
        Description of `arg2`

    Returns
    -------
    str
        Description of return value.
    '''
    return int(arg1) * arg2

An example of using a Google formatted docstring in mando:

@program.command(doctype='google')
def simple_google_docstring(arg1, arg2="string"):
    '''One line summary.

    Extended description.

    Args:
      arg1(int): Description of `arg1`
      arg2(str): Description of `arg2`
    Returns:
      str: Description of return value.
    '''
    return int(arg1) * arg2

Formatter Class¶

For the help display there is the opportunity to use special formatters. Any argparse compatible formatter class can be used. There is an alternative formatter class available with mando that will display on ANSI terminals.

The ANSI formatter class has to be imported from mando and used as follows:

from mando.rst_text_formatter import RSTHelpFormatter

@command(formatter_class=RSTHelpFormatter)
def pow(a, b, mod=None):
    '''Mimic Python's pow() function.

    :param a <float>: The base.
    :param b <float>: The exponent.
    :param -m, --mod <int>: Modulus.'''

    if mod is not None:
        print((a ** b) % mod)
    else:
        print(a ** b)

Shell autocompletion¶

Mando supports autocompletion via the optional dependency argcomplete. If that package is installed, mando detects it automatically without the need to do anything else.