Mando: Create Python CLI apps

0.8.2 · active · verified Thu Apr 09

mando is a lightweight Python library that wraps `argparse` to simplify the creation of command-line interface (CLI) applications. It allows developers to define CLI commands using Python functions and decorators, automatically generating argument parsers from function signatures and docstrings. Key features include support for Python 3-style type annotations for argument conversion, and compatibility with various docstring formats (Sphinx, Google, NumPy). It also supports shell autocompletion through the optional `argcomplete` package. The current version, 0.8.2, was released on October 20, 2024, and focuses on Python 3 compatibility.

Warnings

breaking Mando versions 0.8.x and above have dropped support for Python 2. Users on older Python 2 environments should use an earlier `mando` version or migrate to Python 3.
Fix: Upgrade to Python 3 and install `mando>=0.8.0` or pin `mando<0.8.0` for Python 2 projects (though this is not recommended).
gotcha Mando automatically infers command arguments from function signatures and docstrings. By default, it expects Sphinx-style docstrings. If your project uses Google or NumPy style docstrings, you may need to explicitly configure this for optimal parsing.
Fix: Consult `mando` documentation on 'Other Docstring Formats' for configuration options if using non-Sphinx styles.
gotcha For fine-grained control over argument parsing (e.g., specifying `metavar`, `choices`, or overriding inferred types), use the `@arg` decorator. This decorator allows passing arguments directly to `argparse.add_argument()` and will override information inferred from the function signature or docstring.
Fix: Decorate your command function parameters with `@arg('param_name', ...)` before the `@command` decorator to customize individual arguments.
deprecated Some system package managers (e.g., for certain Linux distributions) may offer older versions of `mando` (e.g., 0.6.4, 0.7.1) that are not up-to-date with the latest features or Python 3 compatibility.
Fix: Always prefer installing `mando` via `pip install mando` to ensure you receive the latest stable version and its full feature set, especially for Python 3 development.

Install

pip install mando Install stable version

Imports

command
```
from mando import command
```
main
```
from mando import main
```

Quickstart

This quickstart demonstrates how to define a command-line function using the `@command` decorator and make it executable with `main()`. It handles arguments and optional flags, showcasing how `mando` parses them from function signatures and docstrings. To run, save as `my_cli.py` and execute `python my_cli.py echo "hello world" --capitalize` or `python my_cli.py echo "hello world"`.

from mando import command, main

@command
def echo(text, capitalize=False):
    '''Echo the given text.
    :param text: The text to echo.
    :param capitalize: Whether to capitalize the text.
    '''
    if capitalize:
        text = text.upper()
    print(text)

if __name__ == '__main__':
    main()

view raw JSON →