mando

library0.8.2pypypi✓ verified 24d ago

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.

http-networking

pip install mando

package ↗homepage ↗

INSTALL

IMPORT

SIG · MANDO

mando

http-networkingpythonv0.8.2

Install

1.6s avg

Import

53ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.8.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.054s · 18MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.052s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

command

✓ from mando import command

main

✓ from mando import main

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()

mando --version

Debug

Known issues

breakingMando 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).

affects: <0.8.0

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

affects: All

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

affects: All

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

affects: <0.8.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'mando'

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)

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>'

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'

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

Upgrade

Version history

0.8.2latest on PyPI · released Oct 20, 2024

Audit

Dependencies

argcompleteoptionalOptional, for shell autocompletion functionality.

Agent activity

12 hits · last 30 days

node

Amazon

Resources

packagehttps://pypi.org/project/mando/ ↗

homepagehttps://mando.readthedocs.org/ ↗