Commander Py provides an efficent solution to building command line applications, inspired by Node.js' Commander.js

Creating a new program requires importing Program from Commander and creating a new instance of it.

Example:

from Commander import Program

program = Program()

# Program now provides an API to add options and arguments

Information about the program can be given and will be shown by default when the user uses the -h flag. The following options are available:

Adding expected arguments is done using the argument function of a program. Arguments enclosed in angle brackets are required, while any enclosed in square brackets are optional. The argument function also provides the option to add a parse function to execute with the argument received or a default value for the argument.

The values of parsed arguments are available to you via program.arguments, which is a dictionary with the snake-cased argument name as the key.

Example:

from Commander import Program
import sys

program = (Program()
    .argument('<argument1>')
    .argument('[argument2]', default='default value')
    .parse(sys.argv))

print program.arguments 

The output of this program for various command line arguments is as follows:

Options can be added to the program via the option function of a program. Options can have a short name (a hyphen followed by a single character), a long name (two hyphens followed by any combinations of letters, numbers, underscores, and hyphens), and expected arguments (required or optional).

The arguments passed to an option will be available through program.options['option_name'], which is a dictionary with the snake-cased argument name as the key. Option arguments also accept default values and parse functions.

If an option has no arguments, it is considered a flag and will have a value of True if that flag is present and False otherwise.

Example:

from Commander import Program
import sys

program = (Program()
    .option('-r, --regular', description='A description of the option')
    .option('-t, --thing <argument>')
    .option('--optional [optionalArg]')
    .option('-d, --default [defaultArg]', default='some value')
    .parse(sys.argv))

print 'result:', program.options

The ouput of this program for various command line arguments is as follows:

Note: Some key/value pairs have been omitted from the output, only relevant information is shown in the output.

A program's argument and option functions accept a parse function that will be executed with any of the command line arguments associated with that specified argument or option.

Example:

from Commander import Program
import sys

program = (Program()
    .argument('[number]', parse=float)
    .option('-p, --parsed <parsedArg>', parse=(lambda s: s.lower()))
    .parse(sys.argv))

print 'result:', program.arguments['number'] * 10
print 'result:', program.options['parsed']['parsedArg']

The ouput of this program for various command line arguments is as follows:

Note: Some output has been omitted, only relevant information is shown in the output.

A program can be configured to accept an arbitrary number of values that will be made available via either program.options['option_name']['argument_name'] or program.arguments['argument_name']. This can be done by adding ... to the end of an argument name.

If a variadic argument is present, the program will consume available arguments until there is another option, or there are no more options.

Example:

from Commander import Program
import sys

program = (Program()
    .argument('[arg...]')
    .option('-o, --option [opt...]')
    .parse(sys.argv))

print 'result:', program.arguments['arg']
print 'result:', program.options['optiom']['opt']

The ouput of this program for various command line arguments is as follows:

Note: Some output has been omitted, only relevant information is shown in the output.

A program offers a function to allow unknown options, handily called allow_unknown_options. Calling this function will prevent a program from printing an error and exiting upon parsing an unknown option.

If unknown options are allowed, they will be accumulated in program.unknown_arguments

Example:

from Commander import Program
import sys

program = (Program()
    .option('-p, --parsed')
    .option('-f, --force')
    .option('-o, --other')
    .allow_unknown_options()
    .parse(sys.argv))

print 'result:', program.unknown_options

The ouput of this program for various command line arguments is as follows:

A program allows overriding the help via the help function. The help function allows a user to specify custom flags, a custom description message, a custom function to execute, or to omit the help option alltogether.

Example:

from Commander import Program
import sys

def my_help():
    print 'Some custom help message or perfrom some other help actions.'

# To omit the help option:
program = (Program()
    .help(omit=True)
    .parse(sys.argv))

# To change the flags:
program = (Program()
    .help(flags='-c, --custom')
    .parse(sys.argv))

# To change the description message:
program = (Program()
    .help(description='Some help description')
    .parse(sys.argv))

# To call a custom help function:
program = (Program()
    .help(display_help=my_help)
    .parse(sys.argv))