study/uTools-Manuals
1
0
Fork 0
mirror of https://github.com/fofolee/uTools-Manuals.git synced 2025-06-08 23:14:06 +08:00
Code Issues Packages Projects Releases Wiki Activity
uTools-Manuals/docs/python/optparse.html
fofolee 38dcd51d8a v0.0.2
2019-04-21 11:50:48 +08:00

365 lines
237 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<div class="body" role="main"><div class="section" id="module-optparse"><h1><span class="yiyi-st" id="yiyi-10">36.1. <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> — 命令行参数解析</span></h1><p><span class="yiyi-st" id="yiyi-11"><strong>源码:</strong> <a class="reference external" href="https://hg.python.org/cpython/file/3.5/Lib/optparse.py">Lib/optparse.py</a></span></p><div class="deprecated"><p><span class="yiyi-st" id="yiyi-12"><span class="versionmodified">3.2版本后开始弃用:</span><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> 模块已经弃用且无继续开发的计划; 新的开发将转向<a class="reference internal" href="argparse.html#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal"><span class="pre">argparse</span></code></a> 模块.</span></p></div><p><span class="yiyi-st" id="yiyi-13"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> is a more convenient, flexible, and powerful library for parsing command-line options than the old <a class="reference internal" href="getopt.html#module-getopt" title="getopt: Portable parser for command line options; support both short and long option names."><code class="xref py py-mod docutils literal"><span class="pre">getopt</span></code></a> module. </span><span class="yiyi-st" id="yiyi-14"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> uses a more declarative style of command-line parsing: you create an instance of <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal"><span class="pre">OptionParser</span></code></a>, populate it with options, and parse the command line. </span><span class="yiyi-st" id="yiyi-15"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> allows users to specify options in the conventional GNU/POSIX syntax, and additionally generates usage and help messages for you.</span></p><p><span class="yiyi-st" id="yiyi-16">Here’s an example of using <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> in a simple script:</span></p><pre><code class="language-python"><span></span><span class="kn">from</span> <span class="nn">optparse</span> <span class="k">import</span> <span class="n">OptionParser</span>
<span class="o">...</span>
<span class="n">parser</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="s2">"-f"</span><span class="p">,</span> <span class="s2">"--file"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"filename"</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s2">"write report to FILE"</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s2">"FILE"</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="s2">"-q"</span><span class="p">,</span> <span class="s2">"--quiet"</span><span class="p">,</span>
<span class="n">action</span><span class="o">=</span><span class="s2">"store_false"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s2">"don't print status messages to stdout"</span><span class="p">)</span>
<span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">)</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
</code></pre><p><span class="yiyi-st" id="yiyi-17">With these few lines of code, users of your script can now do the “usual thing” on the command-line, for example:</span></p><pre><code class="language-python"><span></span><span class="o">&lt;</span><span class="n">yourscript</span><span class="o">&gt;</span> <span class="o">--</span><span class="n">file</span><span class="o">=</span><span class="n">outfile</span> <span class="o">-</span><span class="n">q</span>
</code></pre><p><span class="yiyi-st" id="yiyi-18">As it parses the command line, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> sets attributes of the <code class="docutils literal"><span class="pre">options</span></code> object returned by <code class="xref py py-meth docutils literal"><span class="pre">parse_args()</span></code> based on user-supplied command-line values. </span><span class="yiyi-st" id="yiyi-19">When <code class="xref py py-meth docutils literal"><span class="pre">parse_args()</span></code> returns from parsing this command line, <code class="docutils literal"><span class="pre">options.filename</span></code> will be <code class="docutils literal"><span class="pre">"outfile"</span></code> and <code class="docutils literal"><span class="pre">options.verbose</span></code> will be <code class="docutils literal"><span class="pre">False</span></code>. </span><span class="yiyi-st" id="yiyi-20"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> 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. </span><span class="yiyi-st" id="yiyi-21">Thus, the following command lines are all equivalent to the above example:</span></p><pre><code class="language-python"><span></span><span class="o">&lt;</span><span class="n">yourscript</span><span class="o">&gt;</span> <span class="o">-</span><span class="n">f</span> <span class="n">outfile</span> <span class="o">--</span><span class="n">quiet</span>
<span class="o">&lt;</span><span class="n">yourscript</span><span class="o">&gt;</span> <span class="o">--</span><span class="n">quiet</span> <span class="o">--</span><span class="n">file</span> <span class="n">outfile</span>
<span class="o">&lt;</span><span class="n">yourscript</span><span class="o">&gt;</span> <span class="o">-</span><span class="n">q</span> <span class="o">-</span><span class="n">foutfile</span>
<span class="o">&lt;</span><span class="n">yourscript</span><span class="o">&gt;</span> <span class="o">-</span><span class="n">qfoutfile</span>
</code></pre><p><span class="yiyi-st" id="yiyi-22">Additionally, users can run one of</span></p><pre><code class="language-python"><span></span><span class="o">&lt;</span><span class="n">yourscript</span><span class="o">&gt;</span> <span class="o">-</span><span class="n">h</span>
<span class="o">&lt;</span><span class="n">yourscript</span><span class="o">&gt;</span> <span class="o">--</span><span class="n">help</span>
</code></pre><p><span class="yiyi-st" id="yiyi-23">and <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> will print out a brief summary of your script’s options:</span></p><div class="highlight-text"><div class="highlight"><pre><span></span>Usage: &lt;yourscript&gt; [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
</pre></div></div><p><span class="yiyi-st" id="yiyi-24">where the value of <em>yourscript</em> is determined at runtime (normally from <code class="docutils literal"><span class="pre">sys.argv[0]</span></code>).</span></p><div class="section" id="background"><h2><span class="yiyi-st" id="yiyi-25">36.1.1. </span><span class="yiyi-st" id="yiyi-26">Background</span></h2><p><span class="yiyi-st" id="yiyi-27"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> was explicitly designed to encourage the creation of programs with straightforward, conventional command-line interfaces. </span><span class="yiyi-st" id="yiyi-28">To that end, it supports only the most common command-line syntax and semantics conventionally used under Unix. </span><span class="yiyi-st" id="yiyi-29">If you are unfamiliar with these conventions, read this section to acquaint yourself with them.</span></p><div class="section" id="terminology"><h3><span class="yiyi-st" id="yiyi-30">36.1.1.1. </span><span class="yiyi-st" id="yiyi-31">Terminology</span></h3><dl class="docutils"><dt><span class="yiyi-st" id="yiyi-32">argument</span></dt><dd><p class="first"><span class="yiyi-st" id="yiyi-33">a string entered on the command-line, and passed by the shell to <code class="docutils literal"><span class="pre">execl()</span></code> or <code class="docutils literal"><span class="pre">execv()</span></code>. </span><span class="yiyi-st" id="yiyi-34">In Python, arguments are elements of <code class="docutils literal"><span class="pre">sys.argv[1:]</span></code> (<code class="docutils literal"><span class="pre">sys.argv[0]</span></code> is the name of the program being executed). </span><span class="yiyi-st" id="yiyi-35">Unix shells also use the term “word”.</span></p><p class="last"><span class="yiyi-st" id="yiyi-36">It is occasionally desirable to substitute an argument list other than <code class="docutils literal"><span class="pre">sys.argv[1:]</span></code>, so you should read “argument” as “an element of <code class="docutils literal"><span class="pre">sys.argv[1:]</span></code>, or of some other list provided as a substitute for <code class="docutils literal"><span class="pre">sys.argv[1:]</span></code>”.</span></p></dd><dt><span class="yiyi-st" id="yiyi-37">option</span></dt><dd><p class="first"><span class="yiyi-st" id="yiyi-38">an argument used to supply extra information to guide or customize the execution of a program. </span><span class="yiyi-st" id="yiyi-39">There are many different syntaxes for options; the traditional Unix syntax is a hyphen (“-”) followed by a single letter, e.g. </span><span class="yiyi-st" id="yiyi-40"><code class="docutils literal"><span class="pre">-x</span></code> or <code class="docutils literal"><span class="pre">-F</span></code>. Also, traditional Unix syntax allows multiple options to be merged into a single argument, e.g. </span><span class="yiyi-st" id="yiyi-41"><code class="docutils literal"><span class="pre">-x</span> <span class="pre">-F</span></code> is equivalent to <code class="docutils literal"><span class="pre">-xF</span></code>. </span><span class="yiyi-st" id="yiyi-42">The GNU project introduced <code class="docutils literal"><span class="pre">--</span></code> followed by a series of hyphen-separated words, e.g. </span><span class="yiyi-st" id="yiyi-43"><code class="docutils literal"><span class="pre">--file</span></code> or <code class="docutils literal"><span class="pre">--dry-run</span></code>. </span><span class="yiyi-st" id="yiyi-44">These are the only two option syntaxes provided by <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a>.</span></p><p><span class="yiyi-st" id="yiyi-45">Some other option syntaxes that the world has seen include:</span></p><ul class="simple"><li><span class="yiyi-st" id="yiyi-46">a hyphen followed by a few letters, e.g. </span><span class="yiyi-st" id="yiyi-47"><code class="docutils literal"><span class="pre">-pf</span></code> (this is <em>not</em> the same as multiple options merged into a single argument)</span></li><li><span class="yiyi-st" id="yiyi-48">a hyphen followed by a whole word, e.g. </span><span class="yiyi-st" id="yiyi-49"><code class="docutils literal"><span class="pre">-file</span></code> (this is technically equivalent to the previous syntax, but they aren’t usually seen in the same program)</span></li><li><span class="yiyi-st" id="yiyi-50">a plus sign followed by a single letter, or a few letters, or a word, e.g. </span><span class="yiyi-st" id="yiyi-51"><code class="docutils literal"><span class="pre">+f</span></code>, <code class="docutils literal"><span class="pre">+rgb</span></code></span></li><li><span class="yiyi-st" id="yiyi-52">a slash followed by a letter, or a few letters, or a word, e.g. </span><span class="yiyi-st" id="yiyi-53"><code class="docutils literal"><span class="pre">/f</span></code>, <code class="docutils literal"><span class="pre">/file</span></code></span></li></ul><p class="last"><span class="yiyi-st" id="yiyi-54">These option syntaxes are not supported by <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a>, and they never will be. </span><span class="yiyi-st" id="yiyi-55">This is deliberate: the first three are non-standard on any environment, and the last only makes sense if you’re exclusively targeting VMS, MS-DOS, and/or Windows.</span></p></dd><dt><span class="yiyi-st" id="yiyi-56">option argument</span></dt><dd><p class="first"><span class="yiyi-st" id="yiyi-57">an argument that follows an option, is closely associated with that option, and is consumed from the argument list when that option is. </span><span class="yiyi-st" id="yiyi-58">With <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a>, option arguments may either be in a separate argument from their option:</span></p><div class="highlight-text"><div class="highlight"><pre><span></span>-f foo
--file foo
</pre></div></div><p><span class="yiyi-st" id="yiyi-59">or included in the same argument:</span></p><div class="highlight-text"><div class="highlight"><pre><span></span>-ffoo
--file=foo
</pre></div></div><p class="last"><span class="yiyi-st" id="yiyi-60">Typically, a given option either takes an argument or it doesn’t. </span><span class="yiyi-st" id="yiyi-61">Lots of people want an “optional option arguments” feature, meaning that some options will take an argument if they see it, and won’t if they don’t. </span><span class="yiyi-st" id="yiyi-62">This is somewhat controversial, because it makes parsing ambiguous: if <code class="docutils literal"><span class="pre">-a</span></code> takes an optional argument and <code class="docutils literal"><span class="pre">-b</span></code> is another option entirely, how do we interpret <code class="docutils literal"><span class="pre">-ab</span></code>? </span><span class="yiyi-st" id="yiyi-63">Because of this ambiguity, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> does not support this feature.</span></p></dd><dt><span class="yiyi-st" id="yiyi-64">positional argument</span></dt><dd><span class="yiyi-st" id="yiyi-65">something leftover in the argument list after options have been parsed, i.e. </span><span class="yiyi-st" id="yiyi-66">after options and their arguments have been parsed and removed from the argument list.</span></dd><dt><span class="yiyi-st" id="yiyi-67">required option</span></dt><dd><span class="yiyi-st" id="yiyi-68">an option that must be supplied on the command-line; note that the phrase “required option” is self-contradictory in English. </span><span class="yiyi-st" id="yiyi-69"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> doesn’t prevent you from implementing required options, but doesn’t give you much help at it either.</span></dd></dl><p><span class="yiyi-st" id="yiyi-70">For example, consider this hypothetical command-line:</span></p><pre><code class="language-python"><span></span><span class="n">prog</span> <span class="o">-</span><span class="n">v</span> <span class="o">--</span><span class="n">report</span> <span class="n">report</span><span class="o">.</span><span class="n">txt</span> <span class="n">foo</span> <span class="n">bar</span>
</code></pre><p><span class="yiyi-st" id="yiyi-71"><code class="docutils literal"><span class="pre">-v</span></code> and <code class="docutils literal"><span class="pre">--report</span></code> are both options. </span><span class="yiyi-st" id="yiyi-72">Assuming that <code class="docutils literal"><span class="pre">--report</span></code> takes one argument, <code class="docutils literal"><span class="pre">report.txt</span></code> is an option argument. </span><span class="yiyi-st" id="yiyi-73"><code class="docutils literal"><span class="pre">foo</span></code> and <code class="docutils literal"><span class="pre">bar</span></code> are positional arguments.</span></p></div><div class="section" id="what-are-options-for"><h3><span class="yiyi-st" id="yiyi-74">36.1.1.2. </span><span class="yiyi-st" id="yiyi-75">What are options for?</span></h3><p><span class="yiyi-st" id="yiyi-76">Options are used to provide extra information to tune or customize the execution of a program. </span><span class="yiyi-st" id="yiyi-77">In case it wasn’t clear, options are usually <em>optional</em>. </span><span class="yiyi-st" id="yiyi-78">A program should be able to run just fine with no options whatsoever. </span><span class="yiyi-st" id="yiyi-79">(Pick a random program from the Unix or GNU toolsets. </span><span class="yiyi-st" id="yiyi-80">Can it run without any options at all and still make sense? </span><span class="yiyi-st" id="yiyi-81">The main exceptions are <code class="docutils literal"><span class="pre">find</span></code>, <code class="docutils literal"><span class="pre">tar</span></code>, and <code class="docutils literal"><span class="pre">dd</span></code>—all of which are mutant oddballs that have been rightly criticized for their non-standard syntax and confusing interfaces.)</span></p><p><span class="yiyi-st" id="yiyi-82">Lots of people want their programs to have “required options”. </span><span class="yiyi-st" id="yiyi-83">Think about it. </span><span class="yiyi-st" id="yiyi-84">If it’s required, then it’s <em>not optional</em>! </span><span class="yiyi-st" id="yiyi-85">If there is a piece of information that your program absolutely requires in order to run successfully, that’s what positional arguments are for.</span></p><p><span class="yiyi-st" id="yiyi-86">As an example of good command-line interface design, consider the humble <code class="docutils literal"><span class="pre">cp</span></code> utility, for copying files. </span><span class="yiyi-st" id="yiyi-87">It doesn’t make much sense to try to copy files without supplying a destination and at least one source. </span><span class="yiyi-st" id="yiyi-88">Hence, <code class="docutils literal"><span class="pre">cp</span></code> fails if you run it with no arguments. </span><span class="yiyi-st" id="yiyi-89">However, it has a flexible, useful syntax that does not require any options at all:</span></p><pre><code class="language-python"><span></span><span class="n">cp</span> <span class="n">SOURCE</span> <span class="n">DEST</span>
<span class="n">cp</span> <span class="n">SOURCE</span> <span class="o">...</span> <span class="n">DEST</span><span class="o">-</span><span class="n">DIR</span>
</code></pre><p><span class="yiyi-st" id="yiyi-90">You can get pretty far with just that. </span><span class="yiyi-st" id="yiyi-91">Most <code class="docutils literal"><span class="pre">cp</span></code> implementations provide a bunch of options to tweak exactly how the files are copied: you can preserve mode and modification time, avoid following symlinks, ask before clobbering existing files, etc. </span><span class="yiyi-st" id="yiyi-92">But none of this distracts from the core mission of <code class="docutils literal"><span class="pre">cp</span></code>, which is to copy either one file to another, or several files to another directory.</span></p></div><div class="section" id="what-are-positional-arguments-for"><h3><span class="yiyi-st" id="yiyi-93">36.1.1.3. </span><span class="yiyi-st" id="yiyi-94">What are positional arguments for?</span></h3><p><span class="yiyi-st" id="yiyi-95">Positional arguments are for those pieces of information that your program absolutely, positively requires to run.</span></p><p><span class="yiyi-st" id="yiyi-96">A good user interface should have as few absolute requirements as possible. </span><span class="yiyi-st" id="yiyi-97">If your program requires 17 distinct pieces of information in order to run successfully, it doesn’t much matter <em>how</em> you get that information from the user—most people will give up and walk away before they successfully run the program. </span><span class="yiyi-st" id="yiyi-98">This applies whether the user interface is a command-line, a configuration file, or a GUI: if you make that many demands on your users, most of them will simply give up.</span></p><p><span class="yiyi-st" id="yiyi-99">In short, try to minimize the amount of information that users are absolutely required to supply—use sensible defaults whenever possible. </span><span class="yiyi-st" id="yiyi-100">Of course, you also want to make your programs reasonably flexible. </span><span class="yiyi-st" id="yiyi-101">That’s what options are for. </span><span class="yiyi-st" id="yiyi-102">Again, it doesn’t matter if they are entries in a config file, widgets in the “Preferences” dialog of a GUI, or command-line options—the more options you implement, the more flexible your program is, and the more complicated its implementation becomes. </span><span class="yiyi-st" id="yiyi-103">Too much flexibility has drawbacks as well, of course; too many options can overwhelm users and make your code much harder to maintain.</span></p></div></div><div class="section" id="tutorial"><h2><span class="yiyi-st" id="yiyi-104">36.1.2. </span><span class="yiyi-st" id="yiyi-105">Tutorial</span></h2><p><span class="yiyi-st" id="yiyi-106">While <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> is quite flexible and powerful, it’s also straightforward to use in most cases. </span><span class="yiyi-st" id="yiyi-107">This section covers the code patterns that are common to any <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a>-based program.</span></p><p><span class="yiyi-st" id="yiyi-108">First, you need to import the OptionParser class; then, early in the main program, create an OptionParser instance:</span></p><pre><code class="language-python"><span></span><span class="kn">from</span> <span class="nn">optparse</span> <span class="k">import</span> <span class="n">OptionParser</span>
<span class="o">...</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">()</span>
</code></pre><p><span class="yiyi-st" id="yiyi-109">Then you can start defining options. </span><span class="yiyi-st" id="yiyi-110">The basic syntax is:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="n">opt_str</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span>
<span class="n">attr</span><span class="o">=</span><span class="n">value</span><span class="p">,</span> <span class="o">...</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-111">Each option has one or more option strings, such as <code class="docutils literal"><span class="pre">-f</span></code> or <code class="docutils literal"><span class="pre">--file</span></code>, and several option attributes that tell <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> what to expect and what to do when it encounters that option on the command line.</span></p><p><span class="yiyi-st" id="yiyi-112">Typically, each option will have one short option string and one long option string, e.g. </span><span class="yiyi-st" id="yiyi-113">:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-f"</span><span class="p">,</span> <span class="s2">"--file"</span><span class="p">,</span> <span class="o">...</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-114">You’re free to define as many short option strings and as many long option strings as you like (including zero), as long as there is at least one option string overall.</span></p><p><span class="yiyi-st" id="yiyi-115">The option strings passed to <a class="reference internal" href="#optparse.OptionParser.add_option" title="optparse.OptionParser.add_option"><code class="xref py py-meth docutils literal"><span class="pre">OptionParser.add_option()</span></code></a> are effectively labels for the option defined by that call. </span><span class="yiyi-st" id="yiyi-116">For brevity, we will frequently refer to <em>encountering an option</em> on the command line; in reality, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> encounters <em>option strings</em> and looks up options from them.</span></p><p><span class="yiyi-st" id="yiyi-117">Once all of your options are defined, instruct <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> to parse your program’s command line:</span></p><pre><code class="language-python"><span></span><span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">)</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
</code></pre><p><span class="yiyi-st" id="yiyi-118">(If you like, you can pass a custom argument list to <code class="xref py py-meth docutils literal"><span class="pre">parse_args()</span></code>, but that’s rarely necessary: by default it uses <code class="docutils literal"><span class="pre">sys.argv[1:]</span></code>.)</span></p><p><span class="yiyi-st" id="yiyi-119"><code class="xref py py-meth docutils literal"><span class="pre">parse_args()</span></code> returns two values:</span></p><ul class="simple"><li><span class="yiyi-st" id="yiyi-120"><code class="docutils literal"><span class="pre">options</span></code>, an object containing values for all of your options—e.g. </span><span class="yiyi-st" id="yiyi-121">if <code class="docutils literal"><span class="pre">--file</span></code> takes a single string argument, then <code class="docutils literal"><span class="pre">options.file</span></code> will be the filename supplied by the user, or <code class="docutils literal"><span class="pre">None</span></code> if the user did not supply that option</span></li><li><span class="yiyi-st" id="yiyi-122"><code class="docutils literal"><span class="pre">args</span></code>, the list of positional arguments leftover after parsing options</span></li></ul><p><span class="yiyi-st" id="yiyi-123">This tutorial section only covers the four most important option attributes: <a class="reference internal" href="#optparse.Option.action" title="optparse.Option.action"><code class="xref py py-attr docutils literal"><span class="pre">action</span></code></a>, <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal"><span class="pre">type</span></code></a>, <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a> (destination), and <a class="reference internal" href="#optparse.Option.help" title="optparse.Option.help"><code class="xref py py-attr docutils literal"><span class="pre">help</span></code></a>. </span><span class="yiyi-st" id="yiyi-124">Of these, <a class="reference internal" href="#optparse.Option.action" title="optparse.Option.action"><code class="xref py py-attr docutils literal"><span class="pre">action</span></code></a> is the most fundamental.</span></p><div class="section" id="understanding-option-actions"><h3><span class="yiyi-st" id="yiyi-125">36.1.2.1. </span><span class="yiyi-st" id="yiyi-126">Understanding option actions</span></h3><p><span class="yiyi-st" id="yiyi-127">Actions tell <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> what to do when it encounters an option on the command line. </span><span class="yiyi-st" id="yiyi-128">There is a fixed set of actions hard-coded into <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a>; adding new actions is an advanced topic covered in section <a class="reference internal" href="#optparse-extending-optparse"><span>Extending optparse</span></a>. </span><span class="yiyi-st" id="yiyi-129">Most actions tell <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> to store a value in some variable—for example, take a string from the command line and store it in an attribute of <code class="docutils literal"><span class="pre">options</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-130">If you don’t specify an option action, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> defaults to <code class="docutils literal"><span class="pre">store</span></code>.</span></p></div><div class="section" id="the-store-action"><h3><span class="yiyi-st" id="yiyi-131">36.1.2.2. </span><span class="yiyi-st" id="yiyi-132">The store action</span></h3><p><span class="yiyi-st" id="yiyi-133">The most common option action is <code class="docutils literal"><span class="pre">store</span></code>, which tells <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> to take the next argument (or the remainder of the current argument), ensure that it is of the correct type, and store it to your chosen destination.</span></p><p><span class="yiyi-st" id="yiyi-134">For example:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-f"</span><span class="p">,</span> <span class="s2">"--file"</span><span class="p">,</span>
<span class="n">action</span><span class="o">=</span><span class="s2">"store"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s2">"string"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"filename"</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-135">Now let’s make up a fake command line and ask <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> to parse it:</span></p><pre><code class="language-python"><span></span><span class="n">args</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"-f"</span><span class="p">,</span> <span class="s2">"foo.txt"</span><span class="p">]</span>
<span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">)</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="n">args</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-136">When <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> sees the option string <code class="docutils literal"><span class="pre">-f</span></code>, it consumes the next argument, <code class="docutils literal"><span class="pre">foo.txt</span></code>, and stores it in <code class="docutils literal"><span class="pre">options.filename</span></code>. </span><span class="yiyi-st" id="yiyi-137">So, after this call to <code class="xref py py-meth docutils literal"><span class="pre">parse_args()</span></code>, <code class="docutils literal"><span class="pre">options.filename</span></code> is <code class="docutils literal"><span class="pre">"foo.txt"</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-138">Some other option types supported by <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> are <code class="docutils literal"><span class="pre">int</span></code> and <code class="docutils literal"><span class="pre">float</span></code>. </span><span class="yiyi-st" id="yiyi-139">Here’s an option that expects an integer argument:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-n"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s2">"int"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"num"</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-140">Note that this option has no long option string, which is perfectly acceptable. </span><span class="yiyi-st" id="yiyi-141">Also, there’s no explicit action, since the default is <code class="docutils literal"><span class="pre">store</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-142">Let’s parse another fake command-line. </span><span class="yiyi-st" id="yiyi-143">This time, we’ll jam the option argument right up against the option: since <code class="docutils literal"><span class="pre">-n42</span></code> (one argument) is equivalent to <code class="docutils literal"><span class="pre">-n</span> <span class="pre">42</span></code> (two arguments), the code</span></p><pre><code class="language-python"><span></span><span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">)</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="s2">"-n42"</span><span class="p">])</span>
<span class="nb">print</span><span class="p">(</span><span class="n">options</span><span class="o">.</span><span class="n">num</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-144">will print <code class="docutils literal"><span class="pre">42</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-145">If you don’t specify a type, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> assumes <code class="docutils literal"><span class="pre">string</span></code>. </span><span class="yiyi-st" id="yiyi-146">Combined with the fact that the default action is <code class="docutils literal"><span class="pre">store</span></code>, that means our first example can be a lot shorter:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-f"</span><span class="p">,</span> <span class="s2">"--file"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"filename"</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-147">If you don’t supply a destination, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> figures out a sensible default from the option strings: if the first long option string is <code class="docutils literal"><span class="pre">--foo-bar</span></code>, then the default destination is <code class="docutils literal"><span class="pre">foo_bar</span></code>. </span><span class="yiyi-st" id="yiyi-148">If there are no long option strings, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> looks at the first short option string: the default destination for <code class="docutils literal"><span class="pre">-f</span></code> is <code class="docutils literal"><span class="pre">f</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-149"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> also includes the built-in <code class="docutils literal"><span class="pre">complex</span></code> type. </span><span class="yiyi-st" id="yiyi-150">Adding types is covered in section <a class="reference internal" href="#optparse-extending-optparse"><span>Extending optparse</span></a>.</span></p></div><div class="section" id="handling-boolean-flag-options"><h3><span class="yiyi-st" id="yiyi-151">36.1.2.3. </span><span class="yiyi-st" id="yiyi-152">Handling boolean (flag) options</span></h3><p><span class="yiyi-st" id="yiyi-153">Flag options—set a variable to true or false when a particular option is seen —are quite common. </span><span class="yiyi-st" id="yiyi-154"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> supports them with two separate actions, <code class="docutils literal"><span class="pre">store_true</span></code> and <code class="docutils literal"><span class="pre">store_false</span></code>. </span><span class="yiyi-st" id="yiyi-155">For example, you might have a <code class="docutils literal"><span class="pre">verbose</span></code> flag that is turned on with <code class="docutils literal"><span class="pre">-v</span></code> and off with <code class="docutils literal"><span class="pre">-q</span></code>:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-v"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</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="s2">"-q"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_false"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-156">Here we have two different options with the same destination, which is perfectly OK. (It just means you have to be a bit careful when setting default values— see below.)</span></p><p><span class="yiyi-st" id="yiyi-157">When <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> encounters <code class="docutils literal"><span class="pre">-v</span></code> on the command line, it sets <code class="docutils literal"><span class="pre">options.verbose</span></code> to <code class="docutils literal"><span class="pre">True</span></code>; when it encounters <code class="docutils literal"><span class="pre">-q</span></code>, <code class="docutils literal"><span class="pre">options.verbose</span></code> is set to <code class="docutils literal"><span class="pre">False</span></code>.</span></p></div><div class="section" id="other-actions"><h3><span class="yiyi-st" id="yiyi-158">36.1.2.4. </span><span class="yiyi-st" id="yiyi-159">Other actions</span></h3><p><span class="yiyi-st" id="yiyi-160">Some other actions supported by <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> are:</span></p><dl class="docutils"><dt><span class="yiyi-st" id="yiyi-161"><code class="docutils literal"><span class="pre">"store_const"</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-162">store a constant value</span></dd><dt><span class="yiyi-st" id="yiyi-163"><code class="docutils literal"><span class="pre">"append"</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-164">append this option’s argument to a list</span></dd><dt><span class="yiyi-st" id="yiyi-165"><code class="docutils literal"><span class="pre">"count"</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-166">increment a counter by one</span></dd><dt><span class="yiyi-st" id="yiyi-167"><code class="docutils literal"><span class="pre">"callback"</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-168">call a specified function</span></dd></dl><p><span class="yiyi-st" id="yiyi-169">These are covered in section <a class="reference internal" href="#optparse-reference-guide"><span>Reference Guide</span></a>, Reference Guide and section <a class="reference internal" href="#optparse-option-callbacks"><span>Option Callbacks</span></a>.</span></p></div><div class="section" id="default-values"><h3><span class="yiyi-st" id="yiyi-170">36.1.2.5. </span><span class="yiyi-st" id="yiyi-171">Default values</span></h3><p><span class="yiyi-st" id="yiyi-172">All of the above examples involve setting some variable (the “destination”) when certain command-line options are seen. </span><span class="yiyi-st" id="yiyi-173">What happens if those options are never seen? </span><span class="yiyi-st" id="yiyi-174">Since we didn’t supply any defaults, they are all set to <code class="docutils literal"><span class="pre">None</span></code>. </span><span class="yiyi-st" id="yiyi-175">This is usually fine, but sometimes you want more control. </span><span class="yiyi-st" id="yiyi-176"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> lets you supply a default value for each destination, which is assigned before the command line is parsed.</span></p><p><span class="yiyi-st" id="yiyi-177">First, consider the verbose/quiet example. </span><span class="yiyi-st" id="yiyi-178">If we want <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> to set <code class="docutils literal"><span class="pre">verbose</span></code> to <code class="docutils literal"><span class="pre">True</span></code> unless <code class="docutils literal"><span class="pre">-q</span></code> is seen, then we can do this:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-v"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">True</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="s2">"-q"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_false"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-179">Since default values apply to the <em>destination</em> rather than to any particular option, and these two options happen to have the same destination, this is exactly equivalent:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-v"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</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="s2">"-q"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_false"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-180">Consider this:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-v"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">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="s2">"-q"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_false"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-181">Again, the default value for <code class="docutils literal"><span class="pre">verbose</span></code> will be <code class="docutils literal"><span class="pre">True</span></code>: the last default value supplied for any particular destination is the one that counts.</span></p><p><span class="yiyi-st" id="yiyi-182">A clearer way to specify default values is the <code class="xref py py-meth docutils literal"><span class="pre">set_defaults()</span></code> method of OptionParser, which you can call at any time before calling <code class="xref py py-meth docutils literal"><span class="pre">parse_args()</span></code>:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">set_defaults</span><span class="p">(</span><span class="n">verbose</span><span class="o">=</span><span class="kc">True</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="o">...</span><span class="p">)</span>
<span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">)</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
</code></pre><p><span class="yiyi-st" id="yiyi-183">As before, the last value specified for a given option destination is the one that counts. </span><span class="yiyi-st" id="yiyi-184">For clarity, try to use one method or the other of setting default values, not both.</span></p></div><div class="section" id="generating-help"><h3><span class="yiyi-st" id="yiyi-185">36.1.2.6. </span><span class="yiyi-st" id="yiyi-186">Generating help</span></h3><p><span class="yiyi-st" id="yiyi-187"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a>‘s ability to generate help and usage text automatically is useful for creating user-friendly command-line interfaces. </span><span class="yiyi-st" id="yiyi-188">All you have to do is supply a <a class="reference internal" href="#optparse.Option.help" title="optparse.Option.help"><code class="xref py py-attr docutils literal"><span class="pre">help</span></code></a> value for each option, and optionally a short usage message for your whole program. </span><span class="yiyi-st" id="yiyi-189">Here’s an OptionParser populated with user-friendly (documented) options:</span></p><pre><code class="language-python"><span></span><span class="n">usage</span> <span class="o">=</span> <span class="s2">"usage: %prog [options] arg1 arg2"</span>
<span class="n">parser</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="n">usage</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="s2">"-v"</span><span class="p">,</span> <span class="s2">"--verbose"</span><span class="p">,</span>
<span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s2">"make lots of noise [default]"</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="s2">"-q"</span><span class="p">,</span> <span class="s2">"--quiet"</span><span class="p">,</span>
<span class="n">action</span><span class="o">=</span><span class="s2">"store_false"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s2">"be vewwy quiet (I'm hunting wabbits)"</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="s2">"-f"</span><span class="p">,</span> <span class="s2">"--filename"</span><span class="p">,</span>
<span class="n">metavar</span><span class="o">=</span><span class="s2">"FILE"</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s2">"write output to FILE"</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="s2">"-m"</span><span class="p">,</span> <span class="s2">"--mode"</span><span class="p">,</span>
<span class="n">default</span><span class="o">=</span><span class="s2">"intermediate"</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s2">"interaction mode: novice, intermediate, "</span>
<span class="s2">"or expert [default: </span><span class="si">%d</span><span class="s2">efault]"</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-190">If <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> encounters either <code class="docutils literal"><span class="pre">-h</span></code> or <code class="docutils literal"><span class="pre">--help</span></code> on the command-line, or if you just call <code class="xref py py-meth docutils literal"><span class="pre">parser.print_help()</span></code>, it prints the following to standard output:</span></p><div class="highlight-text"><div class="highlight"><pre><span></span>Usage: &lt;yourscript&gt; [options] arg1 arg2
Options:
-h, --help show this help message and exit
-v, --verbose make lots of noise [default]
-q, --quiet be vewwy quiet (I'm hunting wabbits)
-f FILE, --filename=FILE
write output to FILE
-m MODE, --mode=MODE interaction mode: novice, intermediate, or
expert [default: intermediate]
</pre></div></div><p><span class="yiyi-st" id="yiyi-191">(If the help output is triggered by a help option, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> exits after printing the help text.)</span></p><p><span class="yiyi-st" id="yiyi-192">There’s a lot going on here to help <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> generate the best possible help message:</span></p><ul><li><p class="first"><span class="yiyi-st" id="yiyi-193">the script defines its own usage message:</span></p><pre><code class="language-python"><span></span><span class="n">usage</span> <span class="o">=</span> <span class="s2">"usage: %prog [options] arg1 arg2"</span>
</code></pre><p><span class="yiyi-st" id="yiyi-194"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> expands <code class="docutils literal"><span class="pre">%prog</span></code> in the usage string to the name of the current program, i.e. </span><span class="yiyi-st" id="yiyi-195"><code class="docutils literal"><span class="pre">os.path.basename(sys.argv[0])</span></code>. </span><span class="yiyi-st" id="yiyi-196">The expanded string is then printed before the detailed option help.</span></p><p><span class="yiyi-st" id="yiyi-197">If you don’t supply a usage string, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> uses a bland but sensible default: <code class="docutils literal"><span class="pre">"Usage:</span> <span class="pre">%prog</span> <span class="pre">[options]"</span></code>, which is fine if your script doesn’t take any positional arguments.</span></p></li><li><p class="first"><span class="yiyi-st" id="yiyi-198">every option defines a help string, and doesn’t worry about line-wrapping— <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> takes care of wrapping lines and making the help output look good.</span></p></li><li><p class="first"><span class="yiyi-st" id="yiyi-199">options that take a value indicate this fact in their automatically-generated help message, e.g. </span><span class="yiyi-st" id="yiyi-200">for the “mode” option:</span></p><pre><code class="language-python"><span></span><span class="o">-</span><span class="n">m</span> <span class="n">MODE</span><span class="p">,</span> <span class="o">--</span><span class="n">mode</span><span class="o">=</span><span class="n">MODE</span>
</code></pre><p><span class="yiyi-st" id="yiyi-201">Here, “MODE” is called the meta-variable: it stands for the argument that the user is expected to supply to <code class="docutils literal"><span class="pre">-m</span></code>/<code class="docutils literal"><span class="pre">--mode</span></code>. </span><span class="yiyi-st" id="yiyi-202">By default, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> converts the destination variable name to uppercase and uses that for the meta-variable. </span><span class="yiyi-st" id="yiyi-203">Sometimes, that’s not what you want—for example, the <code class="docutils literal"><span class="pre">--filename</span></code> option explicitly sets <code class="docutils literal"><span class="pre">metavar="FILE"</span></code>, resulting in this automatically-generated option description:</span></p><pre><code class="language-python"><span></span><span class="o">-</span><span class="n">f</span> <span class="n">FILE</span><span class="p">,</span> <span class="o">--</span><span class="n">filename</span><span class="o">=</span><span class="n">FILE</span>
</code></pre><p><span class="yiyi-st" id="yiyi-204">This is important for more than just saving space, though: the manually written help text uses the meta-variable <code class="docutils literal"><span class="pre">FILE</span></code> to clue the user in that there’s a connection between the semi-formal syntax <code class="docutils literal"><span class="pre">-f</span> <span class="pre">FILE</span></code> and the informal semantic description “write output to FILE”. </span><span class="yiyi-st" id="yiyi-205">This is a simple but effective way to make your help text a lot clearer and more useful for end users.</span></p></li><li><p class="first"><span class="yiyi-st" id="yiyi-206">options that have a default value can include <code class="docutils literal"><span class="pre">%default</span></code> in the help string—<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> will replace it with <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-func docutils literal"><span class="pre">str()</span></code></a> of the option’s default value. </span><span class="yiyi-st" id="yiyi-207">If an option has no default value (or the default value is <code class="docutils literal"><span class="pre">None</span></code>), <code class="docutils literal"><span class="pre">%default</span></code> expands to <code class="docutils literal"><span class="pre">none</span></code>.</span></p></li></ul><div class="section" id="grouping-options"><h4><span class="yiyi-st" id="yiyi-208">36.1.2.6.1. </span><span class="yiyi-st" id="yiyi-209">Grouping Options</span></h4><p><span class="yiyi-st" id="yiyi-210">When dealing with many options, it is convenient to group these options for better help output. </span><span class="yiyi-st" id="yiyi-211">An <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal"><span class="pre">OptionParser</span></code></a> can contain several option groups, each of which can contain several options.</span></p><p><span class="yiyi-st" id="yiyi-212">An option group is obtained using the class <a class="reference internal" href="#optparse.OptionGroup" title="optparse.OptionGroup"><code class="xref py py-class docutils literal"><span class="pre">OptionGroup</span></code></a>:</span></p><dl class="class"><dt id="optparse.OptionGroup"><span class="yiyi-st" id="yiyi-213"> <em class="property">class </em><code class="descclassname">optparse.</code><code class="descname">OptionGroup</code><span class="sig-paren">(</span><em>parser</em>, <em>title</em>, <em>description=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-214">where</span></p><ul class="simple"><li><span class="yiyi-st" id="yiyi-215">parser is the <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal"><span class="pre">OptionParser</span></code></a> instance the group will be insterted in to</span></li><li><span class="yiyi-st" id="yiyi-216">title is the group title</span></li><li><span class="yiyi-st" id="yiyi-217">description, optional, is a long description of the group</span></li></ul></dd></dl><p><span class="yiyi-st" id="yiyi-218"><a class="reference internal" href="#optparse.OptionGroup" title="optparse.OptionGroup"><code class="xref py py-class docutils literal"><span class="pre">OptionGroup</span></code></a> inherits from <code class="xref py py-class docutils literal"><span class="pre">OptionContainer</span></code> (like <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal"><span class="pre">OptionParser</span></code></a>) and so the <code class="xref py py-meth docutils literal"><span class="pre">add_option()</span></code> method can be used to add an option to the group.</span></p><p><span class="yiyi-st" id="yiyi-219">Once all the options are declared, using the <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal"><span class="pre">OptionParser</span></code></a> method <code class="xref py py-meth docutils literal"><span class="pre">add_option_group()</span></code> the group is added to the previously defined parser.</span></p><p><span class="yiyi-st" id="yiyi-220">Continuing with the parser defined in the previous section, adding an <a class="reference internal" href="#optparse.OptionGroup" title="optparse.OptionGroup"><code class="xref py py-class docutils literal"><span class="pre">OptionGroup</span></code></a> to a parser is easy:</span></p><pre><code class="language-python"><span></span><span class="n">group</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="s2">"Dangerous Options"</span><span class="p">,</span>
<span class="s2">"Caution: use these options at your own risk. "</span>
<span class="s2">"It is believed that some of them bite."</span><span class="p">)</span>
<span class="n">group</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-g"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s2">"Group option."</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">group</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-221">This would result in the following help output:</span></p><div class="highlight-text"><div class="highlight"><pre><span></span>Usage: &lt;yourscript&gt; [options] arg1 arg2
Options:
-h, --help show this help message and exit
-v, --verbose make lots of noise [default]
-q, --quiet be vewwy quiet (I'm hunting wabbits)
-f FILE, --filename=FILE
write output to FILE
-m MODE, --mode=MODE interaction mode: novice, intermediate, or
expert [default: intermediate]
Dangerous Options:
Caution: use these options at your own risk. It is believed that some
of them bite.
-g Group option.
</pre></div></div><p><span class="yiyi-st" id="yiyi-222">A bit more complete example might involve using more than one group: still extending the previous example:</span></p><pre><code class="language-python"><span></span><span class="n">group</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="s2">"Dangerous Options"</span><span class="p">,</span>
<span class="s2">"Caution: use these options at your own risk. "</span>
<span class="s2">"It is believed that some of them bite."</span><span class="p">)</span>
<span class="n">group</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-g"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s2">"Group option."</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">group</span><span class="p">)</span>
<span class="n">group</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="s2">"Debug Options"</span><span class="p">)</span>
<span class="n">group</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-d"</span><span class="p">,</span> <span class="s2">"--debug"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s2">"Print debug information"</span><span class="p">)</span>
<span class="n">group</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-s"</span><span class="p">,</span> <span class="s2">"--sql"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s2">"Print all SQL statements executed"</span><span class="p">)</span>
<span class="n">group</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-e"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s2">"Print every action done"</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">group</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-223">that results in the following output:</span></p><div class="highlight-text"><div class="highlight"><pre><span></span>Usage: &lt;yourscript&gt; [options] arg1 arg2
Options:
-h, --help show this help message and exit
-v, --verbose make lots of noise [default]
-q, --quiet be vewwy quiet (I'm hunting wabbits)
-f FILE, --filename=FILE
write output to FILE
-m MODE, --mode=MODE interaction mode: novice, intermediate, or expert
[default: intermediate]
Dangerous Options:
Caution: use these options at your own risk. It is believed that some
of them bite.
-g Group option.
Debug Options:
-d, --debug Print debug information
-s, --sql Print all SQL statements executed
-e Print every action done
</pre></div></div><p><span class="yiyi-st" id="yiyi-224">Another interesting method, in particular when working programmatically with option groups is:</span></p><dl class="method"><dt id="optparse.OptionParser.get_option_group"><span class="yiyi-st" id="yiyi-225"> <code class="descclassname">OptionParser.</code><code class="descname">get_option_group</code><span class="sig-paren">(</span><em>opt_str</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-226">Return the <a class="reference internal" href="#optparse.OptionGroup" title="optparse.OptionGroup"><code class="xref py py-class docutils literal"><span class="pre">OptionGroup</span></code></a> to which the short or long option string <em>opt_str</em> (e.g. </span><span class="yiyi-st" id="yiyi-227"><code class="docutils literal"><span class="pre">'-o'</span></code> or <code class="docutils literal"><span class="pre">'--option'</span></code>) belongs. </span><span class="yiyi-st" id="yiyi-228">If there’s no such <a class="reference internal" href="#optparse.OptionGroup" title="optparse.OptionGroup"><code class="xref py py-class docutils literal"><span class="pre">OptionGroup</span></code></a>, return <code class="docutils literal"><span class="pre">None</span></code>.</span></p></dd></dl></div></div><div class="section" id="printing-a-version-string"><h3><span class="yiyi-st" id="yiyi-229">36.1.2.7. </span><span class="yiyi-st" id="yiyi-230">Printing a version string</span></h3><p><span class="yiyi-st" id="yiyi-231">Similar to the brief usage string, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> can also print a version string for your program. </span><span class="yiyi-st" id="yiyi-232">You have to supply the string as the <code class="docutils literal"><span class="pre">version</span></code> argument to OptionParser:</span></p><pre><code class="language-python"><span></span><span class="n">parser</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="s2">"%prog [-f] [-q]"</span><span class="p">,</span> <span class="n">version</span><span class="o">=</span><span class="s2">"%prog 1.0"</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-233"><code class="docutils literal"><span class="pre">%prog</span></code> is expanded just like it is in <code class="docutils literal"><span class="pre">usage</span></code>. </span><span class="yiyi-st" id="yiyi-234">Apart from that, <code class="docutils literal"><span class="pre">version</span></code> can contain anything you like. </span><span class="yiyi-st" id="yiyi-235">When you supply it, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> automatically adds a <code class="docutils literal"><span class="pre">--version</span></code> option to your parser. </span><span class="yiyi-st" id="yiyi-236">If it encounters this option on the command line, it expands your <code class="docutils literal"><span class="pre">version</span></code> string (by replacing <code class="docutils literal"><span class="pre">%prog</span></code>), prints it to stdout, and exits.</span></p><p><span class="yiyi-st" id="yiyi-237">For example, if your script is called <code class="docutils literal"><span class="pre">/usr/bin/foo</span></code>:</span></p><div class="highlight-shell-session"><div class="highlight"><pre><span></span><span class="gp">$</span> /usr/bin/foo --version
<span class="go">foo 1.0</span>
</pre></div></div><p><span class="yiyi-st" id="yiyi-238">The following two methods can be used to print and get the <code class="docutils literal"><span class="pre">version</span></code> string:</span></p><dl class="method"><dt id="optparse.OptionParser.print_version"><span class="yiyi-st" id="yiyi-239"> <code class="descclassname">OptionParser.</code><code class="descname">print_version</code><span class="sig-paren">(</span><em>file=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-240">Print the version message for the current program (<code class="docutils literal"><span class="pre">self.version</span></code>) to <em>file</em> (default stdout). </span><span class="yiyi-st" id="yiyi-241">As with <a class="reference internal" href="#optparse.OptionParser.print_usage" title="optparse.OptionParser.print_usage"><code class="xref py py-meth docutils literal"><span class="pre">print_usage()</span></code></a>, any occurrence of <code class="docutils literal"><span class="pre">%prog</span></code> in <code class="docutils literal"><span class="pre">self.version</span></code> is replaced with the name of the current program. </span><span class="yiyi-st" id="yiyi-242">Does nothing if <code class="docutils literal"><span class="pre">self.version</span></code> is empty or undefined.</span></p></dd></dl><dl class="method"><dt id="optparse.OptionParser.get_version"><span class="yiyi-st" id="yiyi-243"> <code class="descclassname">OptionParser.</code><code class="descname">get_version</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-244">Same as <a class="reference internal" href="#optparse.OptionParser.print_version" title="optparse.OptionParser.print_version"><code class="xref py py-meth docutils literal"><span class="pre">print_version()</span></code></a> but returns the version string instead of printing it.</span></p></dd></dl></div><div class="section" id="how-optparse-handles-errors"><h3><span class="yiyi-st" id="yiyi-245">36.1.2.8. </span><span class="yiyi-st" id="yiyi-246">How <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> handles errors</span></h3><p><span class="yiyi-st" id="yiyi-247">There are two broad classes of errors that <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> has to worry about: programmer errors and user errors. </span><span class="yiyi-st" id="yiyi-248">Programmer errors are usually erroneous calls to <a class="reference internal" href="#optparse.OptionParser.add_option" title="optparse.OptionParser.add_option"><code class="xref py py-func docutils literal"><span class="pre">OptionParser.add_option()</span></code></a>, e.g. </span><span class="yiyi-st" id="yiyi-249">invalid option strings, unknown option attributes, missing option attributes, etc. </span><span class="yiyi-st" id="yiyi-250">These are dealt with in the usual way: raise an exception (either <code class="xref py py-exc docutils literal"><span class="pre">optparse.OptionError</span></code> or <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal"><span class="pre">TypeError</span></code></a>) and let the program crash.</span></p><p><span class="yiyi-st" id="yiyi-251">Handling user errors is much more important, since they are guaranteed to happen no matter how stable your code is. </span><span class="yiyi-st" id="yiyi-252"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> can automatically detect some user errors, such as bad option arguments (passing <code class="docutils literal"><span class="pre">-n</span> <span class="pre">4x</span></code> where <code class="docutils literal"><span class="pre">-n</span></code> takes an integer argument), missing arguments (<code class="docutils literal"><span class="pre">-n</span></code> at the end of the command line, where <code class="docutils literal"><span class="pre">-n</span></code> takes an argument of any type). </span><span class="yiyi-st" id="yiyi-253">Also, you can call <code class="xref py py-func docutils literal"><span class="pre">OptionParser.error()</span></code> to signal an application-defined error condition:</span></p><pre><code class="language-python"><span></span><span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">)</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="o">...</span>
<span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">a</span> <span class="ow">and</span> <span class="n">options</span><span class="o">.</span><span class="n">b</span><span class="p">:</span>
<span class="n">parser</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s2">"options -a and -b are mutually exclusive"</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-254">In either case, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> handles the error the same way: it prints the program’s usage message and an error message to standard error and exits with error status 2.</span></p><p><span class="yiyi-st" id="yiyi-255">Consider the first example above, where the user passes <code class="docutils literal"><span class="pre">4x</span></code> to an option that takes an integer:</span></p><div class="highlight-shell-session"><div class="highlight"><pre><span></span><span class="gp">$</span> /usr/bin/foo -n 4x
<span class="go">Usage: foo [options]</span>
<span class="go">foo: error: option -n: invalid integer value: '4x'</span>
</pre></div></div><p><span class="yiyi-st" id="yiyi-256">Or, where the user fails to pass a value at all:</span></p><div class="highlight-shell-session"><div class="highlight"><pre><span></span><span class="gp">$</span> /usr/bin/foo -n
<span class="go">Usage: foo [options]</span>
<span class="go">foo: error: -n option requires an argument</span>
</pre></div></div><p><span class="yiyi-st" id="yiyi-257"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a>-generated error messages take care always to mention the option involved in the error; be sure to do the same when calling <code class="xref py py-func docutils literal"><span class="pre">OptionParser.error()</span></code> from your application code.</span></p><p><span class="yiyi-st" id="yiyi-258">If <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a>‘s default error-handling behaviour does not suit your needs, you’ll need to subclass OptionParser and override its <code class="xref py py-meth docutils literal"><span class="pre">exit()</span></code> and/or <code class="xref py py-meth docutils literal"><span class="pre">error()</span></code> methods.</span></p></div><div class="section" id="putting-it-all-together"><h3><span class="yiyi-st" id="yiyi-259">36.1.2.9. </span><span class="yiyi-st" id="yiyi-260">Putting it all together</span></h3><p><span class="yiyi-st" id="yiyi-261">Here’s what <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a>-based scripts usually look like:</span></p><pre><code class="language-python"><span></span><span class="kn">from</span> <span class="nn">optparse</span> <span class="k">import</span> <span class="n">OptionParser</span>
<span class="o">...</span>
<span class="k">def</span> <span class="nf">main</span><span class="p">():</span>
<span class="n">usage</span> <span class="o">=</span> <span class="s2">"usage: %prog [options] arg"</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">(</span><span class="n">usage</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="s2">"-f"</span><span class="p">,</span> <span class="s2">"--file"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"filename"</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s2">"read data from FILENAME"</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="s2">"-v"</span><span class="p">,</span> <span class="s2">"--verbose"</span><span class="p">,</span>
<span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</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="s2">"-q"</span><span class="p">,</span> <span class="s2">"--quiet"</span><span class="p">,</span>
<span class="n">action</span><span class="o">=</span><span class="s2">"store_false"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">)</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="p">)</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">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">args</span><span class="p">)</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">error</span><span class="p">(</span><span class="s2">"incorrect number of arguments"</span><span class="p">)</span>
<span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">verbose</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">"reading </span><span class="si">%s</span><span class="s2">..."</span> <span class="o">%</span> <span class="n">options</span><span class="o">.</span><span class="n">filename</span><span class="p">)</span>
<span class="o">...</span>
<span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s2">"__main__"</span><span class="p">:</span>
<span class="n">main</span><span class="p">()</span>
</code></pre></div></div><div class="section" id="reference-guide"><h2><span class="yiyi-st" id="yiyi-262">36.1.3. </span><span class="yiyi-st" id="yiyi-263">Reference Guide</span></h2><div class="section" id="creating-the-parser"><h3><span class="yiyi-st" id="yiyi-264">36.1.3.1. </span><span class="yiyi-st" id="yiyi-265">Creating the parser</span></h3><p><span class="yiyi-st" id="yiyi-266">The first step in using <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> is to create an OptionParser instance.</span></p><dl class="class"><dt id="optparse.OptionParser"><span class="yiyi-st" id="yiyi-267"> <em class="property">class </em><code class="descclassname">optparse.</code><code class="descname">OptionParser</code><span class="sig-paren">(</span><em>...</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-268">The OptionParser constructor has no required arguments, but a number of optional keyword arguments. </span><span class="yiyi-st" id="yiyi-269">You should always pass them as keyword arguments, i.e. </span><span class="yiyi-st" id="yiyi-270">do not rely on the order in which the arguments are declared.</span></p><dl class="docutils"><dt><span class="yiyi-st" id="yiyi-271"><code class="docutils literal"><span class="pre">usage</span></code> (default: <code class="docutils literal"><span class="pre">"%prog</span> <span class="pre">[options]"</span></code>)</span></dt><dd><span class="yiyi-st" id="yiyi-272">The usage summary to print when your program is run incorrectly or with a help option. </span><span class="yiyi-st" id="yiyi-273">When <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> prints the usage string, it expands <code class="docutils literal"><span class="pre">%prog</span></code> to <code class="docutils literal"><span class="pre">os.path.basename(sys.argv[0])</span></code> (or to <code class="docutils literal"><span class="pre">prog</span></code> if you passed that keyword argument). </span><span class="yiyi-st" id="yiyi-274">To suppress a usage message, pass the special value <code class="xref py py-data docutils literal"><span class="pre">optparse.SUPPRESS_USAGE</span></code>.</span></dd><dt><span class="yiyi-st" id="yiyi-275"><code class="docutils literal"><span class="pre">option_list</span></code> (default: <code class="docutils literal"><span class="pre">[]</span></code>)</span></dt><dd><span class="yiyi-st" id="yiyi-276">A list of Option objects to populate the parser with. </span><span class="yiyi-st" id="yiyi-277">The options in <code class="docutils literal"><span class="pre">option_list</span></code> are added after any options in <code class="docutils literal"><span class="pre">standard_option_list</span></code> (a class attribute that may be set by OptionParser subclasses), but before any version or help options. </span><span class="yiyi-st" id="yiyi-278">Deprecated; use <a class="reference internal" href="#optparse.OptionParser.add_option" title="optparse.OptionParser.add_option"><code class="xref py py-meth docutils literal"><span class="pre">add_option()</span></code></a> after creating the parser instead.</span></dd><dt><span class="yiyi-st" id="yiyi-279"><code class="docutils literal"><span class="pre">option_class</span></code> (default: optparse.Option)</span></dt><dd><span class="yiyi-st" id="yiyi-280">Class to use when adding options to the parser in <a class="reference internal" href="#optparse.OptionParser.add_option" title="optparse.OptionParser.add_option"><code class="xref py py-meth docutils literal"><span class="pre">add_option()</span></code></a>.</span></dd><dt><span class="yiyi-st" id="yiyi-281"><code class="docutils literal"><span class="pre">version</span></code> (default: <code class="docutils literal"><span class="pre">None</span></code>)</span></dt><dd><span class="yiyi-st" id="yiyi-282">A version string to print when the user supplies a version option. </span><span class="yiyi-st" id="yiyi-283">If you supply a true value for <code class="docutils literal"><span class="pre">version</span></code>, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> automatically adds a version option with the single option string <code class="docutils literal"><span class="pre">--version</span></code>. </span><span class="yiyi-st" id="yiyi-284">The substring <code class="docutils literal"><span class="pre">%prog</span></code> is expanded the same as for <code class="docutils literal"><span class="pre">usage</span></code>.</span></dd><dt><span class="yiyi-st" id="yiyi-285"><code class="docutils literal"><span class="pre">conflict_handler</span></code> (default: <code class="docutils literal"><span class="pre">"error"</span></code>)</span></dt><dd><span class="yiyi-st" id="yiyi-286">Specifies what to do when options with conflicting option strings are added to the parser; see section <a class="reference internal" href="#optparse-conflicts-between-options"><span>Conflicts between options</span></a>.</span></dd><dt><span class="yiyi-st" id="yiyi-287"><code class="docutils literal"><span class="pre">description</span></code> (default: <code class="docutils literal"><span class="pre">None</span></code>)</span></dt><dd><span class="yiyi-st" id="yiyi-288">A paragraph of text giving a brief overview of your program. </span><span class="yiyi-st" id="yiyi-289"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> reformats this paragraph to fit the current terminal width and prints it when the user requests help (after <code class="docutils literal"><span class="pre">usage</span></code>, but before the list of options).</span></dd><dt><span class="yiyi-st" id="yiyi-290"><code class="docutils literal"><span class="pre">formatter</span></code> (default: a new <code class="xref py py-class docutils literal"><span class="pre">IndentedHelpFormatter</span></code>)</span></dt><dd><span class="yiyi-st" id="yiyi-291">An instance of optparse.HelpFormatter that will be used for printing help text. </span><span class="yiyi-st" id="yiyi-292"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> provides two concrete classes for this purpose: IndentedHelpFormatter and TitledHelpFormatter.</span></dd><dt><span class="yiyi-st" id="yiyi-293"><code class="docutils literal"><span class="pre">add_help_option</span></code> (default: <code class="docutils literal"><span class="pre">True</span></code>)</span></dt><dd><span class="yiyi-st" id="yiyi-294">If true, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> will add a help option (with option strings <code class="docutils literal"><span class="pre">-h</span></code> and <code class="docutils literal"><span class="pre">--help</span></code>) to the parser.</span></dd><dt><span class="yiyi-st" id="yiyi-295"><code class="docutils literal"><span class="pre">prog</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-296">The string to use when expanding <code class="docutils literal"><span class="pre">%prog</span></code> in <code class="docutils literal"><span class="pre">usage</span></code> and <code class="docutils literal"><span class="pre">version</span></code> instead of <code class="docutils literal"><span class="pre">os.path.basename(sys.argv[0])</span></code>.</span></dd><dt><span class="yiyi-st" id="yiyi-297"><code class="docutils literal"><span class="pre">epilog</span></code> (default: <code class="docutils literal"><span class="pre">None</span></code>)</span></dt><dd><span class="yiyi-st" id="yiyi-298">A paragraph of help text to print after the option help.</span></dd></dl></dd></dl></div><div class="section" id="populating-the-parser"><h3><span class="yiyi-st" id="yiyi-299">36.1.3.2. </span><span class="yiyi-st" id="yiyi-300">Populating the parser</span></h3><p><span class="yiyi-st" id="yiyi-301">There are several ways to populate the parser with options. </span><span class="yiyi-st" id="yiyi-302">The preferred way is by using <a class="reference internal" href="#optparse.OptionParser.add_option" title="optparse.OptionParser.add_option"><code class="xref py py-meth docutils literal"><span class="pre">OptionParser.add_option()</span></code></a>, as shown in section <a class="reference internal" href="#optparse-tutorial"><span>Tutorial</span></a>. </span><span class="yiyi-st" id="yiyi-303"><code class="xref py py-meth docutils literal"><span class="pre">add_option()</span></code> can be called in one of two ways:</span></p><ul class="simple"><li><span class="yiyi-st" id="yiyi-304">pass it an Option instance (as returned by <code class="xref py py-func docutils literal"><span class="pre">make_option()</span></code>)</span></li><li><span class="yiyi-st" id="yiyi-305">pass it any combination of positional and keyword arguments that are acceptable to <code class="xref py py-func docutils literal"><span class="pre">make_option()</span></code> (i.e., to the Option constructor), and it will create the Option instance for you</span></li></ul><p><span class="yiyi-st" id="yiyi-306">The other alternative is to pass a list of pre-constructed Option instances to the OptionParser constructor, as in:</span></p><pre><code class="language-python"><span></span><span class="n">option_list</span> <span class="o">=</span> <span class="p">[</span>
<span class="n">make_option</span><span class="p">(</span><span class="s2">"-f"</span><span class="p">,</span> <span class="s2">"--filename"</span><span class="p">,</span>
<span class="n">action</span><span class="o">=</span><span class="s2">"store"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s2">"string"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"filename"</span><span class="p">),</span>
<span class="n">make_option</span><span class="p">(</span><span class="s2">"-q"</span><span class="p">,</span> <span class="s2">"--quiet"</span><span class="p">,</span>
<span class="n">action</span><span class="o">=</span><span class="s2">"store_false"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">),</span>
<span class="p">]</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">(</span><span class="n">option_list</span><span class="o">=</span><span class="n">option_list</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-307">(<code class="xref py py-func docutils literal"><span class="pre">make_option()</span></code> is a factory function for creating Option instances; currently it is an alias for the Option constructor. </span><span class="yiyi-st" id="yiyi-308">A future version of <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> may split Option into several classes, and <code class="xref py py-func docutils literal"><span class="pre">make_option()</span></code> will pick the right class to instantiate. </span><span class="yiyi-st" id="yiyi-309">Do not instantiate Option directly.)</span></p></div><div class="section" id="defining-options"><h3><span class="yiyi-st" id="yiyi-310">36.1.3.3. </span><span class="yiyi-st" id="yiyi-311">Defining options</span></h3><p><span class="yiyi-st" id="yiyi-312">Each Option instance represents a set of synonymous command-line option strings, e.g. </span><span class="yiyi-st" id="yiyi-313"><code class="docutils literal"><span class="pre">-f</span></code> and <code class="docutils literal"><span class="pre">--file</span></code>. </span><span class="yiyi-st" id="yiyi-314">You can specify any number of short or long option strings, but you must specify at least one overall option string.</span></p><p><span class="yiyi-st" id="yiyi-315">The canonical way to create an <code class="xref py py-class docutils literal"><span class="pre">Option</span></code> instance is with the <code class="xref py py-meth docutils literal"><span class="pre">add_option()</span></code> method of <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal"><span class="pre">OptionParser</span></code></a>.</span></p><dl class="method"><dt id="optparse.OptionParser.add_option"><span class="yiyi-st" id="yiyi-316"> <code class="descclassname">OptionParser.</code><code class="descname">add_option</code><span class="sig-paren">(</span><em>option</em><span class="sig-paren">)</span></span></dt><dt><span class="yiyi-st" id="yiyi-317"> <code class="descclassname">OptionParser.</code><code class="descname">add_option</code><span class="sig-paren">(</span><em>*opt_str</em>, <em>attr=value</em>, <em>...</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-318">To define an option with only a short option string:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-f"</span><span class="p">,</span> <span class="n">attr</span><span class="o">=</span><span class="n">value</span><span class="p">,</span> <span class="o">...</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-319">And to define an option with only a long option string:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--foo"</span><span class="p">,</span> <span class="n">attr</span><span class="o">=</span><span class="n">value</span><span class="p">,</span> <span class="o">...</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-320">The keyword arguments define attributes of the new Option object. </span><span class="yiyi-st" id="yiyi-321">The most important option attribute is <a class="reference internal" href="#optparse.Option.action" title="optparse.Option.action"><code class="xref py py-attr docutils literal"><span class="pre">action</span></code></a>, and it largely determines which other attributes are relevant or required. </span><span class="yiyi-st" id="yiyi-322">If you pass irrelevant option attributes, or fail to pass required ones, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> raises an <code class="xref py py-exc docutils literal"><span class="pre">OptionError</span></code> exception explaining your mistake.</span></p><p><span class="yiyi-st" id="yiyi-323">An option’s <em>action</em> determines what <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> does when it encounters this option on the command-line. </span><span class="yiyi-st" id="yiyi-324">The standard option actions hard-coded into <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> are:</span></p><dl class="docutils"><dt><span class="yiyi-st" id="yiyi-325"><code class="docutils literal"><span class="pre">"store"</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-326">store this option’s argument (default)</span></dd><dt><span class="yiyi-st" id="yiyi-327"><code class="docutils literal"><span class="pre">"store_const"</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-328">store a constant value</span></dd><dt><span class="yiyi-st" id="yiyi-329"><code class="docutils literal"><span class="pre">"store_true"</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-330">store a true value</span></dd><dt><span class="yiyi-st" id="yiyi-331"><code class="docutils literal"><span class="pre">"store_false"</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-332">store a false value</span></dd><dt><span class="yiyi-st" id="yiyi-333"><code class="docutils literal"><span class="pre">"append"</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-334">append this option’s argument to a list</span></dd><dt><span class="yiyi-st" id="yiyi-335"><code class="docutils literal"><span class="pre">"append_const"</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-336">append a constant value to a list</span></dd><dt><span class="yiyi-st" id="yiyi-337"><code class="docutils literal"><span class="pre">"count"</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-338">increment a counter by one</span></dd><dt><span class="yiyi-st" id="yiyi-339"><code class="docutils literal"><span class="pre">"callback"</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-340">call a specified function</span></dd><dt><span class="yiyi-st" id="yiyi-341"><code class="docutils literal"><span class="pre">"help"</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-342">print a usage message including all options and the documentation for them</span></dd></dl><p><span class="yiyi-st" id="yiyi-343">(If you don’t supply an action, the default is <code class="docutils literal"><span class="pre">"store"</span></code>. </span><span class="yiyi-st" id="yiyi-344">For this action, you may also supply <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal"><span class="pre">type</span></code></a> and <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a> option attributes; see <a class="reference internal" href="#optparse-standard-option-actions"><span>Standard option actions</span></a>.)</span></p></dd></dl><p><span class="yiyi-st" id="yiyi-345">As you can see, most actions involve storing or updating a value somewhere. </span><span class="yiyi-st" id="yiyi-346"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> always creates a special object for this, conventionally called <code class="docutils literal"><span class="pre">options</span></code> (it happens to be an instance of <code class="xref py py-class docutils literal"><span class="pre">optparse.Values</span></code>). </span><span class="yiyi-st" id="yiyi-347">Option arguments (and various other values) are stored as attributes of this object, according to the <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a> (destination) option attribute.</span></p><p><span class="yiyi-st" id="yiyi-348">For example, when you call</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
</code></pre><p><span class="yiyi-st" id="yiyi-349">one of the first things <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> does is create the <code class="docutils literal"><span class="pre">options</span></code> object:</span></p><pre><code class="language-python"><span></span><span class="n">options</span> <span class="o">=</span> <span class="n">Values</span><span class="p">()</span>
</code></pre><p><span class="yiyi-st" id="yiyi-350">If one of the options in this parser is defined with</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-f"</span><span class="p">,</span> <span class="s2">"--file"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s2">"string"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"filename"</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-351">and the command-line being parsed includes any of the following:</span></p><pre><code class="language-python"><span></span><span class="o">-</span><span class="n">ffoo</span>
<span class="o">-</span><span class="n">f</span> <span class="n">foo</span>
<span class="o">--</span><span class="n">file</span><span class="o">=</span><span class="n">foo</span>
<span class="o">--</span><span class="n">file</span> <span class="n">foo</span>
</code></pre><p><span class="yiyi-st" id="yiyi-352">then <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a>, on seeing this option, will do the equivalent of</span></p><pre><code class="language-python"><span></span><span class="n">options</span><span class="o">.</span><span class="n">filename</span> <span class="o">=</span> <span class="s2">"foo"</span>
</code></pre><p><span class="yiyi-st" id="yiyi-353">The <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal"><span class="pre">type</span></code></a> and <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a> option attributes are almost as important as <a class="reference internal" href="#optparse.Option.action" title="optparse.Option.action"><code class="xref py py-attr docutils literal"><span class="pre">action</span></code></a>, but <a class="reference internal" href="#optparse.Option.action" title="optparse.Option.action"><code class="xref py py-attr docutils literal"><span class="pre">action</span></code></a> is the only one that makes sense for <em>all</em> options.</span></p></div><div class="section" id="option-attributes"><h3><span class="yiyi-st" id="yiyi-354">36.1.3.4. </span><span class="yiyi-st" id="yiyi-355">Option attributes</span></h3><p><span class="yiyi-st" id="yiyi-356">The following option attributes may be passed as keyword arguments to <a class="reference internal" href="#optparse.OptionParser.add_option" title="optparse.OptionParser.add_option"><code class="xref py py-meth docutils literal"><span class="pre">OptionParser.add_option()</span></code></a>. </span><span class="yiyi-st" id="yiyi-357">If you pass an option attribute that is not relevant to a particular option, or fail to pass a required option attribute, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> raises <code class="xref py py-exc docutils literal"><span class="pre">OptionError</span></code>.</span></p><dl class="attribute"><dt id="optparse.Option.action"><span class="yiyi-st" id="yiyi-358"> <code class="descclassname">Option.</code><code class="descname">action</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-359">(default: <code class="docutils literal"><span class="pre">"store"</span></code>)</span></p><p><span class="yiyi-st" id="yiyi-360">Determines <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a>‘s behaviour when this option is seen on the command line; the available options are documented <a class="reference internal" href="#optparse-standard-option-actions"><span>here</span></a>.</span></p></dd></dl><dl class="attribute"><dt id="optparse.Option.type"><span class="yiyi-st" id="yiyi-361"> <code class="descclassname">Option.</code><code class="descname">type</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-362">(default: <code class="docutils literal"><span class="pre">"string"</span></code>)</span></p><p><span class="yiyi-st" id="yiyi-363">The argument type expected by this option (e.g., <code class="docutils literal"><span class="pre">"string"</span></code> or <code class="docutils literal"><span class="pre">"int"</span></code>); the available option types are documented <a class="reference internal" href="#optparse-standard-option-types"><span>here</span></a>.</span></p></dd></dl><dl class="attribute"><dt id="optparse.Option.dest"><span class="yiyi-st" id="yiyi-364"> <code class="descclassname">Option.</code><code class="descname">dest</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-365">(default: derived from option strings)</span></p><p><span class="yiyi-st" id="yiyi-366">If the option’s action implies writing or modifying a value somewhere, this tells <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> where to write it: <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a> names an attribute of the <code class="docutils literal"><span class="pre">options</span></code> object that <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> builds as it parses the command line.</span></p></dd></dl><dl class="attribute"><dt id="optparse.Option.default"><span class="yiyi-st" id="yiyi-367"> <code class="descclassname">Option.</code><code class="descname">default</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-368">The value to use for this option’s destination if the option is not seen on the command line. </span><span class="yiyi-st" id="yiyi-369">See also <a class="reference internal" href="#optparse.OptionParser.set_defaults" title="optparse.OptionParser.set_defaults"><code class="xref py py-meth docutils literal"><span class="pre">OptionParser.set_defaults()</span></code></a>.</span></p></dd></dl><dl class="attribute"><dt id="optparse.Option.nargs"><span class="yiyi-st" id="yiyi-370"> <code class="descclassname">Option.</code><code class="descname">nargs</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-371">(default: 1)</span></p><p><span class="yiyi-st" id="yiyi-372">How many arguments of type <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal"><span class="pre">type</span></code></a> should be consumed when this option is seen. </span><span class="yiyi-st" id="yiyi-373">If &gt; 1, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> will store a tuple of values to <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a>.</span></p></dd></dl><dl class="attribute"><dt id="optparse.Option.const"><span class="yiyi-st" id="yiyi-374"> <code class="descclassname">Option.</code><code class="descname">const</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-375">For actions that store a constant value, the constant value to store.</span></p></dd></dl><dl class="attribute"><dt id="optparse.Option.choices"><span class="yiyi-st" id="yiyi-376"> <code class="descclassname">Option.</code><code class="descname">choices</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-377">For options of type <code class="docutils literal"><span class="pre">"choice"</span></code>, the list of strings the user may choose from.</span></p></dd></dl><dl class="attribute"><dt id="optparse.Option.callback"><span class="yiyi-st" id="yiyi-378"> <code class="descclassname">Option.</code><code class="descname">callback</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-379">For options with action <code class="docutils literal"><span class="pre">"callback"</span></code>, the callable to call when this option is seen. </span><span class="yiyi-st" id="yiyi-380">See section <a class="reference internal" href="#optparse-option-callbacks"><span>Option Callbacks</span></a> for detail on the arguments passed to the callable.</span></p></dd></dl><dl class="attribute"><dt id="optparse.Option.callback_args"><span class="yiyi-st" id="yiyi-381"> <code class="descclassname">Option.</code><code class="descname">callback_args</code></span></dt><dt id="optparse.Option.callback_kwargs"><span class="yiyi-st" id="yiyi-382"> <code class="descclassname">Option.</code><code class="descname">callback_kwargs</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-383">Additional positional and keyword arguments to pass to <code class="docutils literal"><span class="pre">callback</span></code> after the four standard callback arguments.</span></p></dd></dl><dl class="attribute"><dt id="optparse.Option.help"><span class="yiyi-st" id="yiyi-384"> <code class="descclassname">Option.</code><code class="descname">help</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-385">Help text to print for this option when listing all available options after the user supplies a <a class="reference internal" href="#optparse.Option.help" title="optparse.Option.help"><code class="xref py py-attr docutils literal"><span class="pre">help</span></code></a> option (such as <code class="docutils literal"><span class="pre">--help</span></code>). </span><span class="yiyi-st" id="yiyi-386">If no help text is supplied, the option will be listed without help text. </span><span class="yiyi-st" id="yiyi-387">To hide this option, use the special value <code class="xref py py-data docutils literal"><span class="pre">optparse.SUPPRESS_HELP</span></code>.</span></p></dd></dl><dl class="attribute"><dt id="optparse.Option.metavar"><span class="yiyi-st" id="yiyi-388"> <code class="descclassname">Option.</code><code class="descname">metavar</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-389">(default: derived from option strings)</span></p><p><span class="yiyi-st" id="yiyi-390">Stand-in for the option argument(s) to use when printing help text. </span><span class="yiyi-st" id="yiyi-391">See section <a class="reference internal" href="#optparse-tutorial"><span>Tutorial</span></a> for an example.</span></p></dd></dl></div><div class="section" id="standard-option-actions"><h3><span class="yiyi-st" id="yiyi-392">36.1.3.5. </span><span class="yiyi-st" id="yiyi-393">Standard option actions</span></h3><p><span class="yiyi-st" id="yiyi-394">The various option actions all have slightly different requirements and effects. </span><span class="yiyi-st" id="yiyi-395">Most actions have several relevant option attributes which you may specify to guide <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a>‘s behaviour; a few have required attributes, which you must specify for any option using that action.</span></p><ul><li><p class="first"><span class="yiyi-st" id="yiyi-396"><code class="docutils literal"><span class="pre">"store"</span></code> [relevant: <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal"><span class="pre">type</span></code></a>, <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a>, <a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal"><span class="pre">nargs</span></code></a>, <a class="reference internal" href="#optparse.Option.choices" title="optparse.Option.choices"><code class="xref py py-attr docutils literal"><span class="pre">choices</span></code></a>]</span></p><p><span class="yiyi-st" id="yiyi-397">The option must be followed by an argument, which is converted to a value according to <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal"><span class="pre">type</span></code></a> and stored in <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a>. </span><span class="yiyi-st" id="yiyi-398">If <a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal"><span class="pre">nargs</span></code></a> &gt; 1, multiple arguments will be consumed from the command line; all will be converted according to <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal"><span class="pre">type</span></code></a> and stored to <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a> as a tuple. </span><span class="yiyi-st" id="yiyi-399">See the <a class="reference internal" href="#optparse-standard-option-types"><span>Standard option types</span></a> section.</span></p><p><span class="yiyi-st" id="yiyi-400">If <a class="reference internal" href="#optparse.Option.choices" title="optparse.Option.choices"><code class="xref py py-attr docutils literal"><span class="pre">choices</span></code></a> is supplied (a list or tuple of strings), the type defaults to <code class="docutils literal"><span class="pre">"choice"</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-401">If <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal"><span class="pre">type</span></code></a> is not supplied, it defaults to <code class="docutils literal"><span class="pre">"string"</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-402">If <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a> is not supplied, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> derives a destination from the first long option string (e.g., <code class="docutils literal"><span class="pre">--foo-bar</span></code> implies <code class="docutils literal"><span class="pre">foo_bar</span></code>). </span><span class="yiyi-st" id="yiyi-403">If there are no long option strings, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> derives a destination from the first short option string (e.g., <code class="docutils literal"><span class="pre">-f</span></code> implies <code class="docutils literal"><span class="pre">f</span></code>).</span></p><p><span class="yiyi-st" id="yiyi-404">Example:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-f"</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="s2">"-p"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s2">"float"</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"point"</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-405">As it parses the command line</span></p><pre><code class="language-python"><span></span><span class="o">-</span><span class="n">f</span> <span class="n">foo</span><span class="o">.</span><span class="n">txt</span> <span class="o">-</span><span class="n">p</span> <span class="mi">1</span> <span class="o">-</span><span class="mf">3.5</span> <span class="mi">4</span> <span class="o">-</span><span class="n">fbar</span><span class="o">.</span><span class="n">txt</span>
</code></pre><p><span class="yiyi-st" id="yiyi-406"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> will set</span></p><pre><code class="language-python"><span></span><span class="n">options</span><span class="o">.</span><span class="n">f</span> <span class="o">=</span> <span class="s2">"foo.txt"</span>
<span class="n">options</span><span class="o">.</span><span class="n">point</span> <span class="o">=</span> <span class="p">(</span><span class="mf">1.0</span><span class="p">,</span> <span class="o">-</span><span class="mf">3.5</span><span class="p">,</span> <span class="mf">4.0</span><span class="p">)</span>
<span class="n">options</span><span class="o">.</span><span class="n">f</span> <span class="o">=</span> <span class="s2">"bar.txt"</span>
</code></pre></li><li><p class="first"><span class="yiyi-st" id="yiyi-407"><code class="docutils literal"><span class="pre">"store_const"</span></code> [required: <a class="reference internal" href="#optparse.Option.const" title="optparse.Option.const"><code class="xref py py-attr docutils literal"><span class="pre">const</span></code></a>; relevant: <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a>]</span></p><p><span class="yiyi-st" id="yiyi-408">The value <a class="reference internal" href="#optparse.Option.const" title="optparse.Option.const"><code class="xref py py-attr docutils literal"><span class="pre">const</span></code></a> is stored in <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a>.</span></p><p><span class="yiyi-st" id="yiyi-409">Example:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-q"</span><span class="p">,</span> <span class="s2">"--quiet"</span><span class="p">,</span>
<span class="n">action</span><span class="o">=</span><span class="s2">"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="s2">"verbose"</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="s2">"-v"</span><span class="p">,</span> <span class="s2">"--verbose"</span><span class="p">,</span>
<span class="n">action</span><span class="o">=</span><span class="s2">"store_const"</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</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="s2">"--noisy"</span><span class="p">,</span>
<span class="n">action</span><span class="o">=</span><span class="s2">"store_const"</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-410">If <code class="docutils literal"><span class="pre">--noisy</span></code> is seen, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> will set</span></p><pre><code class="language-python"><span></span><span class="n">options</span><span class="o">.</span><span class="n">verbose</span> <span class="o">=</span> <span class="mi">2</span>
</code></pre></li><li><p class="first"><span class="yiyi-st" id="yiyi-411"><code class="docutils literal"><span class="pre">"store_true"</span></code> [relevant: <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a>]</span></p><p><span class="yiyi-st" id="yiyi-412">A special case of <code class="docutils literal"><span class="pre">"store_const"</span></code> that stores a true value to <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a>.</span></p></li><li><p class="first"><span class="yiyi-st" id="yiyi-413"><code class="docutils literal"><span class="pre">"store_false"</span></code> [relevant: <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a>]</span></p><p><span class="yiyi-st" id="yiyi-414">Like <code class="docutils literal"><span class="pre">"store_true"</span></code>, but stores a false value.</span></p><p><span class="yiyi-st" id="yiyi-415">Example:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--clobber"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"clobber"</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="s2">"--no-clobber"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_false"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"clobber"</span><span class="p">)</span>
</code></pre></li><li><p class="first"><span class="yiyi-st" id="yiyi-416"><code class="docutils literal"><span class="pre">"append"</span></code> [relevant: <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal"><span class="pre">type</span></code></a>, <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a>, <a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal"><span class="pre">nargs</span></code></a>, <a class="reference internal" href="#optparse.Option.choices" title="optparse.Option.choices"><code class="xref py py-attr docutils literal"><span class="pre">choices</span></code></a>]</span></p><p><span class="yiyi-st" id="yiyi-417">The option must be followed by an argument, which is appended to the list in <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a>. </span><span class="yiyi-st" id="yiyi-418">If no default value for <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a> is supplied, an empty list is automatically created when <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> first encounters this option on the command-line. </span><span class="yiyi-st" id="yiyi-419">If <a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal"><span class="pre">nargs</span></code></a> &gt; 1, multiple arguments are consumed, and a tuple of length <a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal"><span class="pre">nargs</span></code></a> is appended to <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a>.</span></p><p><span class="yiyi-st" id="yiyi-420">The defaults for <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal"><span class="pre">type</span></code></a> and <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a> are the same as for the <code class="docutils literal"><span class="pre">"store"</span></code> action.</span></p><p><span class="yiyi-st" id="yiyi-421">Example:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-t"</span><span class="p">,</span> <span class="s2">"--tracks"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"append"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s2">"int"</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-422">If <code class="docutils literal"><span class="pre">-t3</span></code> is seen on the command-line, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> does the equivalent of:</span></p><pre><code class="language-python"><span></span><span class="n">options</span><span class="o">.</span><span class="n">tracks</span> <span class="o">=</span> <span class="p">[]</span>
<span class="n">options</span><span class="o">.</span><span class="n">tracks</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="nb">int</span><span class="p">(</span><span class="s2">"3"</span><span class="p">))</span>
</code></pre><p><span class="yiyi-st" id="yiyi-423">If, a little later on, <code class="docutils literal"><span class="pre">--tracks=4</span></code> is seen, it does:</span></p><pre><code class="language-python"><span></span><span class="n">options</span><span class="o">.</span><span class="n">tracks</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="nb">int</span><span class="p">(</span><span class="s2">"4"</span><span class="p">))</span>
</code></pre><p><span class="yiyi-st" id="yiyi-424">The <code class="docutils literal"><span class="pre">append</span></code> action calls the <code class="docutils literal"><span class="pre">append</span></code> method on the current value of the option. </span><span class="yiyi-st" id="yiyi-425">This means that any default value specified must have an <code class="docutils literal"><span class="pre">append</span></code> method. </span><span class="yiyi-st" id="yiyi-426">It also means that if the default value is non-empty, the default elements will be present in the parsed value for the option, with any values from the command line appended after those default values:</span></p><pre><code class="language-python"><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--files"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"append"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="p">[</span><span class="s1">'~/.mypkg/defaults'</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">opts</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="s1">'--files'</span><span class="p">,</span> <span class="s1">'overrides.mypkg'</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">opts</span><span class="o">.</span><span class="n">files</span>
<span class="go">['~/.mypkg/defaults', 'overrides.mypkg']</span>
</code></pre></li><li><p class="first"><span class="yiyi-st" id="yiyi-427"><code class="docutils literal"><span class="pre">"append_const"</span></code> [required: <a class="reference internal" href="#optparse.Option.const" title="optparse.Option.const"><code class="xref py py-attr docutils literal"><span class="pre">const</span></code></a>; relevant: <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a>]</span></p><p><span class="yiyi-st" id="yiyi-428">Like <code class="docutils literal"><span class="pre">"store_const"</span></code>, but the value <a class="reference internal" href="#optparse.Option.const" title="optparse.Option.const"><code class="xref py py-attr docutils literal"><span class="pre">const</span></code></a> is appended to <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a>; as with <code class="docutils literal"><span class="pre">"append"</span></code>, <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a> defaults to <code class="docutils literal"><span class="pre">None</span></code>, and an empty list is automatically created the first time the option is encountered.</span></p></li><li><p class="first"><span class="yiyi-st" id="yiyi-429"><code class="docutils literal"><span class="pre">"count"</span></code> [relevant: <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a>]</span></p><p><span class="yiyi-st" id="yiyi-430">Increment the integer stored at <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a>. </span><span class="yiyi-st" id="yiyi-431">If no default value is supplied, <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a> is set to zero before being incremented the first time.</span></p><p><span class="yiyi-st" id="yiyi-432">Example:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-v"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"count"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbosity"</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-433">The first time <code class="docutils literal"><span class="pre">-v</span></code> is seen on the command line, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> does the equivalent of:</span></p><pre><code class="language-python"><span></span><span class="n">options</span><span class="o">.</span><span class="n">verbosity</span> <span class="o">=</span> <span class="mi">0</span>
<span class="n">options</span><span class="o">.</span><span class="n">verbosity</span> <span class="o">+=</span> <span class="mi">1</span>
</code></pre><p><span class="yiyi-st" id="yiyi-434">Every subsequent occurrence of <code class="docutils literal"><span class="pre">-v</span></code> results in</span></p><pre><code class="language-python"><span></span><span class="n">options</span><span class="o">.</span><span class="n">verbosity</span> <span class="o">+=</span> <span class="mi">1</span>
</code></pre></li><li><p class="first"><span class="yiyi-st" id="yiyi-435"><code class="docutils literal"><span class="pre">"callback"</span></code> [required: <a class="reference internal" href="#optparse.Option.callback" title="optparse.Option.callback"><code class="xref py py-attr docutils literal"><span class="pre">callback</span></code></a>; relevant: <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal"><span class="pre">type</span></code></a>, <a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal"><span class="pre">nargs</span></code></a>, <a class="reference internal" href="#optparse.Option.callback_args" title="optparse.Option.callback_args"><code class="xref py py-attr docutils literal"><span class="pre">callback_args</span></code></a>, <a class="reference internal" href="#optparse.Option.callback_kwargs" title="optparse.Option.callback_kwargs"><code class="xref py py-attr docutils literal"><span class="pre">callback_kwargs</span></code></a>]</span></p><p><span class="yiyi-st" id="yiyi-436">Call the function specified by <a class="reference internal" href="#optparse.Option.callback" title="optparse.Option.callback"><code class="xref py py-attr docutils literal"><span class="pre">callback</span></code></a>, which is called as</span></p><pre><code class="language-python"><span></span><span class="n">func</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="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-437">See section <a class="reference internal" href="#optparse-option-callbacks"><span>Option Callbacks</span></a> for more detail.</span></p></li><li><p class="first"><span class="yiyi-st" id="yiyi-438"><code class="docutils literal"><span class="pre">"help"</span></code></span></p><p><span class="yiyi-st" id="yiyi-439">Prints a complete help message for all the options in the current option parser. </span><span class="yiyi-st" id="yiyi-440">The help message is constructed from the <code class="docutils literal"><span class="pre">usage</span></code> string passed to OptionParser’s constructor and the <a class="reference internal" href="#optparse.Option.help" title="optparse.Option.help"><code class="xref py py-attr docutils literal"><span class="pre">help</span></code></a> string passed to every option.</span></p><p><span class="yiyi-st" id="yiyi-441">If no <a class="reference internal" href="#optparse.Option.help" title="optparse.Option.help"><code class="xref py py-attr docutils literal"><span class="pre">help</span></code></a> string is supplied for an option, it will still be listed in the help message. </span><span class="yiyi-st" id="yiyi-442">To omit an option entirely, use the special value <code class="xref py py-data docutils literal"><span class="pre">optparse.SUPPRESS_HELP</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-443"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> automatically adds a <a class="reference internal" href="#optparse.Option.help" title="optparse.Option.help"><code class="xref py py-attr docutils literal"><span class="pre">help</span></code></a> option to all OptionParsers, so you do not normally need to create one.</span></p><p><span class="yiyi-st" id="yiyi-444">Example:</span></p><pre><code class="language-python"><span></span><span class="kn">from</span> <span class="nn">optparse</span> <span class="k">import</span> <span class="n">OptionParser</span><span class="p">,</span> <span class="n">SUPPRESS_HELP</span>
<span class="c1"># usually, a help option is added automatically, but that can</span>
<span class="c1"># be suppressed using the add_help_option argument</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">(</span><span class="n">add_help_option</span><span class="o">=</span><span class="kc">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="s2">"-h"</span><span class="p">,</span> <span class="s2">"--help"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"help"</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="s2">"-v"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s2">"Be moderately verbose"</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="s2">"--file"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"filename"</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s2">"Input file to read data from"</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="s2">"--secret"</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="n">SUPPRESS_HELP</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-445">If <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> sees either <code class="docutils literal"><span class="pre">-h</span></code> or <code class="docutils literal"><span class="pre">--help</span></code> on the command line, it will print something like the following help message to stdout (assuming <code class="docutils literal"><span class="pre">sys.argv[0]</span></code> is <code class="docutils literal"><span class="pre">"foo.py"</span></code>):</span></p><div class="highlight-text"><div class="highlight"><pre><span></span>Usage: foo.py [options]
Options:
-h, --help Show this help message and exit
-v Be moderately verbose
--file=FILENAME Input file to read data from
</pre></div></div><p><span class="yiyi-st" id="yiyi-446">After printing the help message, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> terminates your process with <code class="docutils literal"><span class="pre">sys.exit(0)</span></code>.</span></p></li><li><p class="first"><span class="yiyi-st" id="yiyi-447"><code class="docutils literal"><span class="pre">"version"</span></code></span></p><p><span class="yiyi-st" id="yiyi-448">Prints the version number supplied to the OptionParser to stdout and exits. </span><span class="yiyi-st" id="yiyi-449">The version number is actually formatted and printed by the <code class="docutils literal"><span class="pre">print_version()</span></code> method of OptionParser. </span><span class="yiyi-st" id="yiyi-450">Generally only relevant if the <code class="docutils literal"><span class="pre">version</span></code> argument is supplied to the OptionParser constructor. </span><span class="yiyi-st" id="yiyi-451">As with <a class="reference internal" href="#optparse.Option.help" title="optparse.Option.help"><code class="xref py py-attr docutils literal"><span class="pre">help</span></code></a> options, you will rarely create <code class="docutils literal"><span class="pre">version</span></code> options, since <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> automatically adds them when needed.</span></p></li></ul></div><div class="section" id="standard-option-types"><h3><span class="yiyi-st" id="yiyi-452">36.1.3.6. </span><span class="yiyi-st" id="yiyi-453">Standard option types</span></h3><p><span class="yiyi-st" id="yiyi-454"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> has five built-in option types: <code class="docutils literal"><span class="pre">"string"</span></code>, <code class="docutils literal"><span class="pre">"int"</span></code>, <code class="docutils literal"><span class="pre">"choice"</span></code>, <code class="docutils literal"><span class="pre">"float"</span></code> and <code class="docutils literal"><span class="pre">"complex"</span></code>. </span><span class="yiyi-st" id="yiyi-455">If you need to add new option types, see section <a class="reference internal" href="#optparse-extending-optparse"><span>Extending optparse</span></a>.</span></p><p><span class="yiyi-st" id="yiyi-456">Arguments to string options are not checked or converted in any way: the text on the command line is stored in the destination (or passed to the callback) as-is.</span></p><p><span class="yiyi-st" id="yiyi-457">Integer arguments (type <code class="docutils literal"><span class="pre">"int"</span></code>) are parsed as follows:</span></p><ul class="simple"><li><span class="yiyi-st" id="yiyi-458">if the number starts with <code class="docutils literal"><span class="pre">0x</span></code>, it is parsed as a hexadecimal number</span></li><li><span class="yiyi-st" id="yiyi-459">if the number starts with <code class="docutils literal"><span class="pre">0</span></code>, it is parsed as an octal number</span></li><li><span class="yiyi-st" id="yiyi-460">if the number starts with <code class="docutils literal"><span class="pre">0b</span></code>, it is parsed as a binary number</span></li><li><span class="yiyi-st" id="yiyi-461">otherwise, the number is parsed as a decimal number</span></li></ul><p><span class="yiyi-st" id="yiyi-462">The conversion is done by calling <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-func docutils literal"><span class="pre">int()</span></code></a> with the appropriate base (2, 8, 10, or 16). </span><span class="yiyi-st" id="yiyi-463">If this fails, so will <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a>, although with a more useful error message.</span></p><p><span class="yiyi-st" id="yiyi-464"><code class="docutils literal"><span class="pre">"float"</span></code> and <code class="docutils literal"><span class="pre">"complex"</span></code> option arguments are converted directly with <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-func docutils literal"><span class="pre">float()</span></code></a> and <a class="reference internal" href="functions.html#complex" title="complex"><code class="xref py py-func docutils literal"><span class="pre">complex()</span></code></a>, with similar error-handling.</span></p><p><span class="yiyi-st" id="yiyi-465"><code class="docutils literal"><span class="pre">"choice"</span></code> options are a subtype of <code class="docutils literal"><span class="pre">"string"</span></code> options. </span><span class="yiyi-st" id="yiyi-466">The <a class="reference internal" href="#optparse.Option.choices" title="optparse.Option.choices"><code class="xref py py-attr docutils literal"><span class="pre">choices</span></code></a> option attribute (a sequence of strings) defines the set of allowed option arguments. </span><span class="yiyi-st" id="yiyi-467"><code class="xref py py-func docutils literal"><span class="pre">optparse.check_choice()</span></code> compares user-supplied option arguments against this master list and raises <code class="xref py py-exc docutils literal"><span class="pre">OptionValueError</span></code> if an invalid string is given.</span></p></div><div class="section" id="parsing-arguments"><h3><span class="yiyi-st" id="yiyi-468">36.1.3.7. </span><span class="yiyi-st" id="yiyi-469">Parsing arguments</span></h3><p><span class="yiyi-st" id="yiyi-470">The whole point of creating and populating an OptionParser is to call its <code class="xref py py-meth docutils literal"><span class="pre">parse_args()</span></code> method:</span></p><pre><code class="language-python"><span></span><span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">)</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="n">args</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">values</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-471">where the input parameters are</span></p><dl class="docutils"><dt><span class="yiyi-st" id="yiyi-472"><code class="docutils literal"><span class="pre">args</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-473">the list of arguments to process (default: <code class="docutils literal"><span class="pre">sys.argv[1:]</span></code>)</span></dd><dt><span class="yiyi-st" id="yiyi-474"><code class="docutils literal"><span class="pre">values</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-475">an <code class="xref py py-class docutils literal"><span class="pre">optparse.Values</span></code> object to store option arguments in (default: a new instance of <code class="xref py py-class docutils literal"><span class="pre">Values</span></code>) – if you give an existing object, the option defaults will not be initialized on it</span></dd></dl><p><span class="yiyi-st" id="yiyi-476">and the return values are</span></p><dl class="docutils"><dt><span class="yiyi-st" id="yiyi-477"><code class="docutils literal"><span class="pre">options</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-478">the same object that was passed in as <code class="docutils literal"><span class="pre">values</span></code>, or the optparse.Values instance created by <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a></span></dd><dt><span class="yiyi-st" id="yiyi-479"><code class="docutils literal"><span class="pre">args</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-480">the leftover positional arguments after all options have been processed</span></dd></dl><p><span class="yiyi-st" id="yiyi-481">The most common usage is to supply neither keyword argument. </span><span class="yiyi-st" id="yiyi-482">If you supply <code class="docutils literal"><span class="pre">values</span></code>, it will be modified with repeated <a class="reference internal" href="functions.html#setattr" title="setattr"><code class="xref py py-func docutils literal"><span class="pre">setattr()</span></code></a> calls (roughly one for every option argument stored to an option destination) and returned by <code class="xref py py-meth docutils literal"><span class="pre">parse_args()</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-483">If <code class="xref py py-meth docutils literal"><span class="pre">parse_args()</span></code> encounters any errors in the argument list, it calls the OptionParser’s <code class="xref py py-meth docutils literal"><span class="pre">error()</span></code> method with an appropriate end-user error message. </span><span class="yiyi-st" id="yiyi-484">This ultimately terminates your process with an exit status of 2 (the traditional Unix exit status for command-line errors).</span></p></div><div class="section" id="querying-and-manipulating-your-option-parser"><h3><span class="yiyi-st" id="yiyi-485">36.1.3.8. </span><span class="yiyi-st" id="yiyi-486">Querying and manipulating your option parser</span></h3><p><span class="yiyi-st" id="yiyi-487">The default behavior of the option parser can be customized slightly, and you can also poke around your option parser and see what’s there. </span><span class="yiyi-st" id="yiyi-488">OptionParser provides several methods to help you out:</span></p><dl class="method"><dt id="optparse.OptionParser.disable_interspersed_args"><span class="yiyi-st" id="yiyi-489"> <code class="descclassname">OptionParser.</code><code class="descname">disable_interspersed_args</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-490">Set parsing to stop on the first non-option. </span><span class="yiyi-st" id="yiyi-491">For example, if <code class="docutils literal"><span class="pre">-a</span></code> and <code class="docutils literal"><span class="pre">-b</span></code> are both simple options that take no arguments, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> normally accepts this syntax:</span></p><pre><code class="language-python"><span></span><span class="n">prog</span> <span class="o">-</span><span class="n">a</span> <span class="n">arg1</span> <span class="o">-</span><span class="n">b</span> <span class="n">arg2</span>
</code></pre><p><span class="yiyi-st" id="yiyi-492">and treats it as equivalent to</span></p><pre><code class="language-python"><span></span><span class="n">prog</span> <span class="o">-</span><span class="n">a</span> <span class="o">-</span><span class="n">b</span> <span class="n">arg1</span> <span class="n">arg2</span>
</code></pre><p><span class="yiyi-st" id="yiyi-493">To disable this feature, call <a class="reference internal" href="#optparse.OptionParser.disable_interspersed_args" title="optparse.OptionParser.disable_interspersed_args"><code class="xref py py-meth docutils literal"><span class="pre">disable_interspersed_args()</span></code></a>. </span><span class="yiyi-st" id="yiyi-494">This restores traditional Unix syntax, where option parsing stops with the first non-option argument.</span></p><p><span class="yiyi-st" id="yiyi-495">Use this if you have a command processor which runs another command which has options of its own and you want to make sure these options don’t get confused. </span><span class="yiyi-st" id="yiyi-496">For example, each command might have a different set of options.</span></p></dd></dl><dl class="method"><dt id="optparse.OptionParser.enable_interspersed_args"><span class="yiyi-st" id="yiyi-497"> <code class="descclassname">OptionParser.</code><code class="descname">enable_interspersed_args</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-498">Set parsing to not stop on the first non-option, allowing interspersing switches with command arguments. </span><span class="yiyi-st" id="yiyi-499">This is the default behavior.</span></p></dd></dl><dl class="method"><dt id="optparse.OptionParser.get_option"><span class="yiyi-st" id="yiyi-500"> <code class="descclassname">OptionParser.</code><code class="descname">get_option</code><span class="sig-paren">(</span><em>opt_str</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-501">Returns the Option instance with the option string <em>opt_str</em>, or <code class="docutils literal"><span class="pre">None</span></code> if no options have that option string.</span></p></dd></dl><dl class="method"><dt id="optparse.OptionParser.has_option"><span class="yiyi-st" id="yiyi-502"> <code class="descclassname">OptionParser.</code><code class="descname">has_option</code><span class="sig-paren">(</span><em>opt_str</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-503">Return true if the OptionParser has an option with option string <em>opt_str</em> (e.g., <code class="docutils literal"><span class="pre">-q</span></code> or <code class="docutils literal"><span class="pre">--verbose</span></code>).</span></p></dd></dl><dl class="method"><dt id="optparse.OptionParser.remove_option"><span class="yiyi-st" id="yiyi-504"> <code class="descclassname">OptionParser.</code><code class="descname">remove_option</code><span class="sig-paren">(</span><em>opt_str</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-505">If the <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal"><span class="pre">OptionParser</span></code></a> has an option corresponding to <em>opt_str</em>, that option is removed. </span><span class="yiyi-st" id="yiyi-506">If that option provided any other option strings, all of those option strings become invalid. </span><span class="yiyi-st" id="yiyi-507">If <em>opt_str</em> does not occur in any option belonging to this <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal"><span class="pre">OptionParser</span></code></a>, raises <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal"><span class="pre">ValueError</span></code></a>.</span></p></dd></dl></div><div class="section" id="conflicts-between-options"><h3><span class="yiyi-st" id="yiyi-508">36.1.3.9. </span><span class="yiyi-st" id="yiyi-509">Conflicts between options</span></h3><p><span class="yiyi-st" id="yiyi-510">If you’re not careful, it’s easy to define options with conflicting option strings:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-n"</span><span class="p">,</span> <span class="s2">"--dry-run"</span><span class="p">,</span> <span class="o">...</span><span class="p">)</span>
<span class="o">...</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-n"</span><span class="p">,</span> <span class="s2">"--noisy"</span><span class="p">,</span> <span class="o">...</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-511">(This is particularly true if you’ve defined your own OptionParser subclass with some standard options.)</span></p><p><span class="yiyi-st" id="yiyi-512">Every time you add an option, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> checks for conflicts with existing options. </span><span class="yiyi-st" id="yiyi-513">If it finds any, it invokes the current conflict-handling mechanism. </span><span class="yiyi-st" id="yiyi-514">You can set the conflict-handling mechanism either in the constructor:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">conflict_handler</span><span class="o">=</span><span class="n">handler</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-515">or with a separate call:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">set_conflict_handler</span><span class="p">(</span><span class="n">handler</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-516">The available conflict handlers are:</span></p><span class="yiyi-st" id="yiyi-526"> <blockquote> <div><dl class="docutils"> <dt><code class="docutils literal"><span class="pre">"error"</span></code> (default)</dt> <dd>assume option conflicts are a programming error and raise <code class="xref py py-exc docutils literal"><span class="pre">OptionConflictError</span></code></dd> <dt><code class="docutils literal"><span class="pre">"resolve"</span></code></dt> <dd>resolve option conflicts intelligently (see below)</dd> </dl> </div></blockquote></span><p><span class="yiyi-st" id="yiyi-517">As an example, let’s define an <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal"><span class="pre">OptionParser</span></code></a> that resolves conflicts intelligently and add conflicting options to it:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">(</span><span class="n">conflict_handler</span><span class="o">=</span><span class="s2">"resolve"</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="s2">"-n"</span><span class="p">,</span> <span class="s2">"--dry-run"</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s2">"do no harm"</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="s2">"-n"</span><span class="p">,</span> <span class="s2">"--noisy"</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s2">"be noisy"</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-518">At this point, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> detects that a previously-added option is already using the <code class="docutils literal"><span class="pre">-n</span></code> option string. </span><span class="yiyi-st" id="yiyi-519">Since <code class="docutils literal"><span class="pre">conflict_handler</span></code> is <code class="docutils literal"><span class="pre">"resolve"</span></code>, it resolves the situation by removing <code class="docutils literal"><span class="pre">-n</span></code> from the earlier option’s list of option strings. </span><span class="yiyi-st" id="yiyi-520">Now <code class="docutils literal"><span class="pre">--dry-run</span></code> is the only way for the user to activate that option. </span><span class="yiyi-st" id="yiyi-521">If the user asks for help, the help message will reflect that:</span></p><pre><code class="language-python"><span></span><span class="n">Options</span><span class="p">:</span>
<span class="o">--</span><span class="n">dry</span><span class="o">-</span><span class="n">run</span> <span class="n">do</span> <span class="n">no</span> <span class="n">harm</span>
<span class="o">...</span>
<span class="o">-</span><span class="n">n</span><span class="p">,</span> <span class="o">--</span><span class="n">noisy</span> <span class="n">be</span> <span class="n">noisy</span>
</code></pre><p><span class="yiyi-st" id="yiyi-522">It’s possible to whittle away the option strings for a previously-added option until there are none left, and the user has no way of invoking that option from the command-line. </span><span class="yiyi-st" id="yiyi-523">In that case, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> removes that option completely, so it doesn’t show up in help text or anywhere else. </span><span class="yiyi-st" id="yiyi-524">Carrying on with our existing OptionParser:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--dry-run"</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s2">"new dry-run option"</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-525">At this point, the original <code class="docutils literal"><span class="pre">-n</span></code>/<code class="docutils literal"><span class="pre">--dry-run</span></code> option is no longer accessible, so <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> removes it, leaving this help text:</span></p><pre><code class="language-python"><span></span><span class="n">Options</span><span class="p">:</span>
<span class="o">...</span>
<span class="o">-</span><span class="n">n</span><span class="p">,</span> <span class="o">--</span><span class="n">noisy</span> <span class="n">be</span> <span class="n">noisy</span>
<span class="o">--</span><span class="n">dry</span><span class="o">-</span><span class="n">run</span> <span class="n">new</span> <span class="n">dry</span><span class="o">-</span><span class="n">run</span> <span class="n">option</span>
</code></pre></div><div class="section" id="cleanup"><h3><span class="yiyi-st" id="yiyi-527">36.1.3.10. </span><span class="yiyi-st" id="yiyi-528">Cleanup</span></h3><p><span class="yiyi-st" id="yiyi-529">OptionParser instances have several cyclic references. </span><span class="yiyi-st" id="yiyi-530">This should not be a problem for Python’s garbage collector, but you may wish to break the cyclic references explicitly by calling <code class="xref py py-meth docutils literal"><span class="pre">destroy()</span></code> on your OptionParser once you are done with it. </span><span class="yiyi-st" id="yiyi-531">This is particularly useful in long-running applications where large object graphs are reachable from your OptionParser.</span></p></div><div class="section" id="other-methods"><h3><span class="yiyi-st" id="yiyi-532">36.1.3.11. </span><span class="yiyi-st" id="yiyi-533">Other methods</span></h3><p><span class="yiyi-st" id="yiyi-534">OptionParser supports several other public methods:</span></p><dl class="method"><dt id="optparse.OptionParser.set_usage"><span class="yiyi-st" id="yiyi-535"> <code class="descclassname">OptionParser.</code><code class="descname">set_usage</code><span class="sig-paren">(</span><em>usage</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-536">Set the usage string according to the rules described above for the <code class="docutils literal"><span class="pre">usage</span></code> constructor keyword argument. </span><span class="yiyi-st" id="yiyi-537">Passing <code class="docutils literal"><span class="pre">None</span></code> sets the default usage string; use <code class="xref py py-data docutils literal"><span class="pre">optparse.SUPPRESS_USAGE</span></code> to suppress a usage message.</span></p></dd></dl><dl class="method"><dt id="optparse.OptionParser.print_usage"><span class="yiyi-st" id="yiyi-538"> <code class="descclassname">OptionParser.</code><code class="descname">print_usage</code><span class="sig-paren">(</span><em>file=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-539">Print the usage message for the current program (<code class="docutils literal"><span class="pre">self.usage</span></code>) to <em>file</em> (default stdout). </span><span class="yiyi-st" id="yiyi-540">Any occurrence of the string <code class="docutils literal"><span class="pre">%prog</span></code> in <code class="docutils literal"><span class="pre">self.usage</span></code> is replaced with the name of the current program. </span><span class="yiyi-st" id="yiyi-541">Does nothing if <code class="docutils literal"><span class="pre">self.usage</span></code> is empty or not defined.</span></p></dd></dl><dl class="method"><dt id="optparse.OptionParser.get_usage"><span class="yiyi-st" id="yiyi-542"> <code class="descclassname">OptionParser.</code><code class="descname">get_usage</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-543">Same as <a class="reference internal" href="#optparse.OptionParser.print_usage" title="optparse.OptionParser.print_usage"><code class="xref py py-meth docutils literal"><span class="pre">print_usage()</span></code></a> but returns the usage string instead of printing it.</span></p></dd></dl><dl class="method"><dt id="optparse.OptionParser.set_defaults"><span class="yiyi-st" id="yiyi-544"> <code class="descclassname">OptionParser.</code><code class="descname">set_defaults</code><span class="sig-paren">(</span><em>dest=value</em>, <em>...</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-545">Set default values for several option destinations at once. </span><span class="yiyi-st" id="yiyi-546">Using <a class="reference internal" href="#optparse.OptionParser.set_defaults" title="optparse.OptionParser.set_defaults"><code class="xref py py-meth docutils literal"><span class="pre">set_defaults()</span></code></a> is the preferred way to set default values for options, since multiple options can share the same destination. </span><span class="yiyi-st" id="yiyi-547">For example, if several “mode” options all set the same destination, any one of them can set the default, and the last one wins:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--advanced"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_const"</span><span class="p">,</span>
<span class="n">dest</span><span class="o">=</span><span class="s2">"mode"</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s2">"advanced"</span><span class="p">,</span>
<span class="n">default</span><span class="o">=</span><span class="s2">"novice"</span><span class="p">)</span> <span class="c1"># overridden below</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--novice"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_const"</span><span class="p">,</span>
<span class="n">dest</span><span class="o">=</span><span class="s2">"mode"</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s2">"novice"</span><span class="p">,</span>
<span class="n">default</span><span class="o">=</span><span class="s2">"advanced"</span><span class="p">)</span> <span class="c1"># overrides above setting</span>
</code></pre><p><span class="yiyi-st" id="yiyi-548">To avoid this confusion, use <a class="reference internal" href="#optparse.OptionParser.set_defaults" title="optparse.OptionParser.set_defaults"><code class="xref py py-meth docutils literal"><span class="pre">set_defaults()</span></code></a>:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">set_defaults</span><span class="p">(</span><span class="n">mode</span><span class="o">=</span><span class="s2">"advanced"</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="s2">"--advanced"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_const"</span><span class="p">,</span>
<span class="n">dest</span><span class="o">=</span><span class="s2">"mode"</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s2">"advanced"</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="s2">"--novice"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_const"</span><span class="p">,</span>
<span class="n">dest</span><span class="o">=</span><span class="s2">"mode"</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s2">"novice"</span><span class="p">)</span>
</code></pre></dd></dl></div></div><div class="section" id="option-callbacks"><h2><span class="yiyi-st" id="yiyi-549">36.1.4. </span><span class="yiyi-st" id="yiyi-550">Option Callbacks</span></h2><p><span class="yiyi-st" id="yiyi-551">When <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a>‘s built-in actions and types aren’t quite enough for your needs, you have two choices: extend <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> or define a callback option. </span><span class="yiyi-st" id="yiyi-552">Extending <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> is more general, but overkill for a lot of simple cases. </span><span class="yiyi-st" id="yiyi-553">Quite often a simple callback is all you need.</span></p><p><span class="yiyi-st" id="yiyi-554">There are two steps to defining a callback option:</span></p><ul class="simple"><li><span class="yiyi-st" id="yiyi-555">define the option itself using the <code class="docutils literal"><span class="pre">"callback"</span></code> action</span></li><li><span class="yiyi-st" id="yiyi-556">write the callback; this is a function (or method) that takes at least four arguments, as described below</span></li></ul><div class="section" id="defining-a-callback-option"><h3><span class="yiyi-st" id="yiyi-557">36.1.4.1. </span><span class="yiyi-st" id="yiyi-558">Defining a callback option</span></h3><p><span class="yiyi-st" id="yiyi-559">As always, the easiest way to define a callback option is by using the <a class="reference internal" href="#optparse.OptionParser.add_option" title="optparse.OptionParser.add_option"><code class="xref py py-meth docutils literal"><span class="pre">OptionParser.add_option()</span></code></a> method. </span><span class="yiyi-st" id="yiyi-560">Apart from <a class="reference internal" href="#optparse.Option.action" title="optparse.Option.action"><code class="xref py py-attr docutils literal"><span class="pre">action</span></code></a>, the only option attribute you must specify is <code class="docutils literal"><span class="pre">callback</span></code>, the function to call:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-c"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"callback"</span><span class="p">,</span> <span class="n">callback</span><span class="o">=</span><span class="n">my_callback</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-561"><code class="docutils literal"><span class="pre">callback</span></code> is a function (or other callable object), so you must have already defined <code class="docutils literal"><span class="pre">my_callback()</span></code> when you create this callback option. </span><span class="yiyi-st" id="yiyi-562">In this simple case, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> doesn’t even know if <code class="docutils literal"><span class="pre">-c</span></code> takes any arguments, which usually means that the option takes no arguments—the mere presence of <code class="docutils literal"><span class="pre">-c</span></code> on the command-line is all it needs to know. </span><span class="yiyi-st" id="yiyi-563">In some circumstances, though, you might want your callback to consume an arbitrary number of command-line arguments. </span><span class="yiyi-st" id="yiyi-564">This is where writing callbacks gets tricky; it’s covered later in this section.</span></p><p><span class="yiyi-st" id="yiyi-565"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> always passes four particular arguments to your callback, and it will only pass additional arguments if you specify them via <a class="reference internal" href="#optparse.Option.callback_args" title="optparse.Option.callback_args"><code class="xref py py-attr docutils literal"><span class="pre">callback_args</span></code></a> and <a class="reference internal" href="#optparse.Option.callback_kwargs" title="optparse.Option.callback_kwargs"><code class="xref py py-attr docutils literal"><span class="pre">callback_kwargs</span></code></a>. </span><span class="yiyi-st" id="yiyi-566">Thus, the minimal callback function signature is:</span></p><pre><code class="language-python"><span></span><span class="k">def</span> <span class="nf">my_callback</span><span class="p">(</span><span class="n">option</span><span class="p">,</span> <span class="n">opt</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">parser</span><span class="p">):</span>
</code></pre><p><span class="yiyi-st" id="yiyi-567">The four arguments to a callback are described below.</span></p><p><span class="yiyi-st" id="yiyi-568">There are several other option attributes that you can supply when you define a callback option:</span></p><dl class="docutils"><dt><span class="yiyi-st" id="yiyi-569"><a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal"><span class="pre">type</span></code></a></span></dt><dd><span class="yiyi-st" id="yiyi-570">has its usual meaning: as with the <code class="docutils literal"><span class="pre">"store"</span></code> or <code class="docutils literal"><span class="pre">"append"</span></code> actions, it instructs <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> to consume one argument and convert it to <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal"><span class="pre">type</span></code></a>. </span><span class="yiyi-st" id="yiyi-571">Rather than storing the converted value(s) anywhere, though, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> passes it to your callback function.</span></dd><dt><span class="yiyi-st" id="yiyi-572"><a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal"><span class="pre">nargs</span></code></a></span></dt><dd><span class="yiyi-st" id="yiyi-573">also has its usual meaning: if it is supplied and &gt; 1, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> will consume <a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal"><span class="pre">nargs</span></code></a> arguments, each of which must be convertible to <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal"><span class="pre">type</span></code></a>. </span><span class="yiyi-st" id="yiyi-574">It then passes a tuple of converted values to your callback.</span></dd><dt><span class="yiyi-st" id="yiyi-575"><a class="reference internal" href="#optparse.Option.callback_args" title="optparse.Option.callback_args"><code class="xref py py-attr docutils literal"><span class="pre">callback_args</span></code></a></span></dt><dd><span class="yiyi-st" id="yiyi-576">a tuple of extra positional arguments to pass to the callback</span></dd><dt><span class="yiyi-st" id="yiyi-577"><a class="reference internal" href="#optparse.Option.callback_kwargs" title="optparse.Option.callback_kwargs"><code class="xref py py-attr docutils literal"><span class="pre">callback_kwargs</span></code></a></span></dt><dd><span class="yiyi-st" id="yiyi-578">a dictionary of extra keyword arguments to pass to the callback</span></dd></dl></div><div class="section" id="how-callbacks-are-called"><h3><span class="yiyi-st" id="yiyi-579">36.1.4.2. </span><span class="yiyi-st" id="yiyi-580">How callbacks are called</span></h3><p><span class="yiyi-st" id="yiyi-581">All callbacks are called as follows:</span></p><pre><code class="language-python"><span></span><span class="n">func</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="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-582">where</span></p><dl class="docutils"><dt><span class="yiyi-st" id="yiyi-583"><code class="docutils literal"><span class="pre">option</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-584">is the Option instance that’s calling the callback</span></dd><dt><span class="yiyi-st" id="yiyi-585"><code class="docutils literal"><span class="pre">opt_str</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-586">is the option string seen on the command-line that’s triggering the callback. </span><span class="yiyi-st" id="yiyi-587">(If an abbreviated long option was used, <code class="docutils literal"><span class="pre">opt_str</span></code> will be the full, canonical option string—e.g. </span><span class="yiyi-st" id="yiyi-588">if the user puts <code class="docutils literal"><span class="pre">--foo</span></code> on the command-line as an abbreviation for <code class="docutils literal"><span class="pre">--foobar</span></code>, then <code class="docutils literal"><span class="pre">opt_str</span></code> will be <code class="docutils literal"><span class="pre">"--foobar"</span></code>.)</span></dd><dt><span class="yiyi-st" id="yiyi-589"><code class="docutils literal"><span class="pre">value</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-590">is the argument to this option seen on the command-line. </span><span class="yiyi-st" id="yiyi-591"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> will only expect an argument if <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal"><span class="pre">type</span></code></a> is set; the type of <code class="docutils literal"><span class="pre">value</span></code> will be the type implied by the option’s type. </span><span class="yiyi-st" id="yiyi-592">If <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal"><span class="pre">type</span></code></a> for this option is <code class="docutils literal"><span class="pre">None</span></code> (no argument expected), then <code class="docutils literal"><span class="pre">value</span></code> will be <code class="docutils literal"><span class="pre">None</span></code>. </span><span class="yiyi-st" id="yiyi-593">If <a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal"><span class="pre">nargs</span></code></a> &gt; 1, <code class="docutils literal"><span class="pre">value</span></code> will be a tuple of values of the appropriate type.</span></dd><dt><span class="yiyi-st" id="yiyi-594"><code class="docutils literal"><span class="pre">parser</span></code></span></dt><dd><p class="first"><span class="yiyi-st" id="yiyi-595">is the OptionParser instance driving the whole thing, mainly useful because you can access some other interesting data through its instance attributes:</span></p><dl class="last docutils"><dt><span class="yiyi-st" id="yiyi-596"><code class="docutils literal"><span class="pre">parser.largs</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-597">the current list of leftover arguments, ie. </span><span class="yiyi-st" id="yiyi-598">arguments that have been consumed but are neither options nor option arguments. </span><span class="yiyi-st" id="yiyi-599">Feel free to modify <code class="docutils literal"><span class="pre">parser.largs</span></code>, e.g. </span><span class="yiyi-st" id="yiyi-600">by adding more arguments to it. </span><span class="yiyi-st" id="yiyi-601">(This list will become <code class="docutils literal"><span class="pre">args</span></code>, the second return value of <code class="xref py py-meth docutils literal"><span class="pre">parse_args()</span></code>.)</span></dd><dt><span class="yiyi-st" id="yiyi-602"><code class="docutils literal"><span class="pre">parser.rargs</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-603">the current list of remaining arguments, ie. </span><span class="yiyi-st" id="yiyi-604">with <code class="docutils literal"><span class="pre">opt_str</span></code> and <code class="docutils literal"><span class="pre">value</span></code> (if applicable) removed, and only the arguments following them still there. </span><span class="yiyi-st" id="yiyi-605">Feel free to modify <code class="docutils literal"><span class="pre">parser.rargs</span></code>, e.g. </span><span class="yiyi-st" id="yiyi-606">by consuming more arguments.</span></dd><dt><span class="yiyi-st" id="yiyi-607"><code class="docutils literal"><span class="pre">parser.values</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-608">the object where option values are by default stored (an instance of optparse.OptionValues). </span><span class="yiyi-st" id="yiyi-609">This lets callbacks use the same mechanism as the rest of <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> for storing option values; you don’t need to mess around with globals or closures. </span><span class="yiyi-st" id="yiyi-610">You can also access or modify the value(s) of any options already encountered on the command-line.</span></dd></dl></dd><dt><span class="yiyi-st" id="yiyi-611"><code class="docutils literal"><span class="pre">args</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-612">is a tuple of arbitrary positional arguments supplied via the <a class="reference internal" href="#optparse.Option.callback_args" title="optparse.Option.callback_args"><code class="xref py py-attr docutils literal"><span class="pre">callback_args</span></code></a> option attribute.</span></dd><dt><span class="yiyi-st" id="yiyi-613"><code class="docutils literal"><span class="pre">kwargs</span></code></span></dt><dd><span class="yiyi-st" id="yiyi-614">is a dictionary of arbitrary keyword arguments supplied via <a class="reference internal" href="#optparse.Option.callback_kwargs" title="optparse.Option.callback_kwargs"><code class="xref py py-attr docutils literal"><span class="pre">callback_kwargs</span></code></a>.</span></dd></dl></div><div class="section" id="raising-errors-in-a-callback"><h3><span class="yiyi-st" id="yiyi-615">36.1.4.3. </span><span class="yiyi-st" id="yiyi-616">Raising errors in a callback</span></h3><p><span class="yiyi-st" id="yiyi-617">The callback function should raise <code class="xref py py-exc docutils literal"><span class="pre">OptionValueError</span></code> if there are any problems with the option or its argument(s). </span><span class="yiyi-st" id="yiyi-618"><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> catches this and terminates the program, printing the error message you supply to stderr. </span><span class="yiyi-st" id="yiyi-619">Your message should be clear, concise, accurate, and mention the option at fault. </span><span class="yiyi-st" id="yiyi-620">Otherwise, the user will have a hard time figuring out what he did wrong.</span></p></div><div class="section" id="callback-example-1-trivial-callback"><h3><span class="yiyi-st" id="yiyi-621">36.1.4.4. </span><span class="yiyi-st" id="yiyi-622">Callback example 1: trivial callback</span></h3><p><span class="yiyi-st" id="yiyi-623">Here’s an example of a callback option that takes no arguments, and simply records that the option was seen:</span></p><pre><code class="language-python"><span></span><span class="k">def</span> <span class="nf">record_foo_seen</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="n">parser</span><span class="o">.</span><span class="n">values</span><span class="o">.</span><span class="n">saw_foo</span> <span class="o">=</span> <span class="kc">True</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--foo"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"callback"</span><span class="p">,</span> <span class="n">callback</span><span class="o">=</span><span class="n">record_foo_seen</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-624">Of course, you could do that with the <code class="docutils literal"><span class="pre">"store_true"</span></code> action.</span></p></div><div class="section" id="callback-example-2-check-option-order"><h3><span class="yiyi-st" id="yiyi-625">36.1.4.5. </span><span class="yiyi-st" id="yiyi-626">Callback example 2: check option order</span></h3><p><span class="yiyi-st" id="yiyi-627">Here’s a slightly more interesting example: record the fact that <code class="docutils literal"><span class="pre">-a</span></code> is seen, but blow up if it comes after <code class="docutils literal"><span class="pre">-b</span></code> in the command-line.</span></p><pre><code class="language-python"><span></span><span class="k">def</span> <span class="nf">check_order</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">if</span> <span class="n">parser</span><span class="o">.</span><span class="n">values</span><span class="o">.</span><span class="n">b</span><span class="p">:</span>
<span class="k">raise</span> <span class="n">OptionValueError</span><span class="p">(</span><span class="s2">"can't use -a after -b"</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">values</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="mi">1</span>
<span class="o">...</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-a"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"callback"</span><span class="p">,</span> <span class="n">callback</span><span class="o">=</span><span class="n">check_order</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="s2">"-b"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"b"</span><span class="p">)</span>
</code></pre></div><div class="section" id="callback-example-3-check-option-order-generalized"><h3><span class="yiyi-st" id="yiyi-628">36.1.4.6. </span><span class="yiyi-st" id="yiyi-629">Callback example 3: check option order (generalized)</span></h3><p><span class="yiyi-st" id="yiyi-630">If you want to re-use this callback for several similar options (set a flag, but blow up if <code class="docutils literal"><span class="pre">-b</span></code> has already been seen), it needs a bit of work: the error message and the flag that it sets must be generalized.</span></p><pre><code class="language-python"><span></span><span class="k">def</span> <span class="nf">check_order</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">if</span> <span class="n">parser</span><span class="o">.</span><span class="n">values</span><span class="o">.</span><span class="n">b</span><span class="p">:</span>
<span class="k">raise</span> <span class="n">OptionValueError</span><span class="p">(</span><span class="s2">"can't use </span><span class="si">%s</span><span class="s2"> after -b"</span> <span class="o">%</span> <span class="n">opt_str</span><span class="p">)</span>
<span class="nb">setattr</span><span class="p">(</span><span class="n">parser</span><span class="o">.</span><span class="n">values</span><span class="p">,</span> <span class="n">option</span><span class="o">.</span><span class="n">dest</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
<span class="o">...</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-a"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"callback"</span><span class="p">,</span> <span class="n">callback</span><span class="o">=</span><span class="n">check_order</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">'a'</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="s2">"-b"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"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="s2">"-c"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"callback"</span><span class="p">,</span> <span class="n">callback</span><span class="o">=</span><span class="n">check_order</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">'c'</span><span class="p">)</span>
</code></pre></div><div class="section" id="callback-example-4-check-arbitrary-condition"><h3><span class="yiyi-st" id="yiyi-631">36.1.4.7. </span><span class="yiyi-st" id="yiyi-632">Callback example 4: check arbitrary condition</span></h3><p><span class="yiyi-st" id="yiyi-633">Of course, you could put any condition in there—you’re not limited to checking the values of already-defined options. </span><span class="yiyi-st" id="yiyi-634">For example, if you have options that should not be called when the moon is full, all you have to do is this:</span></p><pre><code class="language-python"><span></span><span class="k">def</span> <span class="nf">check_moon</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">if</span> <span class="n">is_moon_full</span><span class="p">():</span>
<span class="k">raise</span> <span class="n">OptionValueError</span><span class="p">(</span><span class="s2">"</span><span class="si">%s</span><span class="s2"> option invalid when moon is full"</span>
<span class="o">%</span> <span class="n">opt_str</span><span class="p">)</span>
<span class="nb">setattr</span><span class="p">(</span><span class="n">parser</span><span class="o">.</span><span class="n">values</span><span class="p">,</span> <span class="n">option</span><span class="o">.</span><span class="n">dest</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
<span class="o">...</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--foo"</span><span class="p">,</span>
<span class="n">action</span><span class="o">=</span><span class="s2">"callback"</span><span class="p">,</span> <span class="n">callback</span><span class="o">=</span><span class="n">check_moon</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"foo"</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-635">(The definition of <code class="docutils literal"><span class="pre">is_moon_full()</span></code> is left as an exercise for the reader.)</span></p></div><div class="section" id="callback-example-5-fixed-arguments"><h3><span class="yiyi-st" id="yiyi-636">36.1.4.8. </span><span class="yiyi-st" id="yiyi-637">Callback example 5: fixed arguments</span></h3><p><span class="yiyi-st" id="yiyi-638">Things get slightly more interesting when you define callback options that take a fixed number of arguments. </span><span class="yiyi-st" id="yiyi-639">Specifying that a callback option takes arguments is similar to defining a <code class="docutils literal"><span class="pre">"store"</span></code> or <code class="docutils literal"><span class="pre">"append"</span></code> option: if you define <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal"><span class="pre">type</span></code></a>, then the option takes one argument that must be convertible to that type; if you further define <a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal"><span class="pre">nargs</span></code></a>, then the option takes <a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal"><span class="pre">nargs</span></code></a> arguments.</span></p><p><span class="yiyi-st" id="yiyi-640">Here’s an example that just emulates the standard <code class="docutils literal"><span class="pre">"store"</span></code> action:</span></p><pre><code class="language-python"><span></span><span class="k">def</span> <span class="nf">store_value</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="nb">setattr</span><span class="p">(</span><span class="n">parser</span><span class="o">.</span><span class="n">values</span><span class="p">,</span> <span class="n">option</span><span class="o">.</span><span class="n">dest</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>
<span class="o">...</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--foo"</span><span class="p">,</span>
<span class="n">action</span><span class="o">=</span><span class="s2">"callback"</span><span class="p">,</span> <span class="n">callback</span><span class="o">=</span><span class="n">store_value</span><span class="p">,</span>
<span class="nb">type</span><span class="o">=</span><span class="s2">"int"</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"foo"</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-641">Note that <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> takes care of consuming 3 arguments and converting them to integers for you; all you have to do is store them. </span><span class="yiyi-st" id="yiyi-642">(Or whatever; obviously you don’t need a callback for this example.)</span></p></div><div class="section" id="callback-example-6-variable-arguments"><h3><span class="yiyi-st" id="yiyi-643">36.1.4.9. </span><span class="yiyi-st" id="yiyi-644">Callback example 6: variable arguments</span></h3><p><span class="yiyi-st" id="yiyi-645">Things get hairy when you want an option to take a variable number of arguments. </span><span class="yiyi-st" id="yiyi-646">For this case, you must write a callback, as <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> doesn’t provide any built-in capabilities for it. </span><span class="yiyi-st" id="yiyi-647">And you have to deal with certain intricacies of conventional Unix command-line parsing that <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> normally handles for you. </span><span class="yiyi-st" id="yiyi-648">In particular, callbacks should implement the conventional rules for bare <code class="docutils literal"><span class="pre">--</span></code> and <code class="docutils literal"><span class="pre">-</span></code> arguments:</span></p><ul class="simple"><li><span class="yiyi-st" id="yiyi-649">either <code class="docutils literal"><span class="pre">--</span></code> or <code class="docutils literal"><span class="pre">-</span></code> can be option arguments</span></li><li><span class="yiyi-st" id="yiyi-650">bare <code class="docutils literal"><span class="pre">--</span></code> (if not the argument to some option): halt command-line processing and discard the <code class="docutils literal"><span class="pre">--</span></code></span></li><li><span class="yiyi-st" id="yiyi-651">bare <code class="docutils literal"><span class="pre">-</span></code> (if not the argument to some option): halt command-line processing but keep the <code class="docutils literal"><span class="pre">-</span></code> (append it to <code class="docutils literal"><span class="pre">parser.largs</span></code>)</span></li></ul><p><span class="yiyi-st" id="yiyi-652">If you want an option that takes a variable number of arguments, there are several subtle, tricky issues to worry about. </span><span class="yiyi-st" id="yiyi-653">The exact implementation you choose will be based on which trade-offs you’re willing to make for your application (which is why <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> doesn’t support this sort of thing directly).</span></p><p><span class="yiyi-st" id="yiyi-654">Nevertheless, here’s a stab at a callback for an option with variable arguments:</span></p><pre><code class="language-python"><span></span><span class="k">def</span> <span class="nf">vararg_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">assert</span> <span class="n">value</span> <span class="ow">is</span> <span class="kc">None</span>
<span class="n">value</span> <span class="o">=</span> <span class="p">[]</span>
<span class="k">def</span> <span class="nf">floatable</span><span class="p">(</span><span class="nb">str</span><span class="p">):</span>
<span class="k">try</span><span class="p">:</span>
<span class="nb">float</span><span class="p">(</span><span class="nb">str</span><span class="p">)</span>
<span class="k">return</span> <span class="kc">True</span>
<span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
<span class="k">return</span> <span class="kc">False</span>
<span class="k">for</span> <span class="n">arg</span> <span class="ow">in</span> <span class="n">parser</span><span class="o">.</span><span class="n">rargs</span><span class="p">:</span>
<span class="c1"># stop on --foo like options</span>
<span class="k">if</span> <span class="n">arg</span><span class="p">[:</span><span class="mi">2</span><span class="p">]</span> <span class="o">==</span> <span class="s2">"--"</span> <span class="ow">and</span> <span class="nb">len</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">2</span><span class="p">:</span>
<span class="k">break</span>
<span class="c1"># stop on -a, but not on -3 or -3.0</span>
<span class="k">if</span> <span class="n">arg</span><span class="p">[:</span><span class="mi">1</span><span class="p">]</span> <span class="o">==</span> <span class="s2">"-"</span> <span class="ow">and</span> <span class="nb">len</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">1</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">floatable</span><span class="p">(</span><span class="n">arg</span><span class="p">):</span>
<span class="k">break</span>
<span class="n">value</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span>
<span class="k">del</span> <span class="n">parser</span><span class="o">.</span><span class="n">rargs</span><span class="p">[:</span><span class="nb">len</span><span class="p">(</span><span class="n">value</span><span class="p">)]</span>
<span class="nb">setattr</span><span class="p">(</span><span class="n">parser</span><span class="o">.</span><span class="n">values</span><span class="p">,</span> <span class="n">option</span><span class="o">.</span><span class="n">dest</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>
<span class="o">...</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-c"</span><span class="p">,</span> <span class="s2">"--callback"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"vararg_attr"</span><span class="p">,</span>
<span class="n">action</span><span class="o">=</span><span class="s2">"callback"</span><span class="p">,</span> <span class="n">callback</span><span class="o">=</span><span class="n">vararg_callback</span><span class="p">)</span>
</code></pre></div></div><div class="section" id="extending-optparse"><h2><span class="yiyi-st" id="yiyi-655">36.1.5. </span><span class="yiyi-st" id="yiyi-656">Extending <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a></span></h2><p><span class="yiyi-st" id="yiyi-657">Since the two major controlling factors in how <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> interprets command-line options are the action and type of each option, the most likely direction of extension is to add new actions and new types.</span></p><div class="section" id="adding-new-types"><h3><span class="yiyi-st" id="yiyi-658">36.1.5.1. </span><span class="yiyi-st" id="yiyi-659">Adding new types</span></h3><p><span class="yiyi-st" id="yiyi-660">To add new types, you need to define your own subclass of <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a>‘s <code class="xref py py-class docutils literal"><span class="pre">Option</span></code> class. </span><span class="yiyi-st" id="yiyi-661">This class has a couple of attributes that define <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a>‘s types: <a class="reference internal" href="#optparse.Option.TYPES" title="optparse.Option.TYPES"><code class="xref py py-attr docutils literal"><span class="pre">TYPES</span></code></a> and <a class="reference internal" href="#optparse.Option.TYPE_CHECKER" title="optparse.Option.TYPE_CHECKER"><code class="xref py py-attr docutils literal"><span class="pre">TYPE_CHECKER</span></code></a>.</span></p><dl class="attribute"><dt id="optparse.Option.TYPES"><span class="yiyi-st" id="yiyi-662"> <code class="descclassname">Option.</code><code class="descname">TYPES</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-663">A tuple of type names; in your subclass, simply define a new tuple <a class="reference internal" href="#optparse.Option.TYPES" title="optparse.Option.TYPES"><code class="xref py py-attr docutils literal"><span class="pre">TYPES</span></code></a> that builds on the standard one.</span></p></dd></dl><dl class="attribute"><dt id="optparse.Option.TYPE_CHECKER"><span class="yiyi-st" id="yiyi-664"> <code class="descclassname">Option.</code><code class="descname">TYPE_CHECKER</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-665">A dictionary mapping type names to type-checking functions. </span><span class="yiyi-st" id="yiyi-666">A type-checking function has the following signature:</span></p><pre><code class="language-python"><span></span><span class="k">def</span> <span class="nf">check_mytype</span><span class="p">(</span><span class="n">option</span><span class="p">,</span> <span class="n">opt</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-667">where <code class="docutils literal"><span class="pre">option</span></code> is an <code class="xref py py-class docutils literal"><span class="pre">Option</span></code> instance, <code class="docutils literal"><span class="pre">opt</span></code> is an option string (e.g., <code class="docutils literal"><span class="pre">-f</span></code>), and <code class="docutils literal"><span class="pre">value</span></code> is the string from the command line that must be checked and converted to your desired type. </span><span class="yiyi-st" id="yiyi-668"><code class="docutils literal"><span class="pre">check_mytype()</span></code> should return an object of the hypothetical type <code class="docutils literal"><span class="pre">mytype</span></code>. </span><span class="yiyi-st" id="yiyi-669">The value returned by a type-checking function will wind up in the OptionValues instance returned by <code class="xref py py-meth docutils literal"><span class="pre">OptionParser.parse_args()</span></code>, or be passed to a callback as the <code class="docutils literal"><span class="pre">value</span></code> parameter.</span></p><p><span class="yiyi-st" id="yiyi-670">Your type-checking function should raise <code class="xref py py-exc docutils literal"><span class="pre">OptionValueError</span></code> if it encounters any problems. </span><span class="yiyi-st" id="yiyi-671"><code class="xref py py-exc docutils literal"><span class="pre">OptionValueError</span></code> takes a single string argument, which is passed as-is to <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal"><span class="pre">OptionParser</span></code></a>‘s <code class="xref py py-meth docutils literal"><span class="pre">error()</span></code> method, which in turn prepends the program name and the string <code class="docutils literal"><span class="pre">"error:"</span></code> and prints everything to stderr before terminating the process.</span></p></dd></dl><p><span class="yiyi-st" id="yiyi-672">Here’s a silly example that demonstrates adding a <code class="docutils literal"><span class="pre">"complex"</span></code> option type to parse Python-style complex numbers on the command line. </span><span class="yiyi-st" id="yiyi-673">(This is even sillier than it used to be, because <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> 1.3 added built-in support for complex numbers, but never mind.)</span></p><p><span class="yiyi-st" id="yiyi-674">First, the necessary imports:</span></p><pre><code class="language-python"><span></span><span class="kn">from</span> <span class="nn">copy</span> <span class="k">import</span> <span class="n">copy</span>
<span class="kn">from</span> <span class="nn">optparse</span> <span class="k">import</span> <span class="n">Option</span><span class="p">,</span> <span class="n">OptionValueError</span>
</code></pre><p><span class="yiyi-st" id="yiyi-675">You need to define your type-checker first, since it’s referred to later (in the <a class="reference internal" href="#optparse.Option.TYPE_CHECKER" title="optparse.Option.TYPE_CHECKER"><code class="xref py py-attr docutils literal"><span class="pre">TYPE_CHECKER</span></code></a> class attribute of your Option subclass):</span></p><pre><code class="language-python"><span></span><span class="k">def</span> <span class="nf">check_complex</span><span class="p">(</span><span class="n">option</span><span class="p">,</span> <span class="n">opt</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
<span class="k">try</span><span class="p">:</span>
<span class="k">return</span> <span class="nb">complex</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
<span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
<span class="k">raise</span> <span class="n">OptionValueError</span><span class="p">(</span>
<span class="s2">"option </span><span class="si">%s</span><span class="s2">: invalid complex value: </span><span class="si">%r</span><span class="s2">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">opt</span><span class="p">,</span> <span class="n">value</span><span class="p">))</span>
</code></pre><p><span class="yiyi-st" id="yiyi-676">Finally, the Option subclass:</span></p><pre><code class="language-python"><span></span><span class="k">class</span> <span class="nc">MyOption</span> <span class="p">(</span><span class="n">Option</span><span class="p">):</span>
<span class="n">TYPES</span> <span class="o">=</span> <span class="n">Option</span><span class="o">.</span><span class="n">TYPES</span> <span class="o">+</span> <span class="p">(</span><span class="s2">"complex"</span><span class="p">,)</span>
<span class="n">TYPE_CHECKER</span> <span class="o">=</span> <span class="n">copy</span><span class="p">(</span><span class="n">Option</span><span class="o">.</span><span class="n">TYPE_CHECKER</span><span class="p">)</span>
<span class="n">TYPE_CHECKER</span><span class="p">[</span><span class="s2">"complex"</span><span class="p">]</span> <span class="o">=</span> <span class="n">check_complex</span>
</code></pre><p><span class="yiyi-st" id="yiyi-677">(If we didn’t make a <a class="reference internal" href="copy.html#module-copy" title="copy: Shallow and deep copy operations."><code class="xref py py-func docutils literal"><span class="pre">copy()</span></code></a> of <a class="reference internal" href="#optparse.Option.TYPE_CHECKER" title="optparse.Option.TYPE_CHECKER"><code class="xref py py-attr docutils literal"><span class="pre">Option.TYPE_CHECKER</span></code></a>, we would end up modifying the <a class="reference internal" href="#optparse.Option.TYPE_CHECKER" title="optparse.Option.TYPE_CHECKER"><code class="xref py py-attr docutils literal"><span class="pre">TYPE_CHECKER</span></code></a> attribute of <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a>‘s Option class. </span><span class="yiyi-st" id="yiyi-678">This being Python, nothing stops you from doing that except good manners and common sense.)</span></p><p><span class="yiyi-st" id="yiyi-679">That’s it! </span><span class="yiyi-st" id="yiyi-680">Now you can write a script that uses the new option type just like any other <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a>-based script, except you have to instruct your OptionParser to use MyOption instead of Option:</span></p><pre><code class="language-python"><span></span><span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">(</span><span class="n">option_class</span><span class="o">=</span><span class="n">MyOption</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="s2">"-c"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s2">"complex"</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-681">Alternately, you can build your own option list and pass it to OptionParser; if you don’t use <code class="xref py py-meth docutils literal"><span class="pre">add_option()</span></code> in the above way, you don’t need to tell OptionParser which option class to use:</span></p><pre><code class="language-python"><span></span><span class="n">option_list</span> <span class="o">=</span> <span class="p">[</span><span class="n">MyOption</span><span class="p">(</span><span class="s2">"-c"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s2">"complex"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"c"</span><span class="p">)]</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">(</span><span class="n">option_list</span><span class="o">=</span><span class="n">option_list</span><span class="p">)</span>
</code></pre></div><div class="section" id="adding-new-actions"><h3><span class="yiyi-st" id="yiyi-682">36.1.5.2. </span><span class="yiyi-st" id="yiyi-683">Adding new actions</span></h3><p><span class="yiyi-st" id="yiyi-684">Adding new actions is a bit trickier, because you have to understand that <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> has a couple of classifications for actions:</span></p><dl class="docutils"><dt><span class="yiyi-st" id="yiyi-685">“store” actions</span></dt><dd><span class="yiyi-st" id="yiyi-686">actions that result in <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> storing a value to an attribute of the current OptionValues instance; these options require a <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal"><span class="pre">dest</span></code></a> attribute to be supplied to the Option constructor.</span></dd><dt><span class="yiyi-st" id="yiyi-687">“typed” actions</span></dt><dd><span class="yiyi-st" id="yiyi-688">actions that take a value from the command line and expect it to be of a certain type; or rather, a string that can be converted to a certain type. </span><span class="yiyi-st" id="yiyi-689">These options require a <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal"><span class="pre">type</span></code></a> attribute to the Option constructor.</span></dd></dl><p><span class="yiyi-st" id="yiyi-690">These are overlapping sets: some default “store” actions are <code class="docutils literal"><span class="pre">"store"</span></code>, <code class="docutils literal"><span class="pre">"store_const"</span></code>, <code class="docutils literal"><span class="pre">"append"</span></code>, and <code class="docutils literal"><span class="pre">"count"</span></code>, while the default “typed” actions are <code class="docutils literal"><span class="pre">"store"</span></code>, <code class="docutils literal"><span class="pre">"append"</span></code>, and <code class="docutils literal"><span class="pre">"callback"</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-691">When you add an action, you need to categorize it by listing it in at least one of the following class attributes of Option (all are lists of strings):</span></p><dl class="attribute"><dt id="optparse.Option.ACTIONS"><span class="yiyi-st" id="yiyi-692"> <code class="descclassname">Option.</code><code class="descname">ACTIONS</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-693">All actions must be listed in ACTIONS.</span></p></dd></dl><dl class="attribute"><dt id="optparse.Option.STORE_ACTIONS"><span class="yiyi-st" id="yiyi-694"> <code class="descclassname">Option.</code><code class="descname">STORE_ACTIONS</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-695">“store” actions are additionally listed here.</span></p></dd></dl><dl class="attribute"><dt id="optparse.Option.TYPED_ACTIONS"><span class="yiyi-st" id="yiyi-696"> <code class="descclassname">Option.</code><code class="descname">TYPED_ACTIONS</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-697">“typed” actions are additionally listed here.</span></p></dd></dl><dl class="attribute"><dt id="optparse.Option.ALWAYS_TYPED_ACTIONS"><span class="yiyi-st" id="yiyi-698"> <code class="descclassname">Option.</code><code class="descname">ALWAYS_TYPED_ACTIONS</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-699">Actions that always take a type (i.e. </span><span class="yiyi-st" id="yiyi-700">whose options always take a value) are additionally listed here. </span><span class="yiyi-st" id="yiyi-701">The only effect of this is that <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> assigns the default type, <code class="docutils literal"><span class="pre">"string"</span></code>, to options with no explicit type whose action is listed in <a class="reference internal" href="#optparse.Option.ALWAYS_TYPED_ACTIONS" title="optparse.Option.ALWAYS_TYPED_ACTIONS"><code class="xref py py-attr docutils literal"><span class="pre">ALWAYS_TYPED_ACTIONS</span></code></a>.</span></p></dd></dl><p><span class="yiyi-st" id="yiyi-702">In order to actually implement your new action, you must override Option’s <code class="xref py py-meth docutils literal"><span class="pre">take_action()</span></code> method and add a case that recognizes your action.</span></p><p><span class="yiyi-st" id="yiyi-703">For example, let’s add an <code class="docutils literal"><span class="pre">"extend"</span></code> action. </span><span class="yiyi-st" id="yiyi-704">This is similar to the standard <code class="docutils literal"><span class="pre">"append"</span></code> action, but instead of taking a single value from the command-line and appending it to an existing list, <code class="docutils literal"><span class="pre">"extend"</span></code> will take multiple values in a single comma-delimited string, and extend an existing list with them. </span><span class="yiyi-st" id="yiyi-705">That is, if <code class="docutils literal"><span class="pre">--names</span></code> is an <code class="docutils literal"><span class="pre">"extend"</span></code> option of type <code class="docutils literal"><span class="pre">"string"</span></code>, the command line</span></p><pre><code class="language-python"><span></span><span class="o">--</span><span class="n">names</span><span class="o">=</span><span class="n">foo</span><span class="p">,</span><span class="n">bar</span> <span class="o">--</span><span class="n">names</span> <span class="n">blah</span> <span class="o">--</span><span class="n">names</span> <span class="n">ding</span><span class="p">,</span><span class="n">dong</span>
</code></pre><p><span class="yiyi-st" id="yiyi-706">would result in a list</span></p><pre><code class="language-python"><span></span><span class="p">[</span><span class="s2">"foo"</span><span class="p">,</span> <span class="s2">"bar"</span><span class="p">,</span> <span class="s2">"blah"</span><span class="p">,</span> <span class="s2">"ding"</span><span class="p">,</span> <span class="s2">"dong"</span><span class="p">]</span>
</code></pre><p><span class="yiyi-st" id="yiyi-707">Again we define a subclass of Option:</span></p><pre><code class="language-python"><span></span><span class="k">class</span> <span class="nc">MyOption</span><span class="p">(</span><span class="n">Option</span><span class="p">):</span>
<span class="n">ACTIONS</span> <span class="o">=</span> <span class="n">Option</span><span class="o">.</span><span class="n">ACTIONS</span> <span class="o">+</span> <span class="p">(</span><span class="s2">"extend"</span><span class="p">,)</span>
<span class="n">STORE_ACTIONS</span> <span class="o">=</span> <span class="n">Option</span><span class="o">.</span><span class="n">STORE_ACTIONS</span> <span class="o">+</span> <span class="p">(</span><span class="s2">"extend"</span><span class="p">,)</span>
<span class="n">TYPED_ACTIONS</span> <span class="o">=</span> <span class="n">Option</span><span class="o">.</span><span class="n">TYPED_ACTIONS</span> <span class="o">+</span> <span class="p">(</span><span class="s2">"extend"</span><span class="p">,)</span>
<span class="n">ALWAYS_TYPED_ACTIONS</span> <span class="o">=</span> <span class="n">Option</span><span class="o">.</span><span class="n">ALWAYS_TYPED_ACTIONS</span> <span class="o">+</span> <span class="p">(</span><span class="s2">"extend"</span><span class="p">,)</span>
<span class="k">def</span> <span class="nf">take_action</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">action</span><span class="p">,</span> <span class="n">dest</span><span class="p">,</span> <span class="n">opt</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">values</span><span class="p">,</span> <span class="n">parser</span><span class="p">):</span>
<span class="k">if</span> <span class="n">action</span> <span class="o">==</span> <span class="s2">"extend"</span><span class="p">:</span>
<span class="n">lvalue</span> <span class="o">=</span> <span class="n">value</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s2">","</span><span class="p">)</span>
<span class="n">values</span><span class="o">.</span><span class="n">ensure_value</span><span class="p">(</span><span class="n">dest</span><span class="p">,</span> <span class="p">[])</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">lvalue</span><span class="p">)</span>
<span class="k">else</span><span class="p">:</span>
<span class="n">Option</span><span class="o">.</span><span class="n">take_action</span><span class="p">(</span>
<span class="bp">self</span><span class="p">,</span> <span class="n">action</span><span class="p">,</span> <span class="n">dest</span><span class="p">,</span> <span class="n">opt</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">values</span><span class="p">,</span> <span class="n">parser</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-708">Features of note:</span></p><ul><li><p class="first"><span class="yiyi-st" id="yiyi-709"><code class="docutils literal"><span class="pre">"extend"</span></code> both expects a value on the command-line and stores that value somewhere, so it goes in both <a class="reference internal" href="#optparse.Option.STORE_ACTIONS" title="optparse.Option.STORE_ACTIONS"><code class="xref py py-attr docutils literal"><span class="pre">STORE_ACTIONS</span></code></a> and <a class="reference internal" href="#optparse.Option.TYPED_ACTIONS" title="optparse.Option.TYPED_ACTIONS"><code class="xref py py-attr docutils literal"><span class="pre">TYPED_ACTIONS</span></code></a>.</span></p></li><li><p class="first"><span class="yiyi-st" id="yiyi-710">to ensure that <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> assigns the default type of <code class="docutils literal"><span class="pre">"string"</span></code> to <code class="docutils literal"><span class="pre">"extend"</span></code> actions, we put the <code class="docutils literal"><span class="pre">"extend"</span></code> action in <a class="reference internal" href="#optparse.Option.ALWAYS_TYPED_ACTIONS" title="optparse.Option.ALWAYS_TYPED_ACTIONS"><code class="xref py py-attr docutils literal"><span class="pre">ALWAYS_TYPED_ACTIONS</span></code></a> as well.</span></p></li><li><p class="first"><span class="yiyi-st" id="yiyi-711"><code class="xref py py-meth docutils literal"><span class="pre">MyOption.take_action()</span></code> implements just this one new action, and passes control back to <code class="xref py py-meth docutils literal"><span class="pre">Option.take_action()</span></code> for the standard <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal"><span class="pre">optparse</span></code></a> actions.</span></p></li><li><p class="first"><span class="yiyi-st" id="yiyi-712"><code class="docutils literal"><span class="pre">values</span></code> is an instance of the optparse_parser.Values class, which provides the very useful <code class="xref py py-meth docutils literal"><span class="pre">ensure_value()</span></code> method. </span><span class="yiyi-st" id="yiyi-713"><code class="xref py py-meth docutils literal"><span class="pre">ensure_value()</span></code> is essentially <a class="reference internal" href="functions.html#getattr" title="getattr"><code class="xref py py-func docutils literal"><span class="pre">getattr()</span></code></a> with a safety valve; it is called as</span></p><pre><code class="language-python"><span></span><span class="n">values</span><span class="o">.</span><span class="n">ensure_value</span><span class="p">(</span><span class="n">attr</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-714">If the <code class="docutils literal"><span class="pre">attr</span></code> attribute of <code class="docutils literal"><span class="pre">values</span></code> doesn’t exist or is None, then ensure_value() first sets it to <code class="docutils literal"><span class="pre">value</span></code>, and then returns ‘value. </span><span class="yiyi-st" id="yiyi-715">This is very handy for actions like <code class="docutils literal"><span class="pre">"extend"</span></code>, <code class="docutils literal"><span class="pre">"append"</span></code>, and <code class="docutils literal"><span class="pre">"count"</span></code>, all of which accumulate data in a variable and expect that variable to be of a certain type (a list for the first two, an integer for the latter). </span><span class="yiyi-st" id="yiyi-716">Using <code class="xref py py-meth docutils literal"><span class="pre">ensure_value()</span></code> means that scripts using your action don’t have to worry about setting a default value for the option destinations in question; they can just leave the default as None and <code class="xref py py-meth docutils literal"><span class="pre">ensure_value()</span></code> will take care of getting it right when it’s needed.</span></p></li></ul></div></div></div></div>
Reference in New Issue View Git Blame Copy Permalink