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.

Common errors

```
ModuleNotFoundError: No module named 'mando'
```
cause The `mando` library is not installed in the Python environment you are currently using, or the Python interpreter cannot find it.

fix Install the `mando` package using pip: `pip install mando`
```
zsh: command not found: <your_script_name>.py (or bash: <your_script_name>.py: command not found)
```
cause The shell cannot find or execute your Python script because it's not in the system's PATH, not marked as executable, or the shebang (e.g., `#!/usr/bin/env python3`) is missing or incorrect.

fix Ensure the script has a correct shebang (e.g., `#!/usr/bin/env python3` at the top), make it executable (`chmod +x <your_script_name>.py`), and then run it with `./<your_script_name>.py` or explicitly with `python <your_script_name>.py`.
```
error: argument <argument_name>: invalid <type> value: '<user_input_value>'
```
cause The input provided for an argument does not match the expected type specified in the function's type annotation (e.g., providing a non-integer string for an argument annotated as `int`), and `mando` (via `argparse`) failed to convert it.

fix Ensure the command-line argument matches the expected Python type annotation for that parameter. For example, if an argument is `age: int`, provide a numeric value like `--age 30` instead of `--age 'thirty'`.
```
ImportError: cannot import name 'command' from 'mando'
```
cause While the `mando` package might be installed, the specific `command` (or `main`, `arg`) object is not found during the import, possibly due to a typo in the import statement or an outdated `mando` version where these names might have changed (though unlikely for 0.8.2).

fix Verify the exact import statement is `from mando import command, main` (and `arg` if used), and ensure there are no typos. If problems persist, consider reinstalling `mando` to ensure all components are correctly available: `pip install --upgrade mando`.

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 →