mirror of
https://github.com/fofolee/uTools-Manuals.git
synced 2025-06-08 23:14:06 +08:00
365 lines
237 KiB
HTML
365 lines
237 KiB
HTML
<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"><</span><span class="n">yourscript</span><span class="o">></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"><</span><span class="n">yourscript</span><span class="o">></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"><</span><span class="n">yourscript</span><span class="o">></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"><</span><span class="n">yourscript</span><span class="o">></span> <span class="o">-</span><span class="n">q</span> <span class="o">-</span><span class="n">foutfile</span>
|
||
<span class="o"><</span><span class="n">yourscript</span><span class="o">></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"><</span><span class="n">yourscript</span><span class="o">></span> <span class="o">-</span><span class="n">h</span>
|
||
<span class="o"><</span><span class="n">yourscript</span><span class="o">></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: <yourscript> [options]
|
||
|
||
Options:
|
||
-h, --help show this help message and exit
|
||
-f FILE, --file=FILE write report to FILE
|
||
-q, --quiet don't print status messages to stdout
|
||
</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: <yourscript> [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: <yourscript> [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: <yourscript> [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 > 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> > 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> > 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">>>> </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">>>> </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">>>> </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 > 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> > 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">></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">></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> |