Optik 1.5 =========

Optik is a powerful, flexible, extensible, easy-to-use command-line parsing library for Python. Using Optik, you can add intelligent, sophisticated handling of command-line options to your scripts with very little overhead.

Here's an example of using Optik to add some command-line options to a simple script:

from optik import OptionParser [...] parser = OptionParser() parser.add_option("-f", "--file", dest="filename", help="write report to FILE", metavar="FILE") parser.add_option("-q", "--quiet", action="store_false", dest="verbose", default=True, help="don't print status messages to stdout")

(options, args) = parser.parse_args()

With these few lines of code, users of your script can now do the "usual thing" on the command-line:

<yourscript> -f outfile --quiet <yourscript> -qfoutfile <yourscript> --file=outfile -q <yourscript> --quiet --file outfile

all of which result in the 'options' object looking like this:

options.filename == "outfile" options.verbose == 0

Even niftier, users can run one of

<yourscript> -h <yourscript> --help

and Optik will print out a brief summary of your script's options:

usage: <yourscript> [options]

options: -h, --help show this help message and exit -f FILE, --file=FILE write report to FILE -q, --quiet don't print status messages to stdout

That's just a taste of the flexibility Optik gives you in parsing your command-line. See the documentation included in the package for details.

REQUIREMENTS & INSTALLATION ---------------------------

Optik requires Python 2.2 or greater.

Installing Optik is easy; just use the standard incantion for installing Python modules:

python setup.py install

As of Python 2.3, Optik is included in the Python standard library as 'optparse'. Python 2.3 included Optik 1.4.1 plus a few small bug fixes. If you want to use the new features in Optik 1.5 (see CHANGES.txt), you'll need to "import optik" in your source code. Otherwise, you can "import optparse", and your code will work with Python 2.3 and up without additional requirements.

AVAILABILITY ------------

The latest version of Optik can be found at

http://www.gerg.ca/software/optik/download.html http://optik.sourceforge.net/download.html

CHANGES SINCE 1.5a1 -------------------

* Remove the old, broken "ignore" option conflict handler -- was only needed for compatibility with Optik 1.1.

* Move documentation into docs/ directory, and write a script (mkpydoc) to automatically convert it to LaTeX for the Python standard library manual. Many documentation improvements. (1.5a2)

* SF #997100: attempt to avoid triggering a FutureWarning in __repr__() when using id() with "%x" (1.5a2).

* SF #1048725: fix typo in Values.__eq__() introduced in 1.5a1.

* Fix test script so it plays nice when being run with other test scripts (as in the Python test suite) (1.5a2).

OTHER CHANGES SINCE 1.4.1 -------------------------

* Optik now requires Python 2.2 or later.

* Add expansion of default values in help text: the string "%default" in an option's help string is expanded to str() of that option's default value, or "none" if no default value.

* SF bug #955889: option default values that happen to be strings are now processed in the same way as values from the command line; this allows generation of nicer help when using custom types. Can be disabled with parser.set_process_default_values(False).

* SF bug #960515: don't crash when generating help for callback options that specify 'type', but not 'dest' or 'metavar'.

* SF feature #815264: change the default help format for short options that take an argument from e.g. "-oARG" to "-o ARG"; add set_short_opt_delimiter() and set_long_opt_delimiter() methods to HelpFormatter to allow (slight) customization of the formatting.

* SF patch #736940: internationalize Optik: all built-in user- targeted literal strings are passed through gettext.gettext(). Also added po/ directory for message catalog and translations, so that Optik-based applications have a single place to go for translations of Optik's built-in messags. Include translations for Danish and German (thanks to Frederik S. Olesen and Martin v. Löwis respectively), and partial translations for French (by me).

* SF bug #878453 (Python): respect $COLUMNS environment variable for wrapping help output.

* SF feature #964317: allow type objects to specify option types; allow "str" as an alias for "string".

* SF feature #988122: expand "%prog" in the 'description' passed to OptionParser, just like in the 'usage' and 'version' strings. (This is *not* done in the 'description' passed to OptionGroup.)

* Added HTML-formatted docs to the source distribution (in addition to the reStructuredText source files).

* Added three new examples: custom_source.py, custom_type.py, and no_help.py.