func2cli 0.4.0

Automatic CLIs from functions and their docstrings.

func2cli is a wrapper around the standard Python argparse library that intelligently passes arguments from the command line to one or more Python functions. func2cli reads the type hints and docstrings of those functions and extracts relevant information that is then passed to calls of the add_argument method of argparse parsers.

func2cli can be installed with

pip install func2cli

The example script below uses func2cli to pass command line arguments to one of two simple functions.

# script.py

from func2cli import FunctionParser

def add_three(a: float, b: float, c: float=7) -> float:
    """
    Add three numbers together.

    Parameters
    ----------
    a : The first number to add.
    b : The second number to add.
    c : The third number to add.

    Returns
    -------
    d : The sum of a, b, and c.

    """

    return a + b + c

def modify_string(s: str, reverse: bool=False) -> str:
    """
    Make a string upper case, and maybe reverse it.

    Parameters
    ----------
    s : The original string.
    reverse : Whether to reverse the string.

    Returns
    -------
    output : The modified string.

    """

    output = s.upper()
    if reverse:
        output = output[::-1]

    return output

if __name__ == '__main__':
    parser = FunctionParser([add_three, modify_string])
    output = parser.run()
    print(output)

Usage information is automatically available at the command line.

$ python script.py -h
usage: script.py [-h] {add-three,modify-string} ...

positional arguments:
  {add-three,modify-string}
    add-three           Add three numbers together.
    modify-string       Make a string upper case, and maybe reverse it.

options:
  -h, --help            show this help message and exit

script.py has two allowed positional arguments, one for each of the functions passed to the FunctionParser. Moreover, usage information for individual positional arguments can also be displayed.

$ python script.py add-three -h
usage: script.py add-three [-h] [--c c] a b

Add three numbers together.

positional arguments:
  a           The first number to add.
  b           The second number to add.

options:
  -h, --help  show this help message and exit
  --c c       The third number to add. (default: 7)

func2cli automatically treats parameters with default values as optional command line arguments.

$ python script.py add-three 2 4
13.0
$ python script.py add-three 2 4 --c -8
-2.0

The FunctionParser knows what types are permissible for each argument. For example, the arguments to add-three should all be floats, and so an invalid argument passed at the command line raises an error.

$ python script.py add-three 1 foo
usage: script.py add-three [-h] [--c c] a b
script.py add-three: error: argument b: invalid float value: 'foo'

Boolean arguments should be passed as the strings True and False. This convention breaks with traditional argparse idioms, but makes the resulting command line statements more similar to their corresponding Python function calls.

$ python script.py modify-string -h
usage: script.py modify-string [-h] [--reverse reverse] s

Make a string upper case, and maybe reverse it.

positional arguments:
  s                  The original string.

options:
  -h, --help         show this help message and exit
  --reverse reverse  Whether to reverse the string. (default: False)
$ python script.py modify-string hello --reverse True
OLLEH

By default, func2cli assumes that functions have type hints and docstrings that look like the ones in script.py above. However, func2cli supports arbitrary docstring conventions by allowing the user to pass a custom parse_func argument to FunctionParser.