Python Library Reference

6.21 optparse -- More powerful command line option parser

optparse is a more convenient, flexible, and powerful library for parsing command-line options than getopt. optparse uses a more declarative style of command-line parsing: you create an instance of OptionParser, populate it with options, and parse the command line. optparse allows users to specify options in the conventional GNU/POSIX syntax, and additionally generates usage and help messages for you.

Here's an example of using optparse in a simple script:

from optparse 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, for example:

<yourscript> --file=outfile -q

As it parses the command line, optparse sets attributes of the options object returned by parse_args() based on user-supplied command-line values. When parse_args() returns from parsing this command line, options.filename will be "outfile" and options.verbose will be False. optparse supports both long and short options, allows short options to be merged together, and allows options to be associated with their arguments in a variety of ways. Thus, the following command lines are all equivalent to the above example:

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

Additionally, users can run one of

<yourscript> -h
<yourscript> --help

and optparse 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

where the value of yourscript is determined at runtime (normally from sys.argv[0]).

• 6.21.1 Background
  • 6.21.1.1 Terminology
  • 6.21.1.2 What are options for?
  • 6.21.1.3 What are positional arguments for?
• 6.21.2 Tutorial
  • 6.21.2.1 Understanding option actions
  • 6.21.2.2 The store action
  • 6.21.2.3 Handling boolean (flag) options
  • 6.21.2.4 Other actions
  • 6.21.2.5 Default values
  • 6.21.2.6 Generating help
  • 6.21.2.7 Printing a version string
  • 6.21.2.8 How optparse handles errors
  • 6.21.2.9 Putting it all together
• 6.21.3 Reference Guide
  • 6.21.3.1 Populating the parser
  • 6.21.3.2 Defining options
  • 6.21.3.3 Standard option actions
  • 6.21.3.4 Standard option types
  • 6.21.3.5 Querying and manipulating your option parser
  • 6.21.3.6 Conflicts between options
• 6.21.4 Option Callbacks
  • 6.21.4.1 Defining a callback option
  • 6.21.4.2 How callbacks are called
  • 6.21.4.3 Raising errors in a callback
  • 6.21.4.4 Callback example 1: trivial callback
  • 6.21.4.5 Callback example 2: check option order
  • 6.21.4.6 Callback example 3: check option order (generalized)
  • 6.21.4.7 Callback example 4: check arbitrary condition
  • 6.21.4.8 Callback example 5: fixed arguments
  • 6.21.4.9 Callback example 6: variable arguments

Python Library Reference

Previous: 6.20 getopt Up: 6. Generic Operating System Next: 6.21.1 Background

Release 2.4c1, documentation updated on 18 November 2004.