<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>optparse – Command line option parser to replace getopt. — Python Module of the Week</title>
<link rel="stylesheet" href="../_static/sphinxdoc.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.132',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="top" title="Python Module of the Week" href="../index.html" />
<link rel="up" title="Generic Operating System Services" href="../generic_os.html" />
<link rel="next" title="argparse – Command line option and argument parsing." href="../argparse/index.html" />
<link rel="prev" title="getopt – Command line option parsing" href="../getopt/index.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="../argparse/index.html" title="argparse – Command line option and argument parsing."
accesskey="N">next</a> |</li>
<li class="right" >
<a href="../getopt/index.html" title="getopt – Command line option parsing"
accesskey="P">previous</a> |</li>
<li><a href="../contents.html">PyMOTW</a> »</li>
<li><a href="../generic_os.html" accesskey="U">Generic Operating System Services</a> »</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">optparse – Command line option parser to replace getopt.</a><ul>
<li><a class="reference internal" href="#creating-an-optionparser">Creating an OptionParser</a><ul>
<li><a class="reference internal" href="#defining-options">Defining Options</a></li>
<li><a class="reference internal" href="#parsing-a-command-line">Parsing a Command Line</a></li>
</ul>
</li>
<li><a class="reference internal" href="#short-and-long-form-options">Short and Long-Form Options</a></li>
<li><a class="reference internal" href="#comparing-with-getopt">Comparing with getopt</a></li>
<li><a class="reference internal" href="#option-values">Option Values</a><ul>
<li><a class="reference internal" href="#setting-defaults">Setting Defaults</a></li>
<li><a class="reference internal" href="#type-conversion">Type Conversion</a></li>
<li><a class="reference internal" href="#enumerations">Enumerations</a></li>
</ul>
</li>
<li><a class="reference internal" href="#option-actions">Option Actions</a><ul>
<li><a class="reference internal" href="#constants">Constants</a></li>
<li><a class="reference internal" href="#boolean-flags">Boolean Flags</a></li>
<li><a class="reference internal" href="#repeating-options">Repeating Options</a></li>
<li><a class="reference internal" href="#callbacks">Callbacks</a></li>
</ul>
</li>
<li><a class="reference internal" href="#help-messages">Help Messages</a><ul>
<li><a class="reference internal" href="#organizing-options">Organizing Options</a></li>
<li><a class="reference internal" href="#application-settings">Application Settings</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="../getopt/index.html"
title="previous chapter">getopt – Command line option parsing</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="../argparse/index.html"
title="next chapter">argparse – Command line option and argument parsing.</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/optparse/index.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="module-optparse">
<span id="optparse-command-line-option-parser-to-replace-getopt"></span><h1>optparse – Command line option parser to replace getopt.<a class="headerlink" href="#module-optparse" title="Permalink to this headline">¶</a></h1>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Purpose:</th><td class="field-body">Command line option parser to replace <a class="reference internal" href="../getopt/index.html#module-getopt" title="getopt: Command line option parsing"><tt class="xref py py-mod docutils literal"><span class="pre">getopt</span></tt></a>.</td>
</tr>
<tr class="field"><th class="field-name">Python Version:</th><td class="field-body">2.3</td>
</tr>
</tbody>
</table>
<p>The <a class="reference internal" href="#module-optparse" title="optparse: Command line option parser to replace :mod:`getopt`."><tt class="xref py py-mod docutils literal"><span class="pre">optparse</span></tt></a> module is a modern alternative for command line
option parsing that offers several features not available in
<a class="reference internal" href="../getopt/index.html#module-getopt" title="getopt: Command line option parsing"><tt class="xref py py-mod docutils literal"><span class="pre">getopt</span></tt></a>, including type conversion, option callbacks, and
automatic help generation. There are many more features to
<a class="reference internal" href="#module-optparse" title="optparse: Command line option parser to replace :mod:`getopt`."><tt class="xref py py-mod docutils literal"><span class="pre">optparse</span></tt></a> than can be covered here, but this section will
introduce some of the more commonly used capabilities.</p>
<div class="section" id="creating-an-optionparser">
<h2>Creating an OptionParser<a class="headerlink" href="#creating-an-optionparser" title="Permalink to this headline">¶</a></h2>
<p>There are two phases to parsing options with <a class="reference internal" href="#module-optparse" title="optparse: Command line option parser to replace :mod:`getopt`."><tt class="xref py py-mod docutils literal"><span class="pre">optparse</span></tt></a>. First,
the <tt class="xref py py-class docutils literal"><span class="pre">OptionParser</span></tt> instance is constructed and configured with
the expected options. Then a sequence of options is fed in and
processed.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">()</span>
</pre></div>
</div>
<p>Usually, once the parser has been created, each option is added to the
parser explicitly, with information about what to do when the option
is encountered on the command line. It is also possible to pass a list
of options to the <tt class="xref py py-class docutils literal"><span class="pre">OptionParser</span></tt> constructor, but that form is
not used as frequently.</p>
<div class="section" id="defining-options">
<h3>Defining Options<a class="headerlink" href="#defining-options" title="Permalink to this headline">¶</a></h3>
<p>Options should be added one at a time using the <tt class="xref py py-func docutils literal"><span class="pre">add_option()</span></tt>
method. Any un-named string arguments at the beginning of the argument
list are treated as option names. To create aliases for an option
(i.e., to have a short and long form of the same option), simply pass
multiple names.</p>
</div>
<div class="section" id="parsing-a-command-line">
<h3>Parsing a Command Line<a class="headerlink" href="#parsing-a-command-line" title="Permalink to this headline">¶</a></h3>
<p>After all of the options are defined, the command line is parsed by
passing a sequence of argument strings to <tt class="xref py py-func docutils literal"><span class="pre">parse_args()</span></tt>. By
default, the arguments are taken from <tt class="docutils literal"><span class="pre">sys.argv[1:]</span></tt>, but a list can
be passed explicitly as well. The options are processed using the
GNU/POSIX syntax, so option and argument values can be mixed in the
sequence.</p>
<p>The return value from <tt class="xref py py-func docutils literal"><span class="pre">parse_args()</span></tt> is a two-part tuple
containing an <tt class="xref py py-class docutils literal"><span class="pre">Values</span></tt> instance and the list of arguments to
the command that were not interpreted as options. The default
processing action for options is to store the value using the name
given in the <em>dest</em> argument to <tt class="xref py py-func docutils literal"><span class="pre">add_option()</span></tt>. The
<tt class="xref py py-class docutils literal"><span class="pre">Values</span></tt> instance returned by <tt class="xref py py-func docutils literal"><span class="pre">parse_args()</span></tt> holds the
option values as attributes, so if an option’s <tt class="xref py py-data docutils literal"><span class="pre">dest</span></tt> is set to
<tt class="docutils literal"><span class="pre">"myoption"</span></tt>, the value is accessed as <tt class="docutils literal"><span class="pre">options.myoption</span></tt>.</p>
</div>
</div>
<div class="section" id="short-and-long-form-options">
<h2>Short and Long-Form Options<a class="headerlink" href="#short-and-long-form-options" title="Permalink to this headline">¶</a></h2>
<p>Here is a simple example with three different options: a boolean
option (<tt class="docutils literal"><span class="pre">-a</span></tt>), a simple string option (<tt class="docutils literal"><span class="pre">-b</span></tt>), and an integer
option (<tt class="docutils literal"><span class="pre">-c</span></tt>).</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">()</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-a'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store_true"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-b'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">"b"</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-c'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">"c"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s">"int"</span><span class="p">)</span>
<span class="k">print</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">'-a'</span><span class="p">,</span> <span class="s">'-bval'</span><span class="p">,</span> <span class="s">'-c'</span><span class="p">,</span> <span class="s">'3'</span><span class="p">])</span>
</pre></div>
</div>
<p>The options on the command line are parsed with the same rules that
<tt class="xref py py-func docutils literal"><span class="pre">getopt.gnu_getopt()</span></tt> uses, so there are two ways to pass values
to single character options. The example above uses both forms,
<tt class="docutils literal"><span class="pre">-bval</span></tt> and <tt class="docutils literal"><span class="pre">-c</span> <span class="pre">val</span></tt>.</p>
<div class="highlight-python"><pre>$ python optparse_short.py
(<Values at 0x1004db560: {'a': True, 'c': 3, 'b': 'val'}>, [])</pre>
</div>
<p>Notice that the type of the value associated with <tt class="docutils literal"><span class="pre">'c'</span></tt> in the
output is an integer, since the <tt class="xref py py-class docutils literal"><span class="pre">OptionParser</span></tt> was told to
convert the argument before storing it.</p>
<p>Unlike with <a class="reference internal" href="../getopt/index.html#module-getopt" title="getopt: Command line option parsing"><tt class="xref py py-mod docutils literal"><span class="pre">getopt</span></tt></a>, “long” option names are not handled any
differently by <a class="reference internal" href="#module-optparse" title="optparse: Command line option parser to replace :mod:`getopt`."><tt class="xref py py-mod docutils literal"><span class="pre">optparse</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">()</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'--noarg'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store_true"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'--witharg'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">"witharg"</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'--witharg2'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">"witharg2"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s">"int"</span><span class="p">)</span>
<span class="k">print</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span> <span class="s">'--noarg'</span><span class="p">,</span> <span class="s">'--witharg'</span><span class="p">,</span> <span class="s">'val'</span><span class="p">,</span> <span class="s">'--witharg2=3'</span> <span class="p">])</span>
</pre></div>
</div>
<p>And the results are similar:</p>
<div class="highlight-python"><pre>$ python optparse_long.py
(<Values at 0x1004da560: {'noarg': True, 'witharg': 'val', 'witharg2': 3}>, [])</pre>
</div>
</div>
<div class="section" id="comparing-with-getopt">
<h2>Comparing with getopt<a class="headerlink" href="#comparing-with-getopt" title="Permalink to this headline">¶</a></h2>
<p>Since <a class="reference internal" href="#module-optparse" title="optparse: Command line option parser to replace :mod:`getopt`."><tt class="xref py py-mod docutils literal"><span class="pre">optparse</span></tt></a> is supposed to replace <a class="reference internal" href="../getopt/index.html#module-getopt" title="getopt: Command line option parsing"><tt class="xref py py-mod docutils literal"><span class="pre">getopt</span></tt></a>, this
example re-implements the same example program used in the section
about <a class="reference internal" href="../getopt/index.html#module-getopt" title="getopt: Command line option parsing"><tt class="xref py py-mod docutils literal"><span class="pre">getopt</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
<span class="kn">import</span> <span class="nn">sys</span>
<span class="k">print</span> <span class="s">'ARGV :'</span><span class="p">,</span> <span class="n">sys</span><span class="o">.</span><span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">:]</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">()</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-o'</span><span class="p">,</span> <span class="s">'--output'</span><span class="p">,</span>
<span class="n">dest</span><span class="o">=</span><span class="s">"output_filename"</span><span class="p">,</span>
<span class="n">default</span><span class="o">=</span><span class="s">"default.out"</span><span class="p">,</span>
<span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-v'</span><span class="p">,</span> <span class="s">'--verbose'</span><span class="p">,</span>
<span class="n">dest</span><span class="o">=</span><span class="s">"verbose"</span><span class="p">,</span>
<span class="n">default</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span>
<span class="n">action</span><span class="o">=</span><span class="s">"store_true"</span><span class="p">,</span>
<span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'--version'</span><span class="p">,</span>
<span class="n">dest</span><span class="o">=</span><span class="s">"version"</span><span class="p">,</span>
<span class="n">default</span><span class="o">=</span><span class="mf">1.0</span><span class="p">,</span>
<span class="nb">type</span><span class="o">=</span><span class="s">"float"</span><span class="p">,</span>
<span class="p">)</span>
<span class="n">options</span><span class="p">,</span> <span class="n">remainder</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
<span class="k">print</span> <span class="s">'VERSION :'</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">version</span>
<span class="k">print</span> <span class="s">'VERBOSE :'</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">verbose</span>
<span class="k">print</span> <span class="s">'OUTPUT :'</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">output_filename</span>
<span class="k">print</span> <span class="s">'REMAINING :'</span><span class="p">,</span> <span class="n">remainder</span>
</pre></div>
</div>
<p>Notice how the options <tt class="docutils literal"><span class="pre">-o</span></tt> and <tt class="docutils literal"><span class="pre">--output</span></tt> are aliased by being
added at the same time. Either option can be used on the command line.
The short form:</p>
<div class="highlight-python"><pre>$ python optparse_getoptcomparison.py -o output.txt
ARGV : ['-o', 'output.txt']
VERSION : 1.0
VERBOSE : False
OUTPUT : output.txt
REMAINING : []</pre>
</div>
<p>or the long form:</p>
<div class="highlight-python"><pre>$ python optparse_getoptcomparison.py --output output.txt
ARGV : ['--output', 'output.txt']
VERSION : 1.0
VERBOSE : False
OUTPUT : output.txt
REMAINING : []</pre>
</div>
<p>Any unique prefix of the long option can also be used:</p>
<div class="highlight-python"><pre>$ python optparse_getoptcomparison.py --out output.txt
ARGV : ['--out', 'output.txt']
VERSION : 1.0
VERBOSE : False
OUTPUT : output.txt
REMAINING : []</pre>
</div>
</div>
<div class="section" id="option-values">
<h2>Option Values<a class="headerlink" href="#option-values" title="Permalink to this headline">¶</a></h2>
<p>The default processing action is to store the argument to the option.
If a type is provided, the argument value is converted to that type
before it is stored.</p>
<div class="section" id="setting-defaults">
<h3>Setting Defaults<a class="headerlink" href="#setting-defaults" title="Permalink to this headline">¶</a></h3>
<p>Since options are by definition optional, applications should
establish default behavior when an option is not given on the command
line. A default value for an individual option can be provided when
the option is defined.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">()</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-o'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s">"default value"</span><span class="p">)</span>
<span class="n">options</span><span class="p">,</span> <span class="n">args</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
<span class="k">print</span> <span class="n">options</span><span class="o">.</span><span class="n">o</span>
</pre></div>
</div>
<div class="highlight-python"><pre>$ python optparse_default.py
default value
$ python optparse_default.py -o "different value"
different value</pre>
</div>
<p>Defaults can also be loaded after the options are defined using
keyword arguments to <tt class="xref py py-func docutils literal"><span class="pre">set_defaults()</span></tt>.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">()</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-o'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store"</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">set_defaults</span><span class="p">(</span><span class="n">o</span><span class="o">=</span><span class="s">'default value'</span><span class="p">)</span>
<span class="n">options</span><span class="p">,</span> <span class="n">args</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
<span class="k">print</span> <span class="n">options</span><span class="o">.</span><span class="n">o</span>
</pre></div>
</div>
<p>This form is useful when loading defaults from a configuration file or
other source, instead of hard-coding them.</p>
<div class="highlight-python"><pre>$ python optparse_set_defaults.py
default value
$ python optparse_set_defaults.py -o "different value"
different value</pre>
</div>
<p>All defined options are available as attributes of the <tt class="xref py py-class docutils literal"><span class="pre">Values</span></tt>
instance returned by <tt class="xref py py-func docutils literal"><span class="pre">parse_args()</span></tt> so applications do not need to
check for the presence of an option before trying to use its value.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">()</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-o'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store"</span><span class="p">)</span>
<span class="n">options</span><span class="p">,</span> <span class="n">args</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
<span class="k">print</span> <span class="n">options</span><span class="o">.</span><span class="n">o</span>
</pre></div>
</div>
<p>If no default value is given for an option, and the option is not
specified on the command line, its value is <tt class="xref docutils literal"><span class="pre">None</span></tt>.</p>
<div class="highlight-python"><pre>$ python optparse_no_default.py
None
$ python optparse_no_default.py -o "different value"
different value</pre>
</div>
</div>
<div class="section" id="type-conversion">
<h3>Type Conversion<a class="headerlink" href="#type-conversion" title="Permalink to this headline">¶</a></h3>
<p><a class="reference internal" href="#module-optparse" title="optparse: Command line option parser to replace :mod:`getopt`."><tt class="xref py py-mod docutils literal"><span class="pre">optparse</span></tt></a> will convert option values from strings to integers,
floats, longs, and complex values. To enable the conversion, specify
the <em>type</em> of the option as an argument to <tt class="xref py py-func docutils literal"><span class="pre">add_option()</span></tt>.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">()</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-i'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s">"int"</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-f'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s">"float"</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-l'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s">"long"</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-c'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s">"complex"</span><span class="p">)</span>
<span class="n">options</span><span class="p">,</span> <span class="n">args</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
<span class="k">print</span> <span class="s">'int : </span><span class="si">%-16r</span><span class="s"> </span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="nb">type</span><span class="p">(</span><span class="n">options</span><span class="o">.</span><span class="n">i</span><span class="p">),</span> <span class="n">options</span><span class="o">.</span><span class="n">i</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'float : </span><span class="si">%-16r</span><span class="s"> </span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="nb">type</span><span class="p">(</span><span class="n">options</span><span class="o">.</span><span class="n">f</span><span class="p">),</span> <span class="n">options</span><span class="o">.</span><span class="n">f</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'long : </span><span class="si">%-16r</span><span class="s"> </span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="nb">type</span><span class="p">(</span><span class="n">options</span><span class="o">.</span><span class="n">l</span><span class="p">),</span> <span class="n">options</span><span class="o">.</span><span class="n">l</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'complex: </span><span class="si">%-16r</span><span class="s"> </span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="nb">type</span><span class="p">(</span><span class="n">options</span><span class="o">.</span><span class="n">c</span><span class="p">),</span> <span class="n">options</span><span class="o">.</span><span class="n">c</span><span class="p">)</span>
</pre></div>
</div>
<p>If an option’s value cannot be converted to the specified type, an
error is printed and the program exits.</p>
<div class="highlight-python"><pre>$ python optparse_types.py -i 1 -f 3.14 -l 1000000 -c 1+2j
int : <type 'int'> 1
float : <type 'float'> 3.14
long : <type 'long'> 1000000
complex: <type 'complex'> (1+2j)
$ python optparse_types.py -i a
Usage: optparse_types.py [options]
optparse_types.py: error: option -i: invalid integer value: 'a'</pre>
</div>
<p>Custom conversions can be created by subclassing the <tt class="xref py py-class docutils literal"><span class="pre">Option</span></tt>
class. See the standard library documentation for complete details.</p>
</div>
<div class="section" id="enumerations">
<h3>Enumerations<a class="headerlink" href="#enumerations" title="Permalink to this headline">¶</a></h3>
<p>The <tt class="xref py py-const docutils literal"><span class="pre">choice</span></tt> type provides validation using a list of candidate
strings. Set <em>type</em> to choice and provide the list of valid values
using the <em>choices</em> argument to <tt class="xref py py-func docutils literal"><span class="pre">add_option()</span></tt>.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">()</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-c'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s">'choice'</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="p">[</span><span class="s">'a'</span><span class="p">,</span> <span class="s">'b'</span><span class="p">,</span> <span class="s">'c'</span><span class="p">])</span>
<span class="n">options</span><span class="p">,</span> <span class="n">args</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
<span class="k">print</span> <span class="s">'Choice:'</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">c</span>
</pre></div>
</div>
<p>Invalid inputs result in an error message that shows the allowed list
of values.</p>
<div class="highlight-python"><pre>$ python optparse_choice.py -c a
Choice: a
$ python optparse_choice.py -c b
Choice: b
$ python optparse_choice.py -c d
Usage: optparse_choice.py [options]
optparse_choice.py: error: option -c: invalid choice: 'd' (choose from
'a', 'b', 'c')</pre>
</div>
</div>
</div>
<div class="section" id="option-actions">
<h2>Option Actions<a class="headerlink" href="#option-actions" title="Permalink to this headline">¶</a></h2>
<p>Unlike <a class="reference internal" href="../getopt/index.html#module-getopt" title="getopt: Command line option parsing"><tt class="xref py py-mod docutils literal"><span class="pre">getopt</span></tt></a>, which only <em>parses</em> the options, <a class="reference internal" href="#module-optparse" title="optparse: Command line option parser to replace :mod:`getopt`."><tt class="xref py py-mod docutils literal"><span class="pre">optparse</span></tt></a>
is a full option <em>processing</em> library. Options can trigger different
actions, specified by the action argument to
<tt class="xref py py-func docutils literal"><span class="pre">add_option()</span></tt>. Supported actions include storing the argument
(singly, or as part of a list), storing a constant value when the
option is encountered (including special handling for true/false
values for boolean switches), counting the number of times an option
is seen, and calling a callback. The default action is
<tt class="xref py py-const docutils literal"><span class="pre">store</span></tt>, and does not need to be specified explicitly.</p>
<div class="section" id="constants">
<h3>Constants<a class="headerlink" href="#constants" title="Permalink to this headline">¶</a></h3>
<p>When options represent a selection of fixed alternatives, such as
operating modes of an application, creating separate explicit options
makes it easier to document them. The <tt class="xref py py-const docutils literal"><span class="pre">store_const</span></tt> action is
intended for this purpose.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">()</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'--earth'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store_const"</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s">'earth'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">'element'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s">'earth'</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'--air'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_const'</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s">'air'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">'element'</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'--water'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_const'</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s">'water'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">'element'</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'--fire'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_const'</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s">'fire'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">'element'</span><span class="p">)</span>
<span class="n">options</span><span class="p">,</span> <span class="n">args</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
<span class="k">print</span> <span class="n">options</span><span class="o">.</span><span class="n">element</span>
</pre></div>
</div>
<p>The <tt class="xref py py-const docutils literal"><span class="pre">store_const</span></tt> action associates a constant value in the
application with the option specified by the user. Several options
can be configured to store different constant values to the same
<em>dest</em> name, so the application only has to check a single setting.</p>
<div class="highlight-python"><pre>$ python optparse_store_const.py
earth
$ python optparse_store_const.py --fire
fire</pre>
</div>
</div>
<div class="section" id="boolean-flags">
<h3>Boolean Flags<a class="headerlink" href="#boolean-flags" title="Permalink to this headline">¶</a></h3>
<p>Boolean options are implemented using special actions for storing true
and false constant values.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">()</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-t'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_true'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">'flag'</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-f'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_false'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">'flag'</span><span class="p">)</span>
<span class="n">options</span><span class="p">,</span> <span class="n">args</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
<span class="k">print</span> <span class="s">'Flag:'</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">flag</span>
</pre></div>
</div>
<p>True and false versions of the same flag can be created by configuring
their <em>dest</em> name to the same value.</p>
<div class="highlight-python"><pre>$ python optparse_boolean.py
Flag: False
$ python optparse_boolean.py -t
Flag: True
$ python optparse_boolean.py -f
Flag: False</pre>
</div>
</div>
<div class="section" id="repeating-options">
<h3>Repeating Options<a class="headerlink" href="#repeating-options" title="Permalink to this headline">¶</a></h3>
<p>There are three ways to handle repeated options. The default is to
overwrite any existing value so that the last option specified is
used. The <tt class="xref py py-const docutils literal"><span class="pre">store</span></tt> action works this way.</p>
<p>Using the <tt class="xref py py-const docutils literal"><span class="pre">append</span></tt> action, it is possible to accumulate values
as an option is repeated, creating a list of values. Append mode is
useful when multiple responses are allowed, and specifying them
separately is easier for the user than constructing a parsable syntax.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">()</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-o'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"append"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">'outputs'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="p">[])</span>
<span class="n">options</span><span class="p">,</span> <span class="n">args</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
<span class="k">print</span> <span class="n">options</span><span class="o">.</span><span class="n">outputs</span>
</pre></div>
</div>
<p>The order of the values given on the command line is preserved, in
case it is important for the application.</p>
<div class="highlight-python"><pre>$ python optparse_append.py
[]
$ python optparse_append.py -o a.out
['a.out']
$ python optparse_append.py -o a.out -o b.out
['a.out', 'b.out']</pre>
</div>
<p>Sometimes it is enough to know how many times an option was given, and
the associated value is not needed. For example, many applications
allow the user to repeat the <tt class="docutils literal"><span class="pre">-v</span></tt> option to increase the level of
verbosity of their output. The <tt class="xref py py-const docutils literal"><span class="pre">count</span></tt> action increments a
value each time the option appears.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">()</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-v'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"count"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">'verbosity'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-q'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_const'</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">'verbosity'</span><span class="p">)</span>
<span class="n">options</span><span class="p">,</span> <span class="n">args</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
<span class="k">print</span> <span class="n">options</span><span class="o">.</span><span class="n">verbosity</span>
</pre></div>
</div>
<p>Since the <tt class="docutils literal"><span class="pre">-v</span></tt> option doesn’t take an argument, it can be repeated
using the syntax <tt class="docutils literal"><span class="pre">-vv</span></tt> as well as through separate individual
options.</p>
<div class="highlight-python"><pre>$ python optparse_count.py
1
$ python optparse_count.py -v
2
$ python optparse_count.py -v -v
3
$ python optparse_count.py -vv
3
$ python optparse_count.py -q
0</pre>
</div>
</div>
<div class="section" id="callbacks">
<h3>Callbacks<a class="headerlink" href="#callbacks" title="Permalink to this headline">¶</a></h3>
<p>Beside saving the arguments for options directly, it is possible to
define callback functions to be invoked when the option is encountered
on the command line. Callbacks for options take four arguments: the
<tt class="xref py py-class docutils literal"><span class="pre">Option</span></tt> instance causing the callback, the option string from
the command line, any argument value associated with the option, and
the <tt class="xref py py-class docutils literal"><span class="pre">OptionParser</span></tt> instance doing the parsing work.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
<span class="k">def</span> <span class="nf">flag_callback</span><span class="p">(</span><span class="n">option</span><span class="p">,</span> <span class="n">opt_str</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">parser</span><span class="p">):</span>
<span class="k">print</span> <span class="s">'flag_callback:'</span>
<span class="k">print</span> <span class="s">'</span><span class="se">\t</span><span class="s">option:'</span><span class="p">,</span> <span class="nb">repr</span><span class="p">(</span><span class="n">option</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'</span><span class="se">\t</span><span class="s">opt_str:'</span><span class="p">,</span> <span class="n">opt_str</span>
<span class="k">print</span> <span class="s">'</span><span class="se">\t</span><span class="s">value:'</span><span class="p">,</span> <span class="n">value</span>
<span class="k">print</span> <span class="s">'</span><span class="se">\t</span><span class="s">parser:'</span><span class="p">,</span> <span class="n">parser</span>
<span class="k">return</span>
<span class="k">def</span> <span class="nf">with_callback</span><span class="p">(</span><span class="n">option</span><span class="p">,</span> <span class="n">opt_str</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">parser</span><span class="p">):</span>
<span class="k">print</span> <span class="s">'with_callback:'</span>
<span class="k">print</span> <span class="s">'</span><span class="se">\t</span><span class="s">option:'</span><span class="p">,</span> <span class="nb">repr</span><span class="p">(</span><span class="n">option</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'</span><span class="se">\t</span><span class="s">opt_str:'</span><span class="p">,</span> <span class="n">opt_str</span>
<span class="k">print</span> <span class="s">'</span><span class="se">\t</span><span class="s">value:'</span><span class="p">,</span> <span class="n">value</span>
<span class="k">print</span> <span class="s">'</span><span class="se">\t</span><span class="s">parser:'</span><span class="p">,</span> <span class="n">parser</span>
<span class="k">return</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">()</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'--flag'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"callback"</span><span class="p">,</span> <span class="n">callback</span><span class="o">=</span><span class="n">flag_callback</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'--with'</span><span class="p">,</span>
<span class="n">action</span><span class="o">=</span><span class="s">"callback"</span><span class="p">,</span>
<span class="n">callback</span><span class="o">=</span><span class="n">with_callback</span><span class="p">,</span>
<span class="nb">type</span><span class="o">=</span><span class="s">"string"</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s">"Include optional feature"</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">'--with'</span><span class="p">,</span> <span class="s">'foo'</span><span class="p">,</span> <span class="s">'--flag'</span><span class="p">])</span>
</pre></div>
</div>
<p>In this example, the <tt class="docutils literal"><span class="pre">--with</span></tt> option is configured to take a string
argument (other types such as integers and floats are support as
well).</p>
<div class="highlight-python"><pre>$ python optparse_callback.py
with_callback:
option: <Option at 0x1004db3b0: --with>
opt_str: --with
value: foo
parser: <optparse.OptionParser instance at 0x100460200>
flag_callback:
option: <Option at 0x1004db320: --flag>
opt_str: --flag
value: None
parser: <optparse.OptionParser instance at 0x100460200></pre>
</div>
<p>Callbacks can be configured to take multiple arguments using the <em>nargs</em>
option.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
<span class="k">def</span> <span class="nf">with_callback</span><span class="p">(</span><span class="n">option</span><span class="p">,</span> <span class="n">opt_str</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">parser</span><span class="p">):</span>
<span class="k">print</span> <span class="s">'with_callback:'</span>
<span class="k">print</span> <span class="s">'</span><span class="se">\t</span><span class="s">option:'</span><span class="p">,</span> <span class="nb">repr</span><span class="p">(</span><span class="n">option</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'</span><span class="se">\t</span><span class="s">opt_str:'</span><span class="p">,</span> <span class="n">opt_str</span>
<span class="k">print</span> <span class="s">'</span><span class="se">\t</span><span class="s">value:'</span><span class="p">,</span> <span class="n">value</span>
<span class="k">print</span> <span class="s">'</span><span class="se">\t</span><span class="s">parser:'</span><span class="p">,</span> <span class="n">parser</span>
<span class="k">return</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">()</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'--with'</span><span class="p">,</span>
<span class="n">action</span><span class="o">=</span><span class="s">"callback"</span><span class="p">,</span>
<span class="n">callback</span><span class="o">=</span><span class="n">with_callback</span><span class="p">,</span>
<span class="nb">type</span><span class="o">=</span><span class="s">"string"</span><span class="p">,</span>
<span class="n">nargs</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s">"Include optional feature"</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">'--with'</span><span class="p">,</span> <span class="s">'foo'</span><span class="p">,</span> <span class="s">'bar'</span><span class="p">])</span>
</pre></div>
</div>
<p>In this case, the arguments are passed to the callback function as a tuple via
the value argument.</p>
<div class="highlight-python"><pre>$ python optparse_callback_nargs.py
with_callback:
option: <Option at 0x1004da2d8: --with>
opt_str: --with
value: ('foo', 'bar')
parser: <optparse.OptionParser instance at 0x100460128></pre>
</div>
</div>
</div>
<div class="section" id="help-messages">
<h2>Help Messages<a class="headerlink" href="#help-messages" title="Permalink to this headline">¶</a></h2>
<p>The <tt class="xref py py-class docutils literal"><span class="pre">OptionParser</span></tt> automatically includes a help option to all
option sets, so the user can pass <tt class="docutils literal"><span class="pre">--help</span></tt> on the command line to
see instructions for running the program. The help message includes
all of the options with an indication of whether or not they take an
argument. It is also possible to pass help text to
<tt class="xref py py-class docutils literal"><span class="pre">add_option()</span></tt> to give a more verbose description of an option.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">()</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'--no-foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store_true"</span><span class="p">,</span>
<span class="n">default</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span>
<span class="n">dest</span><span class="o">=</span><span class="s">"foo"</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s">"Turn off foo"</span><span class="p">,</span>
<span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'--with'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store"</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s">"Include optional feature"</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
</pre></div>
</div>
<p>The options are listed in alphabetical order, with aliases included on
the same line. When the option takes an argument, the <tt class="docutils literal"><span class="pre">dest</span></tt> name is
included as an argument name in the help output. The help text is
printed in the right column.</p>
<div class="highlight-python"><pre>$ python optparse_help.py --help
Usage: optparse_help.py [options]
Options:
-h, --help show this help message and exit
--no-foo Turn off foo
--with=WITH Include optional feature</pre>
</div>
<p>The name <tt class="docutils literal"><span class="pre">WITH</span></tt> printed with the option <tt class="docutils literal"><span class="pre">--with</span></tt> comes from the
destination variable for the option. For cases where the internal
variable name is descriptive enough to serve in the documentation, the
<em>metavar</em> argument can be used to set a different name.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">()</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'--no-foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store_true"</span><span class="p">,</span>
<span class="n">default</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span>
<span class="n">dest</span><span class="o">=</span><span class="s">"foo"</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s">"Turn off foo"</span><span class="p">,</span>
<span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'--with'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store"</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s">"Include optional feature"</span><span class="p">,</span>
<span class="n">metavar</span><span class="o">=</span><span class="s">'feature_NAME'</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
</pre></div>
</div>
<p>The value is printed exactly as it is given, without any changes to
capitalization or punctuation.</p>
<div class="highlight-python"><pre>$ python optparse_metavar.py -h
Usage: optparse_metavar.py [options]
Options:
-h, --help show this help message and exit
--no-foo Turn off foo
--with=feature_NAME Include optional feature</pre>
</div>
<div class="section" id="organizing-options">
<h3>Organizing Options<a class="headerlink" href="#organizing-options" title="Permalink to this headline">¶</a></h3>
<p>Many applications include sets of related options. For example,
<strong class="command">rpm</strong> includes separate options for each of its operating
modes. <a class="reference internal" href="#module-optparse" title="optparse: Command line option parser to replace :mod:`getopt`."><tt class="xref py py-mod docutils literal"><span class="pre">optparse</span></tt></a> uses <em>option groups</em> to organize options in
the help output. The option values are all still saved in a single
<tt class="xref py py-class docutils literal"><span class="pre">Values</span></tt> instance, so the namespace for option names is still
flat.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">()</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-q'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_const'</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s">'query'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">'mode'</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s">'Query'</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-i'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_const'</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s">'install'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">'mode'</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s">'Install'</span><span class="p">)</span>
<span class="n">query_opts</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionGroup</span><span class="p">(</span>
<span class="n">parser</span><span class="p">,</span> <span class="s">'Query Options'</span><span class="p">,</span>
<span class="s">'These options control the query mode.'</span><span class="p">,</span>
<span class="p">)</span>
<span class="n">query_opts</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-l'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_const'</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s">'list'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">'query_mode'</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s">'List contents'</span><span class="p">)</span>
<span class="n">query_opts</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-f'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_const'</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s">'file'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">'query_mode'</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s">'Show owner of file'</span><span class="p">)</span>
<span class="n">query_opts</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-a'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_const'</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s">'all'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">'query_mode'</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s">'Show all packages'</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option_group</span><span class="p">(</span><span class="n">query_opts</span><span class="p">)</span>
<span class="n">install_opts</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionGroup</span><span class="p">(</span>
<span class="n">parser</span><span class="p">,</span> <span class="s">'Installation Options'</span><span class="p">,</span>
<span class="s">'These options control installation.'</span><span class="p">,</span>
<span class="p">)</span>
<span class="n">install_opts</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'--hash'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_true'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s">'Show hash marks as progress indication'</span><span class="p">)</span>
<span class="n">install_opts</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'--force'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">'install_force'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_true'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s">'Install, regardless of depdencies or existing version'</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option_group</span><span class="p">(</span><span class="n">install_opts</span><span class="p">)</span>
<span class="k">print</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
</pre></div>
</div>
<p>Each group has its own section title and description, and the options
are displayed together.</p>
<div class="highlight-python"><pre>$ python optparse_groups.py -h
Usage: optparse_groups.py [options]
Options:
-h, --help show this help message and exit
-q Query
-i Install
Query Options:
These options control the query mode.
-l List contents
-f Show owner of file
-a Show all packages
Installation Options:
These options control installation.
--hash Show hash marks as progress indication
--force Install, regardless of depdencies or existing version</pre>
</div>
</div>
<div class="section" id="application-settings">
<h3>Application Settings<a class="headerlink" href="#application-settings" title="Permalink to this headline">¶</a></h3>
<p>The automatic help generation facilities support configuration
settings to control several aspects of the help output. The program’s
<em>usage</em> string, which shows how the positional arguments are expected,
can be set when the <tt class="xref py py-class docutils literal"><span class="pre">OptionParser</span></tt> is created.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">(</span><span class="n">usage</span><span class="o">=</span><span class="s">'%prog [options] <arg1> <arg2> [<arg3>...]'</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-a'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store_true"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-b'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">"b"</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-c'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">"c"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s">"int"</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
</pre></div>
</div>
<p>The literal value <tt class="docutils literal"><span class="pre">%prog</span></tt> is expanded to the name of the program at
runtime, so it can reflect the full path to the script. If the script
is run by <strong class="command">python</strong>, instead of running directly, the script
name is used.</p>
<div class="highlight-python"><pre>$ python optparse_usage.py -h
Usage: optparse_usage.py [options] <arg1> <arg2> [<arg3>...]
Options:
-h, --help show this help message and exit
-a
-b B
-c C</pre>
</div>
<p>The program name can be changed using the <em>prog</em> argument.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">(</span><span class="n">usage</span><span class="o">=</span><span class="s">'%prog [options] <arg1> <arg2> [<arg3>...]'</span><span class="p">,</span>
<span class="n">prog</span><span class="o">=</span><span class="s">'my_program_name'</span><span class="p">,</span>
<span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-a'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store_true"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-b'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">"b"</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-c'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">"c"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s">"int"</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
</pre></div>
</div>
<p>It is generally a bad idea to hard-code the program name in this way,
though, because if the program is renamed the help will not reflect
the change.</p>
<div class="highlight-python"><pre>$ python optparse_prog.py -h
Usage: my_program_name [options] <arg1> <arg2> [<arg3>...]
Options:
-h, --help show this help message and exit
-a
-b B
-c C</pre>
</div>
<p>The application version can be set using the <em>version</em> argument. When
a value is provided, <a class="reference internal" href="#module-optparse" title="optparse: Command line option parser to replace :mod:`getopt`."><tt class="xref py py-mod docutils literal"><span class="pre">optparse</span></tt></a> automatically adds a
<tt class="docutils literal"><span class="pre">--version</span></tt> option to the parser.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">(</span><span class="n">usage</span><span class="o">=</span><span class="s">'%prog [options] <arg1> <arg2> [<arg3>...]'</span><span class="p">,</span>
<span class="n">version</span><span class="o">=</span><span class="s">'1.0'</span><span class="p">,</span>
<span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
</pre></div>
</div>
<p>When the user runs the program with the <tt class="docutils literal"><span class="pre">--version</span></tt> option,
<a class="reference internal" href="#module-optparse" title="optparse: Command line option parser to replace :mod:`getopt`."><tt class="xref py py-mod docutils literal"><span class="pre">optparse</span></tt></a> prints the version string and then exits.</p>
<div class="highlight-python"><pre>$ python optparse_version.py -h
Usage: optparse_version.py [options] <arg1> <arg2> [<arg3>...]
Options:
--version show program's version number and exit
-h, --help show this help message and exit
$ python optparse_version.py --version
1.0</pre>
</div>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a class="reference external" href="http://docs.python.org/lib/module-optparse.html">optparse</a></dt>
<dd>Standard library documentation for this module.</dd>
<dt><a class="reference internal" href="../getopt/index.html#module-getopt" title="getopt: Command line option parsing"><tt class="xref py py-mod docutils literal"><span class="pre">getopt</span></tt></a></dt>
<dd>The getopt module, replaced by optparse.</dd>
<dt><a class="reference internal" href="../argparse/index.html#module-argparse" title="argparse: Command line option and argument parsing."><tt class="xref py py-mod docutils literal"><span class="pre">argparse</span></tt></a></dt>
<dd>Newer replacement for optparse.</dd>
</dl>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="../argparse/index.html" title="argparse – Command line option and argument parsing."
>next</a> |</li>
<li class="right" >
<a href="../getopt/index.html" title="getopt – Command line option parsing"
>previous</a> |</li>
<li><a href="../contents.html">PyMOTW</a> »</li>
<li><a href="../generic_os.html" >Generic Operating System Services</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright Doug Hellmann.
Last updated on Oct 24, 2010.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
<br/><a href="http://creativecommons.org/licenses/by-nc-sa/3.0/us/" rel="license"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by-nc-sa/3.0/us/88x31.png"/></a>
</div>
</body>
</html>