opster 4.1

Opster is a command line options parser, intended to make writing command line applications easy and painless. It uses built-in Python types (lists, dictionaries, etc) to define options, which makes configuration clear and concise. Additionally it contains possibility to handle subcommands (i.e. hg commit or svn update).

Supported Python versions: Python >= 2.6 (including 3.x)

Quick example

That’s an example of an option definition

import sys
from opster import command

@command()
def main(message,
         no_newline=('n', False, "don't print a newline")):
    '''Simple echo program'''
    sys.stdout.write(message)
    if not no_newline:
        sys.stdout.write('\n')

if __name__ == '__main__':
    main.command()

Running this program will print help message:

> ./echo.py
echo.py: invalid arguments
echo.py [OPTIONS] MESSAGE

Simple echo program

options:

 -n --no-newline  don't print a newline
 -h --help        show help

As you can see, here we have defined option to not print newline: keyword argument name is a long name for option, default value is a 3-tuple, containing short name for an option (can be empty), default value (on base of which processing is applied - see description) and a help string.

Underscores in long names of options are converted into dashes.

If you are calling a command with option using long name, you can supply it partially. In this case it could look like ./echo.py --no-new. This is also true for subcommands: read about them and everything else you’d like to know in documentation.

Changelog

4.1 (2013.08.19)

• Improve guessing abilities under Python 3 (options in keyword arguments and keyword only arguments are combined now).

4.0 (2013.06.03)

• Infinitely nested subcommands.
• Tuple options (one of given enumerated values).
• A lot of fixes.

Most of changes were done by Oscar Benjamin.

3.7 (2012.05.03)

• Fixed name in usage on Windows.
• Improved and documented preparsing of global options when using subcommands (GH-25).

3.6 (2012.04.23)

• Now commands can have -h option (GH-2).
• Better Windows compatibility (GH-18, GH-20).
• Refactored internal options representation with easier introspectability (GH-19).
• Tests support Python 3 (GH-21).

Thanks for this release are going to Oscar Benjamin, every point in this release is his work.

3.5 (2012.03.25)

• Added command.Error to facilitate easy exits from scripts (GH-12).
• Fixed opster.t output.

3.4 (2012.01.24)

• Fix for installation issue (MANIFEST.in wasn’t included).
• Fix for pep8.py complaints (most of them).
• Fix for script name when calling as a command (and not a dispatcher) (GH-4).
• Fix for some 2to3 issues (GH-5).
• Fixed bug with empty arguments for opster.command (GH-6).
• opster.t is now able to run under dash.
• More output encodings supported (GH-7).
• Coverage support for cram tests (GH-8).
• Fixed combination of varargs and option name with underscore (GH-10).

3.3 (2011.09.04)

• Multicommands: ability to specify global options before specifying name of command

3.2 (2011.08.27)

• Fix for TypeError: func() got multiple values for 'argument'

3.1 (2011.08.27)

• Better aliases support.
• Fixes for options and usage discovery.
• Fix for error handling of dictionary options in multicommands.
• Fix for help not working when global options are defined.

3.0 (2011.08.14)

• Backward incompatible Single commands now don’t attempt to parse. arguments if you call them. Use function.command() attribute (much like earlier function.help()) to parse arguments now.
• Switch to Python 2.6.
• Ability to have few subcommand dispatchers in a single runtime (no single global CMDTABLE dictionary anymore).

2.2 (2011.03.23)

• adjust indentation level in multiline docstrings (compare 1 and 2)
• small fix for internal getopt exception handling

2.1 (2011.01.23)

• fix help display in case middleware returns original function

2.0 (2011.01.23)

• fix help display when there is no __doc__ declared for function
• dict type handling
• .help() attribute for every function, printing help on call

1.2 (2010.12.29)

• fix option display for a list of subcommands if docstring starts with a blank line

1.1 (2010.12.07)

• _completion was failing to work when global options were supplied to command dispatcher

1.0 (2010.12.06)

• when middleware was used and command called without arguments, instead of help, traceback was displayed

0.9.13 (2010.11.18)

• fixed exception handling (cleanup previous fix, actually)
• display only name of application, without full path

0.9.12 (2010.11.02)

• fixed trouble with non-ascii characters in docstrings

0.9.11 (2010.09.19)

• fixed exceptions handling
• autocompletion improvements (skips middleware, ability of options completion)

0.9.10 (2010.04.10)

• if default value of an option is a fuction, always call it (None is passed in case when option is not supplied)
• always call a function if it’s default argument for an option
• some cleanup with better support for python 3
• initial support for autocompletion (borrowed from PIP)

0.9 - 0.9.9 (since 2009.07.13)

Ancient history ;-)