dispatch

A low information-redundancy cli framework for a quick and dirty way of converting python scripts to a command line tool.

Inspired by fire and click.

Install

pip install py-dispatch

Demo

# example.py
import dispatch
import sys

@dispatch.command
def hello(name: str, verbose: bool, debug: bool, file: str = 'stdout'):
    '''Run the 'hello' command line interface.

    :v verbose: Run the command verbosly
    :name: Name of the person you are saying hello to.
    :file: Either stdout or stderr
    '''
    if debug:
        print(f'debugging with {name}', file=getattr(sys, file))
    else:
        print(f'hello, {name}', file=getattr(sys, file))

if __name__ == '__main__':
    hello()

$ python example.py --help

Run the 'hello' command line interface.

Usage:
    hello [options]

Options:
        --name      Name of the person you are saying hello to.
    -v, --verbose   Run the command verbosly
        --debug
        --file      Either stdout or stderr (default: stdout)
    -h, --help      Get help.

Arguments

Arguments can be retrieved in two ways, either from Command.args or with positional only arguments. When a cli function is run, it is replaced with a Command object so the cli function can use the command in it's own body.

@dispatch.command
def cli(verbose: bool):
    print(cli.args)

Running this cli with python cli.py hello --verbose these are some args will result in ['hello', 'these', 'are', 'some', 'args'].

The Other way to get arguments is to give the cli function a positional only argument at the beginning of the parameters list.

@dispatch.command
def cli(*args, verbose: bool):
    print(args)

Running this cli as before will have the same result. However, it only works when the args tuple is the first function parameter.

Properties of Flags

Because flags are specified by function arguments, the properties of flags are a little bit weird.

Boolean Flags

All boolean flags have a default of False.

A positional argument with no default and no type annotation is assumed to be a boolean flag and will default to a value of False.

@disptch.command
def cli(verbose):
    if verbose:
        print('the verbose flag has been given')
    else:
        print('using default of False for verbose')

Flag Types

Dispatch uses type annotations to infer flag types and will use those annotations to convert the arguments given.

# cli.py
@dispatch.command
def cli(num: complex, decimal: float):
    pass

When the program cli.py is executed it will convert each argument to its type.

python cli.py --num=5+3j --decimal=5.9

For this command, the parser internals will eventually call complex('5+3j') and float('5.9') before giving the values as function arguments. What this means is that you can use any type as long it has an __init__ function that takes one argument. However there are exceptions