arger 2.2.2

Create ArgumentParser automatically from function signatures

Overview

A lightweight wrapper around argparse to help build CLIs from functions.

Setup

:gear: Installation

Install it directly into an activated virtual environment:

$ pip install arger

:books: Usage

• Create a Python file called test.py:

from arger import Arger


def main(param1: int, param2: str, kw1=None, kw2=False):
    """Example function with types documented in the docstring.

    Args:
        param1: The first parameter.
        param2: The second parameter.
        kw1: This is an optional parameter.
        kw2: This is a boolean. Setting the flag sets it to True.
    """
    print(locals())


arger = Arger(
    main,
    prog="pytest",  # for testing purposes; otherwise, not required
)

if __name__ == "__main__":
    arger.run()

• Here Arger is just a subclass of ArgumentParser. It does not prevent you from using standard argparse features.

• Run this normally with:

$ python test.py -h
usage: pytest [-h] [-k KW1] [-w] param1 param2

Example function with types documented in the docstring.

positional arguments:
  param1             The first parameter.
  param2             The second parameter.

optional arguments:
  -h, --help         show this help message and exit
  -k KW1, --kw1 KW1  This is an optional parameter. (default: None)
  -w, --kw2          This is a boolean. Setting the flag sets it to True. (default: False)

$ python test.py 100 param2
{'param1': 100, 'param2': 'param2', 'kw1': None, 'kw2': False}

• Check out the examples folder and documentation to see more of arger in action. It supports any level of sub-commands.

Features

• Uses the docstring to parse help descriptions for arguments. Supports:
  • google
  • numpy
  • rst
• Flags will be generated from parameter names.
  1. E.g., def main(param: ...) -> -p, --param
  2. If needed, you can declare them inside the docstring, like :param arg1: -a --arg this is the document.
• One can use the Argument class to pass any values to the parser.add_argument function.
• The decorated functions can be composed to form nested sub-commands of any level.
• Most standard types are supported. Please see the examples for more supported types with code examples.
• No external dependency other than the standard library.

NOTE

• *args is supported, but there is no **kwargs support yet.
• Any optional argument starting with an underscore is not passed to the parser. They are considered private to the function's implementation. Some parameter names have special meaning:
  • _namespace_ -> gets the output from ArgumentParser.parse_args()
  • _arger_ -> gets the parser instance

Argparser enhancements

• web-ui : https://github.com/nirizr/argparseweb
• extra actions : https://github.com/kadimisetty/action-hero
• automatic shell completions using argcomplete