Awesome
This repo and Python module are unmaintained.
Why cmdln.py?
cmdln.py
fixes some of the design flaws in cmd.py
and uses the
optparse
module so that it is more useful (and convenient) for
implementing command-line scripts/shells.
The main differences are:
- Instead of passing a command line to subcommand handlers, already parsed options and an args list are provided. This is much more convenient when the complexity of commands grows to have options, arguments with spaces, etc.
- By default the help for a subcommand is the associated method's docstring. Default help output is also much nicer and some template vars can be used to automatically fill in some details.
- Defining command aliases is easy (using a new decorator).
- A
.main()
method is provided to make using yourCmdln
subclass a little cleaner. - The error handling (and associated hooks) have been improved so that
trapping and dealing with errors in sub-command handlers (the
do_*
methods) can be done -- as might be wanted for a slighty more robust shell.
Install notes and intro docs are below. Please send any feedback to [Trent Mick](mailto:trentm at google's mail thing).
Python Versions
cmdln 2.x versions support Python 2.6, 2.7, 3.3 and 3.4.
cmdln 1.x versions support Python 2.5, 2.6 and 2.7.
Install
To install it in your Python installation run one of the following:
pip install cmdln
pypm install cmdln # if you use ActivePython (activestate.com/activepython)
easy_install cmdln # if this is the best you have
python setup.py install
However, everything you need to run this is in "lib/cmdln.py". If it is easier for you, you can just copy that file to somewhere on your PYTHONPATH (to use as a module) or executable path (to use as a script).
Introduction
cmdln.py
is an extension of Python's default cmd.py
module that
provides "a simple framework for writing line-oriented command
interpreters". The idea (with both cmd.py
and cmdln.py
) is to be
able to quickly build multi-sub-command tools (think cvs
or svn
)
and/or simple interactive shells (think gdb
or pdb
). cmdln.py
's
extensions make it more natural to write sub-commands, integrate
optparse for simple
option processing, and make having good command documentation easier.
For example, here is most of the scaffolding for the svn
status command. (Note:
Some options were removed and the doc string truncated for brevity. See
examples/svn.py for a more complete scaffold
re-implementation of the svn
command-line interface.)
#!/usr/bin/env python
from __future__ import print_function
import sys
import cmdln
class MySVN(cmdln.Cmdln):
name = "svn"
@cmdln.alias("stat", "st")
@cmdln.option("-u", "--show-updates", action="store_true",
help="display update information")
@cmdln.option("-v", "--verbose", action="store_true",
help="print extra information")
def do_status(self, subcmd, opts, *paths):
"""${cmd_name}: print the status of working copy files and directories
${cmd_usage}
${cmd_option_list}
"""
print("'svn %s' opts: %s" % (subcmd, opts))
print("'svn %s' paths: %s" % (subcmd, paths))
if __name__ == "__main__":
svn = MySVN()
sys.exit(svn.main())
The base cmdln.Cmdln
class is providing a number of things for free
here. (1) There is a reasonable default help string:
$ python svn.py
Usage:
svn COMMAND [ARGS...]
svn help [COMMAND]
Commands:
help (?) give detailed help on a specific command
status (st, stat) print the status of working copy files and dire...
(2) A default help
command is provided for getting detailed help on
specific sub-commands. This is how many such tools already work (e.g.
svn
and p4
, the command-line interface for the Perforce source
control system).
$ python svn.py help status
status (stat, st): print the status of working copy files and directories.
Usage:
svn status [PATHS...]
Options:
-h, --help show this help message and exit
-v, --verbose print extra information
-u, --show-updates display update information
(3) It makes parsing the command line easy (with optparse
integration):
$ python svn.py status -v foo bar baz
'svn status' opts: {'show_updates': None, 'verbose': True}
'svn status' paths: ('foo', 'bar', 'baz')
and (4) defining command aliases easy:
$ python svn.py st -v foo bar baz
'svn st' opts: {'show_updates': None, 'verbose': True}
'svn st' paths: ('foo', 'bar', 'baz')
Read the Getting Started docs next.
Development
Run the test suite on your current python
version:
make test
To attempt to run with all supported versions:
make testall
On a particular version:
make test34