Overview

The command line project provides a simple way to provide a feature packed command line interface to an existing python method (similar to the goals of the optparse module). eg:

def someFunc(someArg, someFlag = False):
    print "Flag value =", someFlag
    print "Arg value =", someArg

from cmdline import Command
command = Command(someFunc, "An example to show usage of command line",
    "Email bug reports to bugs@example.com")
command.add_flag('s', 'setflag', 'Set the flag', 'someFlag')
command.add_argument('SOMEARG', 'Some float argument', 'someArg', float)
command.invoke()

This is can now be used from the command line in the fashion of standard unix command line utilities;

$ python test.py 3
Flag value =  False
Arg value = 3.0

Flags can be set

$ python test.py -s 5.3
Flag value =  True
Arg value = 5.3

Help can be called

$ python test.py --help
Usage: test.py [OPTIONS] SOMEARG
An example to show usage of command line

Arguments
    SOMEARG               Some float argument

Mandatory arguments to long flags are mandatory for short options too
    -h, --help            Show this help page
    -s, --setflag         Set the flag

Email bug reports to bugs@example.com

Setting configuration trees

Sometimes it isn't appropriate to call a function, especially when the number of configuration options grows. That's why it is also possible to set values in an arbitrary object;

# For some python object...
config.general.verbose = False
config.general.filename = ""
config.i386.bounds_checks = False
config.i386.overflow_checks = False

from cmdline import ConfigSetter
command = ConfigSetter(config, "An example command line app")
command.add_flag('v', 'verbose', 'Verbose logging', 'general.verbose')
command.add_flag(None, 'bounds-checks', 'Debugging bounds checks', 'i386.bounds_checks')
command.add_flag(None, 'overflow-checks', 'Debugging overflow checks', 'i386.overflow_checks')
command.add_argument('FILENAME', 'Filename to compile', 'general.filename')
command.invoke()

print "filename:", config.general.filename
print "bounds checks:", config.i386.bounds_checks

Which when run gives

$ python test.py --bounds-checks somefile.txt
filename: somefile.txt
bounds checks: True

Advantages

So why should you use this instead of optparse? I actually wrote this before becoming aware of optparse, and once I noticed it, was a little annoyed. That said,

I believe this is quicker, easier and cleaner to implement in code, while giving a full command line interface.
Help (usage) option for free. This help is in the format of standard unix command line tools
It also has the advantage of completely seperating the command line interface from actual functionality.
It uses the well tested getopt module, so actual command line parsing is well tested.
Lots of validating user input; If you want an int, either you get an int, or the user gets an error that they didn't enter an int.
The code that checks for correct format uses a simple user provided callable object (eg: int, float, str...). This can be easily customised to parse user defined types (simply write a method to parse an object from a string)
Checks for correctness of arguments, something getopt doesn't do (it is outside of it's functional spec). eg: if the user enters too many, not enough, or the wrong sort of argument, they get an error.
When usage is printed, long strings are wrapped correctly at the end of the line
When usage is printed, flags are sorted alphabetically

Restrictions

No optional arguments to flags (difficult, as getopt doesn't seem to support them).
At the moment, no support for repeated flags (all repeated flags converge into one)

Technology

The command line module is written in python, and uses the getopt library for parsing the command line.

While the examples show a unix type shell, it also works correctly in Microsoft Windows.

Downloads

Release 0.20, 30 Jan 2007
Update the library to be more like a standard module (naming conventions, etc), plus general code improvements. Added a 'config' style backend, where flags can be set in a configuration tree (instead of invoking a function).

Release 0.11, 02 April 2005
Release following review on python mailing list. Includes better python code practice (eg: properties, new style classes), and code style improvements.

Release 0.10, 14 March 2005
Initial release of cmdline module