parthtamu/rag-code-assistant
0
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4 <head>5 <meta charset="utf-8" />6 <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="optparse — Parser for command line options" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/optparse.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/optparse.py Choosing an argument parsing library: The standard library includes three argument parsing libraries: getopt: a module that closely mirrors the procedural C getopt API...." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_optparse_af18d9d1.png" />15<meta property="og:image:alt" content="Source code: Lib/optparse.py Choosing an argument parsing library: The standard library includes three argument parsing libraries: getopt: a module that closely mirrors the procedural C getopt API...." />16<meta name="description" content="Source code: Lib/optparse.py Choosing an argument parsing library: The standard library includes three argument parsing libraries: getopt: a module that closely mirrors the procedural C getopt API...." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20 <title>optparse — Parser for command line options — Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21 22 <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23 <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24 <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25 <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26 <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27 28 <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29 <script src="../_static/doctools.js?v=9bcbadda"></script>30 <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31 <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32 33 <script src="../_static/sidebar.js"></script>34 35 <link rel="search" type="application/opensearchdescription+xml"36 title="Search within Python 3.15.0a6 documentation"37 href="../_static/opensearch.xml"/>38 <link rel="author" title="About these documents" href="../about.html" />39 <link rel="index" title="Index" href="../genindex.html" />40 <link rel="search" title="Search" href="../search.html" />41 <link rel="copyright" title="Copyright" href="../copyright.html" />42 <link rel="next" title="getpass — Portable password input" href="getpass.html" />43 <link rel="prev" title="Migrating optparse code to argparse" href="../howto/argparse-optparse.html" />44 45 46 <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47 48 <link rel="canonical" href="https://docs.python.org/3/library/optparse.html">49 50 51 52 53 <style>54 @media only screen {55 table.full-width-table {56 width: 100%;57 }58 }59 </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61 <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62 <script type="text/javascript" src="../_static/copybutton.js"></script>63 <script type="text/javascript" src="../_static/menu.js"></script>64 <script type="text/javascript" src="../_static/search-focus.js"></script>65 <script type="text/javascript" src="../_static/themetoggle.js"></script> 66 <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67 <meta name="readthedocs-addons-api-version" content="1">68 69 </head>70<body>71<div class="mobile-nav">72 <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73 aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74 <nav class="nav-content" role="navigation">75 <label for="menuToggler" class="toggler__label">76 <span></span>77 </label>78 <span class="nav-items-wrapper">79 <a href="https://www.python.org/" class="nav-logo">80 <img src="../_static/py.svg" alt="Python logo">81 </a>82 <span class="version_switcher_placeholder"></span>83 <form role="search" class="search" action="../search.html" method="get">84 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85 <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86 </svg>87 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88 <input type="submit" value="Go">89 </form>90 </span>91 </nav>92 <div class="menu-wrapper">93 <nav class="menu" role="navigation" aria-label="main navigation">94 <div class="language_switcher_placeholder"></div>95 96<label class="theme-selector-label">97 Theme98 <select class="theme-selector" oninput="activateTheme(this.value)">99 <option value="auto" selected>Auto</option>100 <option value="light">Light</option>101 <option value="dark">Dark</option>102 </select>103</label>104 <div>105 <h3><a href="../contents.html">Table of Contents</a></h3>106 <ul>107<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> — Parser for command line options</a><ul>108<li><a class="reference internal" href="#choosing-an-argument-parsing-library">Choosing an argument parsing library</a></li>109<li><a class="reference internal" href="#introduction">Introduction</a></li>110<li><a class="reference internal" href="#background">Background</a><ul>111<li><a class="reference internal" href="#terminology">Terminology</a></li>112<li><a class="reference internal" href="#what-are-options-for">What are options for?</a></li>113<li><a class="reference internal" href="#what-are-positional-arguments-for">What are positional arguments for?</a></li>114</ul>115</li>116<li><a class="reference internal" href="#tutorial">Tutorial</a><ul>117<li><a class="reference internal" href="#understanding-option-actions">Understanding option actions</a></li>118<li><a class="reference internal" href="#the-store-action">The store action</a></li>119<li><a class="reference internal" href="#handling-boolean-flag-options">Handling boolean (flag) options</a></li>120<li><a class="reference internal" href="#other-actions">Other actions</a></li>121<li><a class="reference internal" href="#default-values">Default values</a></li>122<li><a class="reference internal" href="#generating-help">Generating help</a><ul>123<li><a class="reference internal" href="#grouping-options">Grouping Options</a></li>124</ul>125</li>126<li><a class="reference internal" href="#printing-a-version-string">Printing a version string</a></li>127<li><a class="reference internal" href="#how-optparse-handles-errors">How <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> handles errors</a></li>128<li><a class="reference internal" href="#putting-it-all-together">Putting it all together</a></li>129</ul>130</li>131<li><a class="reference internal" href="#reference-guide">Reference Guide</a><ul>132<li><a class="reference internal" href="#creating-the-parser">Creating the parser</a></li>133<li><a class="reference internal" href="#populating-the-parser">Populating the parser</a></li>134<li><a class="reference internal" href="#defining-options">Defining options</a></li>135<li><a class="reference internal" href="#option-attributes">Option attributes</a></li>136<li><a class="reference internal" href="#standard-option-actions">Standard option actions</a></li>137<li><a class="reference internal" href="#standard-option-types">Standard option types</a></li>138<li><a class="reference internal" href="#parsing-arguments">Parsing arguments</a></li>139<li><a class="reference internal" href="#querying-and-manipulating-your-option-parser">Querying and manipulating your option parser</a></li>140<li><a class="reference internal" href="#conflicts-between-options">Conflicts between options</a></li>141<li><a class="reference internal" href="#cleanup">Cleanup</a></li>142<li><a class="reference internal" href="#other-methods">Other methods</a></li>143</ul>144</li>145<li><a class="reference internal" href="#option-callbacks">Option Callbacks</a><ul>146<li><a class="reference internal" href="#defining-a-callback-option">Defining a callback option</a></li>147<li><a class="reference internal" href="#how-callbacks-are-called">How callbacks are called</a></li>148<li><a class="reference internal" href="#raising-errors-in-a-callback">Raising errors in a callback</a></li>149<li><a class="reference internal" href="#callback-example-1-trivial-callback">Callback example 1: trivial callback</a></li>150<li><a class="reference internal" href="#callback-example-2-check-option-order">Callback example 2: check option order</a></li>151<li><a class="reference internal" href="#callback-example-3-check-option-order-generalized">Callback example 3: check option order (generalized)</a></li>152<li><a class="reference internal" href="#callback-example-4-check-arbitrary-condition">Callback example 4: check arbitrary condition</a></li>153<li><a class="reference internal" href="#callback-example-5-fixed-arguments">Callback example 5: fixed arguments</a></li>154<li><a class="reference internal" href="#callback-example-6-variable-arguments">Callback example 6: variable arguments</a></li>155</ul>156</li>157<li><a class="reference internal" href="#extending-optparse">Extending <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a><ul>158<li><a class="reference internal" href="#adding-new-types">Adding new types</a></li>159<li><a class="reference internal" href="#adding-new-actions">Adding new actions</a></li>160</ul>161</li>162<li><a class="reference internal" href="#exceptions">Exceptions</a></li>163</ul>164</li>165</ul>166 167 </div>168 <div>169 <h4>Previous topic</h4>170 <p class="topless"><a href="../howto/argparse-optparse.html"171 title="previous chapter">Migrating <code class="docutils literal notranslate"><span class="pre">optparse</span></code> code to <code class="docutils literal notranslate"><span class="pre">argparse</span></code></a></p>172 </div>173 <div>174 <h4>Next topic</h4>175 <p class="topless"><a href="getpass.html"176 title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">getpass</span></code> — Portable password input</a></p>177 </div>178 <script>179 document.addEventListener('DOMContentLoaded', () => {180 const title = document.querySelector('meta[property="og:title"]').content;181 const elements = document.querySelectorAll('.improvepage');182 const pageurl = window.location.href.split('?')[0];183 elements.forEach(element => {184 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));185 url.searchParams.set('pagetitle', title);186 url.searchParams.set('pageurl', pageurl);187 url.searchParams.set('pagesource', "library/optparse.rst");188 element.href = url.toString();189 });190 });191 </script>192 <div role="note" aria-label="source link">193 <h3>This page</h3>194 <ul class="this-page-menu">195 <li><a href="../bugs.html">Report a bug</a></li>196 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>197 <li>198 <a href="https://github.com/python/cpython/blob/main/Doc/library/optparse.rst?plain=1"199 rel="nofollow">Show source200 </a>201 </li>202 203 </ul>204 </div>205 </nav>206 </div>207</div>208 209 210 <div class="related" role="navigation" aria-label="Related">211 <h3>Navigation</h3>212 <ul>213 <li class="right" style="margin-right: 10px">214 <a href="../genindex.html" title="General Index"215 accesskey="I">index</a></li>216 <li class="right" >217 <a href="../py-modindex.html" title="Python Module Index"218 >modules</a> |</li>219 <li class="right" >220 <a href="getpass.html" title="getpass — Portable password input"221 accesskey="N">next</a> |</li>222 <li class="right" >223 <a href="../howto/argparse-optparse.html" title="Migrating optparse code to argparse"224 accesskey="P">previous</a> |</li>225 226 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>227 <li><a href="https://www.python.org/">Python</a> »</li>228 <li class="switchers">229 <div class="language_switcher_placeholder"></div>230 <div class="version_switcher_placeholder"></div>231 </li>232 <li>233 234 </li>235 <li id="cpython-language-and-version">236 <a href="../index.html">3.15.0a6 Documentation</a> »237 </li>238 239 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>240 <li class="nav-item nav-item-2"><a href="cmdlinelibs.html" accesskey="U">Command-line interface libraries</a> »</li>241 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> — Parser for command line options</a></li>242 <li class="right">243 244 245 <div class="inline-search" role="search">246 <form class="inline-search" action="../search.html" method="get">247 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">248 <input type="submit" value="Go">249 </form>250 </div>251 |252 </li>253 <li class="right">254<label class="theme-selector-label">255 Theme256 <select class="theme-selector" oninput="activateTheme(this.value)">257 <option value="auto" selected>Auto</option>258 <option value="light">Light</option>259 <option value="dark">Dark</option>260 </select>261</label> |</li>262 263 </ul>264 </div> 265 266 <div class="document">267 <div class="documentwrapper">268 <div class="bodywrapper">269 <div class="body" role="main">270 271 <section id="module-optparse">272<span id="optparse-parser-for-command-line-options"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> — Parser for command line options<a class="headerlink" href="#module-optparse" title="Link to this heading">¶</a></h1>273<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/optparse.py">Lib/optparse.py</a></p>274<hr class="docutils" />275<section id="choosing-an-argument-parsing-library">276<span id="choosing-an-argument-parser"></span><h2>Choosing an argument parsing library<a class="headerlink" href="#choosing-an-argument-parsing-library" title="Link to this heading">¶</a></h2>277<p>The standard library includes three argument parsing libraries:</p>278<ul class="simple">279<li><p><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 notranslate"><span class="pre">getopt</span></code></a>: a module that closely mirrors the procedural C <code class="docutils literal notranslate"><span class="pre">getopt</span></code> API.280Included in the standard library since before the initial Python 1.0 release.</p></li>281<li><p><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code>: a declarative replacement for <code class="docutils literal notranslate"><span class="pre">getopt</span></code> that282provides equivalent functionality without requiring each application283to implement its own procedural option parsing logic. Included284in the standard library since the Python 2.3 release.</p></li>285<li><p><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 notranslate"><span class="pre">argparse</span></code></a>: a more opinionated alternative to <code class="docutils literal notranslate"><span class="pre">optparse</span></code> that286provides more functionality by default, at the expense of reduced application287flexibility in controlling exactly how arguments are processed. Included in288the standard library since the Python 2.7 and Python 3.2 releases.</p></li>289</ul>290<p>In the absence of more specific argument parsing design constraints, <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 notranslate"><span class="pre">argparse</span></code></a>291is the recommended choice for implementing command line applications, as it offers292the highest level of baseline functionality with the least application level code.</p>293<p><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 notranslate"><span class="pre">getopt</span></code></a> is retained almost entirely for backwards compatibility reasons.294However, it also serves a niche use case as a tool for prototyping and testing295command line argument handling in <code class="docutils literal notranslate"><span class="pre">getopt</span></code>-based C applications.</p>296<p><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> should be considered as an alternative to <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 notranslate"><span class="pre">argparse</span></code></a> in the297following cases:</p>298<ul class="simple">299<li><p>an application is already using <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> and doesn’t want to risk the300subtle behavioural changes that may arise when migrating to <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 notranslate"><span class="pre">argparse</span></code></a></p></li>301<li><p>the application requires additional control over the way options and302positional parameters are interleaved on the command line (including303the ability to disable the interleaving feature completely)</p></li>304<li><p>the application requires additional control over the incremental parsing305of command line elements (while <code class="docutils literal notranslate"><span class="pre">argparse</span></code> does support this, the306exact way it works in practice is undesirable for some use cases)</p></li>307<li><p>the application requires additional control over the handling of options308which accept parameter values that may start with <code class="docutils literal notranslate"><span class="pre">-</span></code> (such as delegated309options to be passed to invoked subprocesses)</p></li>310<li><p>the application requires some other command line parameter processing311behavior which <code class="docutils literal notranslate"><span class="pre">argparse</span></code> does not support, but which can be implemented312in terms of the lower level interface offered by <code class="docutils literal notranslate"><span class="pre">optparse</span></code></p></li>313</ul>314<p>These considerations also mean that <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> is likely to provide a315better foundation for library authors writing third party command line316argument processing libraries.</p>317<p>As a concrete example, consider the following two command line argument318parsing configurations, the first using <code class="docutils literal notranslate"><span class="pre">optparse</span></code>, and the second319using <code class="docutils literal notranslate"><span class="pre">argparse</span></code>:</p>320<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">optparse</span>321 322<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">'__main__'</span><span class="p">:</span>323 <span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">()</span>324 <span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s1">'-o'</span><span class="p">,</span> <span class="s1">'--output'</span><span class="p">)</span>325 <span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s1">'-v'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">'verbose'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_true'</span><span class="p">)</span>326 <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>327 <span class="n">process</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="n">output</span><span class="o">=</span><span class="n">opts</span><span class="o">.</span><span class="n">output</span><span class="p">,</span> <span class="n">verbose</span><span class="o">=</span><span class="n">opts</span><span class="o">.</span><span class="n">verbose</span><span class="p">)</span>328</pre></div>329</div>330<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">argparse</span>331 332<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">'__main__'</span><span class="p">:</span>333 <span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">()</span>334 <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-o'</span><span class="p">,</span> <span class="s1">'--output'</span><span class="p">)</span>335 <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-v'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">'verbose'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_true'</span><span class="p">)</span>336 <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'rest'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'*'</span><span class="p">)</span>337 <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>338 <span class="n">process</span><span class="p">(</span><span class="n">args</span><span class="o">.</span><span class="n">rest</span><span class="p">,</span> <span class="n">output</span><span class="o">=</span><span class="n">args</span><span class="o">.</span><span class="n">output</span><span class="p">,</span> <span class="n">verbose</span><span class="o">=</span><span class="n">args</span><span class="o">.</span><span class="n">verbose</span><span class="p">)</span>339</pre></div>340</div>341<p>The most obvious difference is that in the <code class="docutils literal notranslate"><span class="pre">optparse</span></code> version, the non-option342arguments are processed separately by the application after the option processing343is complete. In the <code class="docutils literal notranslate"><span class="pre">argparse</span></code> version, positional arguments are declared and344processed in the same way as the named options.</p>345<p>However, the <code class="docutils literal notranslate"><span class="pre">argparse</span></code> version will also handle some parameter combination346differently from the way the <code class="docutils literal notranslate"><span class="pre">optparse</span></code> version would handle them.347For example (amongst other differences):</p>348<ul class="simple">349<li><p>supplying <code class="docutils literal notranslate"><span class="pre">-o</span> <span class="pre">-v</span></code> gives <code class="docutils literal notranslate"><span class="pre">output="-v"</span></code> and <code class="docutils literal notranslate"><span class="pre">verbose=False</span></code>350when using <code class="docutils literal notranslate"><span class="pre">optparse</span></code>, but a usage error with <code class="docutils literal notranslate"><span class="pre">argparse</span></code>351(complaining that no value has been supplied for <code class="docutils literal notranslate"><span class="pre">-o/--output</span></code>,352since <code class="docutils literal notranslate"><span class="pre">-v</span></code> is interpreted as meaning the verbosity flag)</p></li>353<li><p>similarly, supplying <code class="docutils literal notranslate"><span class="pre">-o</span> <span class="pre">--</span></code> gives <code class="docutils literal notranslate"><span class="pre">output="--"</span></code> and <code class="docutils literal notranslate"><span class="pre">args=()</span></code>354when using <code class="docutils literal notranslate"><span class="pre">optparse</span></code>, but a usage error with <code class="docutils literal notranslate"><span class="pre">argparse</span></code>355(also complaining that no value has been supplied for <code class="docutils literal notranslate"><span class="pre">-o/--output</span></code>,356since <code class="docutils literal notranslate"><span class="pre">--</span></code> is interpreted as terminating the option processing357and treating all remaining values as positional arguments)</p></li>358<li><p>supplying <code class="docutils literal notranslate"><span class="pre">-o=foo</span></code> gives <code class="docutils literal notranslate"><span class="pre">output="=foo"</span></code> when using <code class="docutils literal notranslate"><span class="pre">optparse</span></code>,359but gives <code class="docutils literal notranslate"><span class="pre">output="foo"</span></code> with <code class="docutils literal notranslate"><span class="pre">argparse</span></code> (since <code class="docutils literal notranslate"><span class="pre">=</span></code> is special360cased as an alternative separator for option parameter values)</p></li>361</ul>362<p>Whether these differing behaviors in the <code class="docutils literal notranslate"><span class="pre">argparse</span></code> version are363considered desirable or a problem will depend on the specific command line364application use case.</p>365<div class="admonition seealso">366<p class="admonition-title">See also</p>367<p><a class="extlink-pypi reference external" href="https://pypi.org/project/click/">click</a> is a third party argument processing library (originally368based on <code class="docutils literal notranslate"><span class="pre">optparse</span></code>), which allows command line applications to be369developed as a set of decorated command implementation functions.</p>370<p>Other third party libraries, such as <a class="extlink-pypi reference external" href="https://pypi.org/project/typer/">typer</a> or <a class="extlink-pypi reference external" href="https://pypi.org/project/msgspec-click/">msgspec-click</a>,371allow command line interfaces to be specified in ways that more effectively372integrate with static checking of Python type annotations.</p>373</div>374</section>375<section id="introduction">376<h2>Introduction<a class="headerlink" href="#introduction" title="Link to this heading">¶</a></h2>377<p><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> is a more convenient, flexible, and powerful library for parsing378command-line options than the minimalist <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 notranslate"><span class="pre">getopt</span></code></a> module.379<code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> uses a more declarative style of command-line parsing:380you create an instance of <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionParser</span></code></a>,381populate it with options, and parse the command line.382<code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> allows users to specify options in the conventional383GNU/POSIX syntax, and additionally generates usage and help messages for you.</p>384<p>Here’s an example of using <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> in a simple script:</p>385<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">optparse</span><span class="w"> </span><span class="kn">import</span> <span class="n">OptionParser</span>386<span class="o">...</span>387<span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">()</span>388<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>389 <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>390<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>391 <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>392 <span class="n">help</span><span class="o">=</span><span class="s2">"don't print status messages to stdout"</span><span class="p">)</span>393 394<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>395</pre></div>396</div>397<p>With these few lines of code, users of your script can now do the “usual thing”398on the command-line, for example:</p>399<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>400</pre></div>401</div>402<p>As it parses the command line, <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> sets attributes of the403<code class="docutils literal notranslate"><span class="pre">options</span></code> object returned by <a class="reference internal" href="#optparse.OptionParser.parse_args" title="optparse.OptionParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> based on user-supplied404command-line values. When <code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code> returns from parsing this command405line, <code class="docutils literal notranslate"><span class="pre">options.filename</span></code> will be <code class="docutils literal notranslate"><span class="pre">"outfile"</span></code> and <code class="docutils literal notranslate"><span class="pre">options.verbose</span></code> will be406<code class="docutils literal notranslate"><span class="pre">False</span></code>. <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> supports both long and short options, allows short407options to be merged together, and allows options to be associated with their408arguments in a variety of ways. Thus, the following command lines are all409equivalent to the above example:</p>410<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>411<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>412<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>413<span class="o"><</span><span class="n">yourscript</span><span class="o">></span> <span class="o">-</span><span class="n">qfoutfile</span>414</pre></div>415</div>416<p>Additionally, users can run one of the following</p>417<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">yourscript</span><span class="o">></span> <span class="o">-</span><span class="n">h</span>418<span class="o"><</span><span class="n">yourscript</span><span class="o">></span> <span class="o">--</span><span class="n">help</span>419</pre></div>420</div>421<p>and <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> will print out a brief summary of your script’s options:</p>422<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Usage: <yourscript> [options]423 424Options:425 -h, --help show this help message and exit426 -f FILE, --file=FILE write report to FILE427 -q, --quiet don't print status messages to stdout428</pre></div>429</div>430<p>where the value of <em>yourscript</em> is determined at runtime (normally from431<code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code>).</p>432</section>433<section id="background">434<span id="optparse-background"></span><h2>Background<a class="headerlink" href="#background" title="Link to this heading">¶</a></h2>435<p><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> was explicitly designed to encourage the creation of programs436with straightforward command-line interfaces that follow the conventions437established by the <code class="xref c c-func docutils literal notranslate"><span class="pre">getopt()</span></code> family of functions available to C developers.438To that end, it supports only the most common command-line syntax and semantics439conventionally used under Unix. If you are unfamiliar with these conventions,440reading this section will allow you to acquaint yourself with them.</p>441<section id="terminology">442<span id="optparse-terminology"></span><h3>Terminology<a class="headerlink" href="#terminology" title="Link to this heading">¶</a></h3>443<dl>444<dt>argument</dt><dd><p>a string entered on the command-line, and passed by the shell to <code class="docutils literal notranslate"><span class="pre">execl()</span></code>445or <code class="docutils literal notranslate"><span class="pre">execv()</span></code>. In Python, arguments are elements of <code class="docutils literal notranslate"><span class="pre">sys.argv[1:]</span></code>446(<code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code> is the name of the program being executed). Unix shells447also use the term “word”.</p>448<p>It is occasionally desirable to substitute an argument list other than449<code class="docutils literal notranslate"><span class="pre">sys.argv[1:]</span></code>, so you should read “argument” as “an element of450<code class="docutils literal notranslate"><span class="pre">sys.argv[1:]</span></code>, or of some other list provided as a substitute for451<code class="docutils literal notranslate"><span class="pre">sys.argv[1:]</span></code>”.</p>452</dd>453<dt>option</dt><dd><p>an argument used to supply extra information to guide or customize the454execution of a program. There are many different syntaxes for options; the455traditional Unix syntax is a hyphen (“-”) followed by a single letter,456e.g. <code class="docutils literal notranslate"><span class="pre">-x</span></code> or <code class="docutils literal notranslate"><span class="pre">-F</span></code>. Also, traditional Unix syntax allows multiple457options to be merged into a single argument, e.g. <code class="docutils literal notranslate"><span class="pre">-x</span> <span class="pre">-F</span></code> is equivalent458to <code class="docutils literal notranslate"><span class="pre">-xF</span></code>. The GNU project introduced <code class="docutils literal notranslate"><span class="pre">--</span></code> followed by a series of459hyphen-separated words, e.g. <code class="docutils literal notranslate"><span class="pre">--file</span></code> or <code class="docutils literal notranslate"><span class="pre">--dry-run</span></code>. These are the460only two option syntaxes provided by <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code>.</p>461<p>Some other option syntaxes that the world has seen include:</p>462<ul class="simple">463<li><p>a hyphen followed by a few letters, e.g. <code class="docutils literal notranslate"><span class="pre">-pf</span></code> (this is <em>not</em> the same464as multiple options merged into a single argument)</p></li>465<li><p>a hyphen followed by a whole word, e.g. <code class="docutils literal notranslate"><span class="pre">-file</span></code> (this is technically466equivalent to the previous syntax, but they aren’t usually seen in the same467program)</p></li>468<li><p>a plus sign followed by a single letter, or a few letters, or a word, e.g.469<code class="docutils literal notranslate"><span class="pre">+f</span></code>, <code class="docutils literal notranslate"><span class="pre">+rgb</span></code></p></li>470<li><p>a slash followed by a letter, or a few letters, or a word, e.g. <code class="docutils literal notranslate"><span class="pre">/f</span></code>,471<code class="docutils literal notranslate"><span class="pre">/file</span></code></p></li>472</ul>473<p>These option syntaxes are not supported by <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code>, and they never474will be. This is deliberate: the first three are non-standard on any475environment, and the last only makes sense if you’re exclusively targeting476Windows or certain legacy platforms (e.g. VMS, MS-DOS).</p>477</dd>478<dt>option argument</dt><dd><p>an argument that follows an option, is closely associated with that option,479and is consumed from the argument list when that option is. With480<code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code>, option arguments may either be in a separate argument from481their option:</p>482<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>-f foo483--file foo484</pre></div>485</div>486<p>or included in the same argument:</p>487<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>-ffoo488--file=foo489</pre></div>490</div>491<p>Typically, a given option either takes an argument or it doesn’t. Lots of492people want an “optional option arguments” feature, meaning that some options493will take an argument if they see it, and won’t if they don’t. This is494somewhat controversial, because it makes parsing ambiguous: if <code class="docutils literal notranslate"><span class="pre">-a</span></code> takes495an optional argument and <code class="docutils literal notranslate"><span class="pre">-b</span></code> is another option entirely, how do we496interpret <code class="docutils literal notranslate"><span class="pre">-ab</span></code>? Because of this ambiguity, <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> does not497support this feature.</p>498</dd>499<dt>positional argument</dt><dd><p>something leftover in the argument list after options have been parsed, i.e.500after options and their arguments have been parsed and removed from the501argument list.</p>502</dd>503<dt>required option</dt><dd><p>an option that must be supplied on the command-line; note that the phrase504“required option” is self-contradictory in English. <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> doesn’t505prevent you from implementing required options, but doesn’t give you much506help at it either.</p>507</dd>508</dl>509<p>For example, consider this hypothetical command-line:</p>510<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>511</pre></div>512</div>513<p><code class="docutils literal notranslate"><span class="pre">-v</span></code> and <code class="docutils literal notranslate"><span class="pre">--report</span></code> are both options. Assuming that <code class="docutils literal notranslate"><span class="pre">--report</span></code>514takes one argument, <code class="docutils literal notranslate"><span class="pre">report.txt</span></code> is an option argument. <code class="docutils literal notranslate"><span class="pre">foo</span></code> and515<code class="docutils literal notranslate"><span class="pre">bar</span></code> are positional arguments.</p>516</section>517<section id="what-are-options-for">518<span id="optparse-what-options-for"></span><h3>What are options for?<a class="headerlink" href="#what-are-options-for" title="Link to this heading">¶</a></h3>519<p>Options are used to provide extra information to tune or customize the execution520of a program. In case it wasn’t clear, options are usually <em>optional</em>. A521program should be able to run just fine with no options whatsoever. (Pick a522random program from the Unix or GNU toolsets. Can it run without any options at523all and still make sense? The main exceptions are <code class="docutils literal notranslate"><span class="pre">find</span></code>, <code class="docutils literal notranslate"><span class="pre">tar</span></code>, and524<code class="docutils literal notranslate"><span class="pre">dd</span></code>—all of which are mutant oddballs that have been rightly criticized525for their non-standard syntax and confusing interfaces.)</p>526<p>Lots of people want their programs to have “required options”. Think about it.527If it’s required, then it’s <em>not optional</em>! If there is a piece of information528that your program absolutely requires in order to run successfully, that’s what529positional arguments are for.</p>530<p>As an example of good command-line interface design, consider the humble <code class="docutils literal notranslate"><span class="pre">cp</span></code>531utility, for copying files. It doesn’t make much sense to try to copy files532without supplying a destination and at least one source. Hence, <code class="docutils literal notranslate"><span class="pre">cp</span></code> fails if533you run it with no arguments. However, it has a flexible, useful syntax that534does not require any options at all:</p>535<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">cp</span> <span class="n">SOURCE</span> <span class="n">DEST</span>536<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>537</pre></div>538</div>539<p>You can get pretty far with just that. Most <code class="docutils literal notranslate"><span class="pre">cp</span></code> implementations provide a540bunch of options to tweak exactly how the files are copied: you can preserve541mode and modification time, avoid following symlinks, ask before clobbering542existing files, etc. But none of this distracts from the core mission of543<code class="docutils literal notranslate"><span class="pre">cp</span></code>, which is to copy either one file to another, or several files to another544directory.</p>545</section>546<section id="what-are-positional-arguments-for">547<span id="optparse-what-positional-arguments-for"></span><h3>What are positional arguments for?<a class="headerlink" href="#what-are-positional-arguments-for" title="Link to this heading">¶</a></h3>548<p>Positional arguments are for those pieces of information that your program549absolutely, positively requires to run.</p>550<p>A good user interface should have as few absolute requirements as possible. If551your program requires 17 distinct pieces of information in order to run552successfully, it doesn’t much matter <em>how</em> you get that information from the553user—most people will give up and walk away before they successfully run the554program. This applies whether the user interface is a command-line, a555configuration file, or a GUI: if you make that many demands on your users, most556of them will simply give up.</p>557<p>In short, try to minimize the amount of information that users are absolutely558required to supply—use sensible defaults whenever possible. Of course, you559also want to make your programs reasonably flexible. That’s what options are560for. Again, it doesn’t matter if they are entries in a config file, widgets in561the “Preferences” dialog of a GUI, or command-line options—the more options562you implement, the more flexible your program is, and the more complicated its563implementation becomes. Too much flexibility has drawbacks as well, of course;564too many options can overwhelm users and make your code much harder to maintain.</p>565</section>566</section>567<section id="tutorial">568<span id="optparse-tutorial"></span><h2>Tutorial<a class="headerlink" href="#tutorial" title="Link to this heading">¶</a></h2>569<p>While <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> is quite flexible and powerful, it’s also straightforward570to use in most cases. This section covers the code patterns that are common to571any <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code>-based program.</p>572<p>First, you need to import the OptionParser class; then, early in the main573program, create an OptionParser instance:</p>574<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">optparse</span><span class="w"> </span><span class="kn">import</span> <span class="n">OptionParser</span>575<span class="o">...</span>576<span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">()</span>577</pre></div>578</div>579<p>Then you can start defining options. The basic syntax is:</p>580<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>581 <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>582</pre></div>583</div>584<p>Each option has one or more option strings, such as <code class="docutils literal notranslate"><span class="pre">-f</span></code> or <code class="docutils literal notranslate"><span class="pre">--file</span></code>,585and several option attributes that tell <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> what to expect and what586to do when it encounters that option on the command line.</p>587<p>Typically, each option will have one short option string and one long option588string, e.g.:</p>589<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>590</pre></div>591</div>592<p>You’re free to define as many short option strings and as many long option593strings as you like (including zero), as long as there is at least one option594string overall.</p>595<p>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 notranslate"><span class="pre">OptionParser.add_option()</span></code></a> are effectively596labels for the597option defined by that call. For brevity, we will frequently refer to598<em>encountering an option</em> on the command line; in reality, <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code>599encounters <em>option strings</em> and looks up options from them.</p>600<p>Once all of your options are defined, instruct <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> to parse your601program’s command line:</p>602<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>603</pre></div>604</div>605<p>(If you like, you can pass a custom argument list to <a class="reference internal" href="#optparse.OptionParser.parse_args" title="optparse.OptionParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a>, but606that’s rarely necessary: by default it uses <code class="docutils literal notranslate"><span class="pre">sys.argv[1:]</span></code>.)</p>607<p><a class="reference internal" href="#optparse.OptionParser.parse_args" title="optparse.OptionParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> returns two values:</p>608<ul class="simple">609<li><p><code class="docutils literal notranslate"><span class="pre">options</span></code>, an object containing values for all of your options—e.g. if610<code class="docutils literal notranslate"><span class="pre">--file</span></code> takes a single string argument, then <code class="docutils literal notranslate"><span class="pre">options.file</span></code> will be the611filename supplied by the user, or <code class="docutils literal notranslate"><span class="pre">None</span></code> if the user did not supply that612option</p></li>613<li><p><code class="docutils literal notranslate"><span class="pre">args</span></code>, the list of positional arguments leftover after parsing options</p></li>614</ul>615<p>This tutorial section only covers the four most important option attributes:616<a class="reference internal" href="#optparse.Option.action" title="optparse.Option.action"><code class="xref py py-attr docutils literal notranslate"><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 notranslate"><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 notranslate"><span class="pre">dest</span></code></a>617(destination), and <a class="reference internal" href="#optparse.Option.help" title="optparse.Option.help"><code class="xref py py-attr docutils literal notranslate"><span class="pre">help</span></code></a>. Of these, <code class="xref py py-attr docutils literal notranslate"><span class="pre">action</span></code> is the618most fundamental.</p>619<section id="understanding-option-actions">620<span id="optparse-understanding-option-actions"></span><h3>Understanding option actions<a class="headerlink" href="#understanding-option-actions" title="Link to this heading">¶</a></h3>621<p>Actions tell <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> what to do when it encounters an option on the622command line. There is a fixed set of actions hard-coded into <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code>;623adding new actions is an advanced topic covered in section624<a class="reference internal" href="#optparse-extending-optparse"><span class="std std-ref">Extending optparse</span></a>. Most actions tell <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> to store625a value in some variable—for example, take a string from the command line and626store it in an attribute of <code class="docutils literal notranslate"><span class="pre">options</span></code>.</p>627<p>If you don’t specify an option action, <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> defaults to <code class="docutils literal notranslate"><span class="pre">store</span></code>.</p>628</section>629<section id="the-store-action">630<span id="optparse-store-action"></span><h3>The store action<a class="headerlink" href="#the-store-action" title="Link to this heading">¶</a></h3>631<p>The most common option action is <code class="docutils literal notranslate"><span class="pre">store</span></code>, which tells <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> to take632the next argument (or the remainder of the current argument), ensure that it is633of the correct type, and store it to your chosen destination.</p>634<p>For example:</p>635<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>636 <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>637</pre></div>638</div>639<p>Now let’s make up a fake command line and ask <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> to parse it:</p>640<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>641<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>642</pre></div>643</div>644<p>When <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> sees the option string <code class="docutils literal notranslate"><span class="pre">-f</span></code>, it consumes the next645argument, <code class="docutils literal notranslate"><span class="pre">foo.txt</span></code>, and stores it in <code class="docutils literal notranslate"><span class="pre">options.filename</span></code>. So, after this646call to <a class="reference internal" href="#optparse.OptionParser.parse_args" title="optparse.OptionParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a>, <code class="docutils literal notranslate"><span class="pre">options.filename</span></code> is <code class="docutils literal notranslate"><span class="pre">"foo.txt"</span></code>.</p>647<p>Some other option types supported by <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> are <code class="docutils literal notranslate"><span class="pre">int</span></code> and <code class="docutils literal notranslate"><span class="pre">float</span></code>.648Here’s an option that expects an integer argument:</p>649<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>650</pre></div>651</div>652<p>Note that this option has no long option string, which is perfectly acceptable.653Also, there’s no explicit action, since the default is <code class="docutils literal notranslate"><span class="pre">store</span></code>.</p>654<p>Let’s parse another fake command-line. This time, we’ll jam the option argument655right up against the option: since <code class="docutils literal notranslate"><span class="pre">-n42</span></code> (one argument) is equivalent to656<code class="docutils literal notranslate"><span class="pre">-n</span> <span class="pre">42</span></code> (two arguments), the code</p>657<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>658<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>659</pre></div>660</div>661<p>will print <code class="docutils literal notranslate"><span class="pre">42</span></code>.</p>662<p>If you don’t specify a type, <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> assumes <code class="docutils literal notranslate"><span class="pre">string</span></code>. Combined with663the fact that the default action is <code class="docutils literal notranslate"><span class="pre">store</span></code>, that means our first example can664be a lot shorter:</p>665<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>666</pre></div>667</div>668<p>If you don’t supply a destination, <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> figures out a sensible669default from the option strings: if the first long option string is670<code class="docutils literal notranslate"><span class="pre">--foo-bar</span></code>, then the default destination is <code class="docutils literal notranslate"><span class="pre">foo_bar</span></code>. If there are no671long option strings, <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> looks at the first short option string: the672default destination for <code class="docutils literal notranslate"><span class="pre">-f</span></code> is <code class="docutils literal notranslate"><span class="pre">f</span></code>.</p>673<p><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> also includes the built-in <code class="docutils literal notranslate"><span class="pre">complex</span></code> type. Adding674types is covered in section <a class="reference internal" href="#optparse-extending-optparse"><span class="std std-ref">Extending optparse</span></a>.</p>675</section>676<section id="handling-boolean-flag-options">677<span id="optparse-handling-boolean-options"></span><h3>Handling boolean (flag) options<a class="headerlink" href="#handling-boolean-flag-options" title="Link to this heading">¶</a></h3>678<p>Flag options—set a variable to true or false when a particular option is679seen—are quite common. <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> supports them with two separate actions,680<code class="docutils literal notranslate"><span class="pre">store_true</span></code> and <code class="docutils literal notranslate"><span class="pre">store_false</span></code>. For example, you might have a <code class="docutils literal notranslate"><span class="pre">verbose</span></code>681flag that is turned on with <code class="docutils literal notranslate"><span class="pre">-v</span></code> and off with <code class="docutils literal notranslate"><span class="pre">-q</span></code>:</p>682<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>683<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>684</pre></div>685</div>686<p>Here we have two different options with the same destination, which is perfectly687OK. (It just means you have to be a bit careful when setting default688values—see below.)</p>689<p>When <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> encounters <code class="docutils literal notranslate"><span class="pre">-v</span></code> on the command line, it sets690<code class="docutils literal notranslate"><span class="pre">options.verbose</span></code> to <code class="docutils literal notranslate"><span class="pre">True</span></code>; when it encounters <code class="docutils literal notranslate"><span class="pre">-q</span></code>,691<code class="docutils literal notranslate"><span class="pre">options.verbose</span></code> is set to <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>692</section>693<section id="other-actions">694<span id="optparse-other-actions"></span><h3>Other actions<a class="headerlink" href="#other-actions" title="Link to this heading">¶</a></h3>695<p>Some other actions supported by <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> are:</p>696<dl class="simple">697<dt><code class="docutils literal notranslate"><span class="pre">"store_const"</span></code></dt><dd><p>store a constant value, pre-set via <a class="reference internal" href="#optparse.Option.const" title="optparse.Option.const"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Option.const</span></code></a></p>698</dd>699<dt><code class="docutils literal notranslate"><span class="pre">"append"</span></code></dt><dd><p>append this option’s argument to a list</p>700</dd>701<dt><code class="docutils literal notranslate"><span class="pre">"count"</span></code></dt><dd><p>increment a counter by one</p>702</dd>703<dt><code class="docutils literal notranslate"><span class="pre">"callback"</span></code></dt><dd><p>call a specified function</p>704</dd>705</dl>706<p>These are covered in section <a class="reference internal" href="#optparse-reference-guide"><span class="std std-ref">Reference Guide</span></a>,707and section <a class="reference internal" href="#optparse-option-callbacks"><span class="std std-ref">Option Callbacks</span></a>.</p>708</section>709<section id="default-values">710<span id="optparse-default-values"></span><h3>Default values<a class="headerlink" href="#default-values" title="Link to this heading">¶</a></h3>711<p>All of the above examples involve setting some variable (the “destination”) when712certain command-line options are seen. What happens if those options are never713seen? Since we didn’t supply any defaults, they are all set to <code class="docutils literal notranslate"><span class="pre">None</span></code>. This714is usually fine, but sometimes you want more control. <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> lets you715supply a default value for each destination, which is assigned before the716command line is parsed.</p>717<p>First, consider the verbose/quiet example. If we want <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> to set718<code class="docutils literal notranslate"><span class="pre">verbose</span></code> to <code class="docutils literal notranslate"><span class="pre">True</span></code> unless <code class="docutils literal notranslate"><span class="pre">-q</span></code> is seen, then we can do this:</p>719<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>720<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>721</pre></div>722</div>723<p>Since default values apply to the <em>destination</em> rather than to any particular724option, and these two options happen to have the same destination, this is725exactly equivalent:</p>726<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>727<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>728</pre></div>729</div>730<p>Consider this:</p>731<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>732<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>733</pre></div>734</div>735<p>Again, the default value for <code class="docutils literal notranslate"><span class="pre">verbose</span></code> will be <code class="docutils literal notranslate"><span class="pre">True</span></code>: the last default736value supplied for any particular destination is the one that counts.</p>737<p>A clearer way to specify default values is the <code class="xref py py-meth docutils literal notranslate"><span class="pre">set_defaults()</span></code> method of738OptionParser, which you can call at any time before calling739<a class="reference internal" href="#optparse.OptionParser.parse_args" title="optparse.OptionParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a>:</p>740<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>741<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>742<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>743</pre></div>744</div>745<p>As before, the last value specified for a given option destination is the one746that counts. For clarity, try to use one method or the other of setting default747values, not both.</p>748</section>749<section id="generating-help">750<span id="optparse-generating-help"></span><h3>Generating help<a class="headerlink" href="#generating-help" title="Link to this heading">¶</a></h3>751<p><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code>’s ability to generate help and usage text automatically is752useful for creating user-friendly command-line interfaces. All you have to do753is supply a <a class="reference internal" href="#optparse.Option.help" title="optparse.Option.help"><code class="xref py py-attr docutils literal notranslate"><span class="pre">help</span></code></a> value for each option, and optionally a short754usage message for your whole program. Here’s an OptionParser populated with755user-friendly (documented) options:</p>756<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">usage</span> <span class="o">=</span> <span class="s2">"usage: %prog [options] arg1 arg2"</span>757<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>758<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>759 <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>760 <span class="n">help</span><span class="o">=</span><span class="s2">"make lots of noise [default]"</span><span class="p">)</span>761<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>762 <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>763 <span class="n">help</span><span class="o">=</span><span class="s2">"be vewwy quiet (I'm hunting wabbits)"</span><span class="p">)</span>764<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>765 <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>766<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>767 <span class="n">default</span><span class="o">=</span><span class="s2">"intermediate"</span><span class="p">,</span>768 <span class="n">help</span><span class="o">=</span><span class="s2">"interaction mode: novice, intermediate, "</span>769 <span class="s2">"or expert [default: </span><span class="si">%d</span><span class="s2">efault]"</span><span class="p">)</span>770</pre></div>771</div>772<p>If <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> encounters either <code class="docutils literal notranslate"><span class="pre">-h</span></code> or <code class="docutils literal notranslate"><span class="pre">--help</span></code> on the773command-line, or if you just call <code class="xref py py-meth docutils literal notranslate"><span class="pre">parser.print_help()</span></code>, it prints the774following to standard output:</p>775<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Usage: <yourscript> [options] arg1 arg2776 777Options:778 -h, --help show this help message and exit779 -v, --verbose make lots of noise [default]780 -q, --quiet be vewwy quiet (I'm hunting wabbits)781 -f FILE, --filename=FILE782 write output to FILE783 -m MODE, --mode=MODE interaction mode: novice, intermediate, or784 expert [default: intermediate]785</pre></div>786</div>787<p>(If the help output is triggered by a help option, <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> exits after788printing the help text.)</p>789<p>There’s a lot going on here to help <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> generate the best possible790help message:</p>791<ul>792<li><p>the script defines its own usage message:</p>793<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">usage</span> <span class="o">=</span> <span class="s2">"usage: %prog [options] arg1 arg2"</span>794</pre></div>795</div>796<p><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> expands <code class="docutils literal notranslate"><span class="pre">%prog</span></code> in the usage string to the name of the797current program, i.e. <code class="docutils literal notranslate"><span class="pre">os.path.basename(sys.argv[0])</span></code>. The expanded string798is then printed before the detailed option help.</p>799<p>If you don’t supply a usage string, <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> uses a bland but sensible800default: <code class="docutils literal notranslate"><span class="pre">"Usage:</span> <span class="pre">%prog</span> <span class="pre">[options]"</span></code>, which is fine if your script doesn’t801take any positional arguments.</p>802</li>803<li><p>every option defines a help string, and doesn’t worry about804line-wrapping—<code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> takes care of wrapping lines and making805the help output look good.</p></li>806<li><p>options that take a value indicate this fact in their automatically generated807help message, e.g. for the “mode” option:</p>808<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>809</pre></div>810</div>811<p>Here, “MODE” is called the meta-variable: it stands for the argument that the812user is expected to supply to <code class="docutils literal notranslate"><span class="pre">-m</span></code>/<code class="docutils literal notranslate"><span class="pre">--mode</span></code>. By default,813<code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> converts the destination variable name to uppercase and uses814that for the meta-variable. Sometimes, that’s not what you want—for815example, the <code class="docutils literal notranslate"><span class="pre">--filename</span></code> option explicitly sets <code class="docutils literal notranslate"><span class="pre">metavar="FILE"</span></code>,816resulting in this automatically generated option description:</p>817<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>818</pre></div>819</div>820<p>This is important for more than just saving space, though: the manually821written help text uses the meta-variable <code class="docutils literal notranslate"><span class="pre">FILE</span></code> to clue the user in that822there’s a connection between the semi-formal syntax <code class="docutils literal notranslate"><span class="pre">-f</span> <span class="pre">FILE</span></code> and the informal823semantic description “write output to FILE”. This is a simple but effective824way to make your help text a lot clearer and more useful for end users.</p>825</li>826<li><p>options that have a default value can include <code class="docutils literal notranslate"><span class="pre">%default</span></code> in the help827string—<code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> will replace it with <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a> of the option’s828default value. If an option has no default value (or the default value is829<code class="docutils literal notranslate"><span class="pre">None</span></code>), <code class="docutils literal notranslate"><span class="pre">%default</span></code> expands to <code class="docutils literal notranslate"><span class="pre">none</span></code>.</p></li>830</ul>831<section id="grouping-options">832<h4>Grouping Options<a class="headerlink" href="#grouping-options" title="Link to this heading">¶</a></h4>833<p>When dealing with many options, it is convenient to group these options for834better help output. An <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionParser</span></code></a> can contain several option groups,835each of which can contain several options.</p>836<p>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 notranslate"><span class="pre">OptionGroup</span></code></a>:</p>837<dl class="py class">838<dt class="sig sig-object py" id="optparse.OptionGroup">839<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">optparse.</span></span><span class="sig-name descname"><span class="pre">OptionGroup</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">parser</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">title</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">description</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#optparse.OptionGroup" title="Link to this definition">¶</a></dt>840<dd><p>where</p>841<ul class="simple">842<li><p>parser is the <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionParser</span></code></a> instance the group will be inserted in843to</p></li>844<li><p>title is the group title</p></li>845<li><p>description, optional, is a long description of the group</p></li>846</ul>847</dd></dl>848 849<p><a class="reference internal" href="#optparse.OptionGroup" title="optparse.OptionGroup"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionGroup</span></code></a> inherits from <code class="xref py py-class docutils literal notranslate"><span class="pre">OptionContainer</span></code> (like850<a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionParser</span></code></a>) and so the <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_option()</span></code> method can be used to add851an option to the group.</p>852<p>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 notranslate"><span class="pre">OptionParser</span></code></a> method853<code class="xref py py-meth docutils literal notranslate"><span class="pre">add_option_group()</span></code> the group is added to the previously defined parser.</p>854<p>Continuing with the parser defined in the previous section, adding an855<a class="reference internal" href="#optparse.OptionGroup" title="optparse.OptionGroup"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionGroup</span></code></a> to a parser is easy:</p>856<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>857 <span class="s2">"Caution: use these options at your own risk. "</span>858 <span class="s2">"It is believed that some of them bite."</span><span class="p">)</span>859<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>860<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>861</pre></div>862</div>863<p>This would result in the following help output:</p>864<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Usage: <yourscript> [options] arg1 arg2865 866Options:867 -h, --help show this help message and exit868 -v, --verbose make lots of noise [default]869 -q, --quiet be vewwy quiet (I'm hunting wabbits)870 -f FILE, --filename=FILE871 write output to FILE872 -m MODE, --mode=MODE interaction mode: novice, intermediate, or873 expert [default: intermediate]874 875 Dangerous Options:876 Caution: use these options at your own risk. It is believed that some877 of them bite.878 879 -g Group option.880</pre></div>881</div>882<p>A bit more complete example might involve using more than one group: still883extending the previous example:</p>884<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>885 <span class="s2">"Caution: use these options at your own risk. "</span>886 <span class="s2">"It is believed that some of them bite."</span><span class="p">)</span>887<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>888<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>889 890<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>891<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>892 <span class="n">help</span><span class="o">=</span><span class="s2">"Print debug information"</span><span class="p">)</span>893<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>894 <span class="n">help</span><span class="o">=</span><span class="s2">"Print all SQL statements executed"</span><span class="p">)</span>895<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>896<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>897</pre></div>898</div>899<p>that results in the following output:</p>900<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Usage: <yourscript> [options] arg1 arg2901 902Options:903 -h, --help show this help message and exit904 -v, --verbose make lots of noise [default]905 -q, --quiet be vewwy quiet (I'm hunting wabbits)906 -f FILE, --filename=FILE907 write output to FILE908 -m MODE, --mode=MODE interaction mode: novice, intermediate, or expert909 [default: intermediate]910 911 Dangerous Options:912 Caution: use these options at your own risk. It is believed that some913 of them bite.914 915 -g Group option.916 917 Debug Options:918 -d, --debug Print debug information919 -s, --sql Print all SQL statements executed920 -e Print every action done921</pre></div>922</div>923<p>Another interesting method, in particular when working programmatically with924option groups is:</p>925<dl class="py method">926<dt class="sig sig-object py" id="optparse.OptionParser.get_option_group">927<span class="sig-prename descclassname"><span class="pre">OptionParser.</span></span><span class="sig-name descname"><span class="pre">get_option_group</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">opt_str</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#optparse.OptionParser.get_option_group" title="Link to this definition">¶</a></dt>928<dd><p>Return the <a class="reference internal" href="#optparse.OptionGroup" title="optparse.OptionGroup"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionGroup</span></code></a> to which the short or long option929string <em>opt_str</em> (e.g. <code class="docutils literal notranslate"><span class="pre">'-o'</span></code> or <code class="docutils literal notranslate"><span class="pre">'--option'</span></code>) belongs. If930there’s no such <code class="xref py py-class docutils literal notranslate"><span class="pre">OptionGroup</span></code>, return <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>931</dd></dl>932 933</section>934</section>935<section id="printing-a-version-string">936<span id="optparse-printing-version-string"></span><h3>Printing a version string<a class="headerlink" href="#printing-a-version-string" title="Link to this heading">¶</a></h3>937<p>Similar to the brief usage string, <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> can also print a version938string for your program. You have to supply the string as the <code class="docutils literal notranslate"><span class="pre">version</span></code>939argument to OptionParser:</p>940<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>941</pre></div>942</div>943<p><code class="docutils literal notranslate"><span class="pre">%prog</span></code> is expanded just like it is in <code class="docutils literal notranslate"><span class="pre">usage</span></code>. Apart from that,944<code class="docutils literal notranslate"><span class="pre">version</span></code> can contain anything you like. When you supply it, <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code>945automatically adds a <code class="docutils literal notranslate"><span class="pre">--version</span></code> option to your parser. If it encounters946this option on the command line, it expands your <code class="docutils literal notranslate"><span class="pre">version</span></code> string (by947replacing <code class="docutils literal notranslate"><span class="pre">%prog</span></code>), prints it to stdout, and exits.</p>948<p>For example, if your script is called <code class="docutils literal notranslate"><span class="pre">/usr/bin/foo</span></code>:</p>949<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>/usr/bin/foo<span class="w"> </span>--version950<span class="go">foo 1.0</span>951</pre></div>952</div>953<p>The following two methods can be used to print and get the <code class="docutils literal notranslate"><span class="pre">version</span></code> string:</p>954<dl class="py method">955<dt class="sig sig-object py" id="optparse.OptionParser.print_version">956<span class="sig-prename descclassname"><span class="pre">OptionParser.</span></span><span class="sig-name descname"><span class="pre">print_version</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">file</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#optparse.OptionParser.print_version" title="Link to this definition">¶</a></dt>957<dd><p>Print the version message for the current program (<code class="docutils literal notranslate"><span class="pre">self.version</span></code>) to958<em>file</em> (default stdout). As with <a class="reference internal" href="#optparse.OptionParser.print_usage" title="optparse.OptionParser.print_usage"><code class="xref py py-meth docutils literal notranslate"><span class="pre">print_usage()</span></code></a>, any occurrence959of <code class="docutils literal notranslate"><span class="pre">%prog</span></code> in <code class="docutils literal notranslate"><span class="pre">self.version</span></code> is replaced with the name of the current960program. Does nothing if <code class="docutils literal notranslate"><span class="pre">self.version</span></code> is empty or undefined.</p>961</dd></dl>962 963<dl class="py method">964<dt class="sig sig-object py" id="optparse.OptionParser.get_version">965<span class="sig-prename descclassname"><span class="pre">OptionParser.</span></span><span class="sig-name descname"><span class="pre">get_version</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#optparse.OptionParser.get_version" title="Link to this definition">¶</a></dt>966<dd><p>Same as <a class="reference internal" href="#optparse.OptionParser.print_version" title="optparse.OptionParser.print_version"><code class="xref py py-meth docutils literal notranslate"><span class="pre">print_version()</span></code></a> but returns the version string instead of967printing it.</p>968</dd></dl>969 970</section>971<section id="how-optparse-handles-errors">972<span id="optparse-how-optparse-handles-errors"></span><h3>How <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> handles errors<a class="headerlink" href="#how-optparse-handles-errors" title="Link to this heading">¶</a></h3>973<p>There are two broad classes of errors that <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> has to worry about:974programmer errors and user errors. Programmer errors are usually erroneous975calls to <a class="reference internal" href="#optparse.OptionParser.add_option" title="optparse.OptionParser.add_option"><code class="xref py py-func docutils literal notranslate"><span class="pre">OptionParser.add_option()</span></code></a>, e.g. invalid option strings, unknown976option attributes, missing option attributes, etc. These are dealt with in the977usual way: raise an exception (either <a class="reference internal" href="#optparse.OptionError" title="optparse.OptionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">optparse.OptionError</span></code></a> or978<a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>) and let the program crash.</p>979<p>Handling user errors is much more important, since they are guaranteed to happen980no matter how stable your code is. <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> can automatically detect981some user errors, such as bad option arguments (passing <code class="docutils literal notranslate"><span class="pre">-n</span> <span class="pre">4x</span></code> where982<code class="docutils literal notranslate"><span class="pre">-n</span></code> takes an integer argument), missing arguments (<code class="docutils literal notranslate"><span class="pre">-n</span></code> at the end983of the command line, where <code class="docutils literal notranslate"><span class="pre">-n</span></code> takes an argument of any type). Also,984you can call <code class="xref py py-func docutils literal notranslate"><span class="pre">OptionParser.error()</span></code> to signal an application-defined error985condition:</p>986<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>987<span class="o">...</span>988<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>989 <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>990</pre></div>991</div>992<p>In either case, <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> handles the error the same way: it prints the993program’s usage message and an error message to standard error and exits with994error status 2.</p>995<p>Consider the first example above, where the user passes <code class="docutils literal notranslate"><span class="pre">4x</span></code> to an option996that takes an integer:</p>997<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>/usr/bin/foo<span class="w"> </span>-n<span class="w"> </span>4x998<span class="go">Usage: foo [options]</span>999 1000<span class="go">foo: error: option -n: invalid integer value: '4x'</span>1001</pre></div>1002</div>1003<p>Or, where the user fails to pass a value at all:</p>1004<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>/usr/bin/foo<span class="w"> </span>-n1005<span class="go">Usage: foo [options]</span>1006 1007<span class="go">foo: error: -n option requires an argument</span>1008</pre></div>1009</div>1010<p><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code>-generated error messages take care always to mention the1011option involved in the error; be sure to do the same when calling1012<code class="xref py py-func docutils literal notranslate"><span class="pre">OptionParser.error()</span></code> from your application code.</p>1013<p>If <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code>’s default error-handling behaviour does not suit your needs,1014you’ll need to subclass OptionParser and override its <code class="xref py py-meth docutils literal notranslate"><span class="pre">exit()</span></code>1015and/or <code class="xref py py-meth docutils literal notranslate"><span class="pre">error()</span></code> methods.</p>1016</section>1017<section id="putting-it-all-together">1018<span id="optparse-putting-it-all-together"></span><h3>Putting it all together<a class="headerlink" href="#putting-it-all-together" title="Link to this heading">¶</a></h3>1019<p>Here’s what <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code>-based scripts usually look like:</p>1020<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">optparse</span><span class="w"> </span><span class="kn">import</span> <span class="n">OptionParser</span>1021<span class="o">...</span>1022<span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>1023 <span class="n">usage</span> <span class="o">=</span> <span class="s2">"usage: %prog [options] arg"</span>1024 <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>1025 <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>1026 <span class="n">help</span><span class="o">=</span><span class="s2">"read data from FILENAME"</span><span class="p">)</span>1027 <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>1028 <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>1029 <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>1030 <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>1031 <span class="o">...</span>1032 <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>1033 <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>1034 <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>1035 <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">verbose</span><span class="p">:</span>1036 <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>1037 <span class="o">...</span>1038 1039<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s2">"__main__"</span><span class="p">:</span>1040 <span class="n">main</span><span class="p">()</span>1041</pre></div>1042</div>1043</section>1044</section>1045<section id="reference-guide">1046<span id="optparse-reference-guide"></span><h2>Reference Guide<a class="headerlink" href="#reference-guide" title="Link to this heading">¶</a></h2>1047<section id="creating-the-parser">1048<span id="optparse-creating-parser"></span><h3>Creating the parser<a class="headerlink" href="#creating-the-parser" title="Link to this heading">¶</a></h3>1049<p>The first step in using <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> is to create an OptionParser instance.</p>1050<dl class="py class">1051<dt class="sig sig-object py" id="optparse.OptionParser">1052<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">optparse.</span></span><span class="sig-name descname"><span class="pre">OptionParser</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">...</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#optparse.OptionParser" title="Link to this definition">¶</a></dt>1053<dd><p>The OptionParser constructor has no required arguments, but a number of1054optional keyword arguments. You should always pass them as keyword1055arguments, i.e. do not rely on the order in which the arguments are declared.</p>1056<dl class="simple">1057<dt><code class="docutils literal notranslate"><span class="pre">usage</span></code> (default: <code class="docutils literal notranslate"><span class="pre">"%prog</span> <span class="pre">[options]"</span></code>)</dt><dd><p>The usage summary to print when your program is run incorrectly or with a1058help option. When <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> prints the usage string, it expands1059<code class="docutils literal notranslate"><span class="pre">%prog</span></code> to <code class="docutils literal notranslate"><span class="pre">os.path.basename(sys.argv[0])</span></code> (or to <code class="docutils literal notranslate"><span class="pre">prog</span></code> if you1060passed that keyword argument). To suppress a usage message, pass the1061special value <code class="xref py py-const docutils literal notranslate"><span class="pre">optparse.SUPPRESS_USAGE</span></code>.</p>1062</dd>1063<dt><code class="docutils literal notranslate"><span class="pre">option_list</span></code> (default: <code class="docutils literal notranslate"><span class="pre">[]</span></code>)</dt><dd><p>A list of Option objects to populate the parser with. The options in1064<code class="docutils literal notranslate"><span class="pre">option_list</span></code> are added after any options in <code class="docutils literal notranslate"><span class="pre">standard_option_list</span></code> (a1065class attribute that may be set by OptionParser subclasses), but before1066any version or help options. Deprecated; use <a class="reference internal" href="#optparse.OptionParser.add_option" title="optparse.OptionParser.add_option"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_option()</span></code></a> after1067creating the parser instead.</p>1068</dd>1069<dt><code class="docutils literal notranslate"><span class="pre">option_class</span></code> (default: optparse.Option)</dt><dd><p>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 notranslate"><span class="pre">add_option()</span></code></a>.</p>1070</dd>1071<dt><code class="docutils literal notranslate"><span class="pre">version</span></code> (default: <code class="docutils literal notranslate"><span class="pre">None</span></code>)</dt><dd><p>A version string to print when the user supplies a version option. If you1072supply a true value for <code class="docutils literal notranslate"><span class="pre">version</span></code>, <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> automatically adds a1073version option with the single option string <code class="docutils literal notranslate"><span class="pre">--version</span></code>. The1074substring <code class="docutils literal notranslate"><span class="pre">%prog</span></code> is expanded the same as for <code class="docutils literal notranslate"><span class="pre">usage</span></code>.</p>1075</dd>1076<dt><code class="docutils literal notranslate"><span class="pre">conflict_handler</span></code> (default: <code class="docutils literal notranslate"><span class="pre">"error"</span></code>)</dt><dd><p>Specifies what to do when options with conflicting option strings are1077added to the parser; see section1078<a class="reference internal" href="#optparse-conflicts-between-options"><span class="std std-ref">Conflicts between options</span></a>.</p>1079</dd>1080<dt><code class="docutils literal notranslate"><span class="pre">description</span></code> (default: <code class="docutils literal notranslate"><span class="pre">None</span></code>)</dt><dd><p>A paragraph of text giving a brief overview of your program.1081<code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> reformats this paragraph to fit the current terminal width1082and prints it when the user requests help (after <code class="docutils literal notranslate"><span class="pre">usage</span></code>, but before the1083list of options).</p>1084</dd>1085<dt><code class="docutils literal notranslate"><span class="pre">formatter</span></code> (default: a new <code class="xref py py-class docutils literal notranslate"><span class="pre">IndentedHelpFormatter</span></code>)</dt><dd><p>An instance of optparse.HelpFormatter that will be used for printing help1086text. <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> provides two concrete classes for this purpose:1087IndentedHelpFormatter and TitledHelpFormatter.</p>1088</dd>1089<dt><code class="docutils literal notranslate"><span class="pre">add_help_option</span></code> (default: <code class="docutils literal notranslate"><span class="pre">True</span></code>)</dt><dd><p>If true, <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> will add a help option (with option strings <code class="docutils literal notranslate"><span class="pre">-h</span></code>1090and <code class="docutils literal notranslate"><span class="pre">--help</span></code>) to the parser.</p>1091</dd>1092<dt><code class="docutils literal notranslate"><span class="pre">prog</span></code></dt><dd><p>The string to use when expanding <code class="docutils literal notranslate"><span class="pre">%prog</span></code> in <code class="docutils literal notranslate"><span class="pre">usage</span></code> and <code class="docutils literal notranslate"><span class="pre">version</span></code>1093instead of <code class="docutils literal notranslate"><span class="pre">os.path.basename(sys.argv[0])</span></code>.</p>1094</dd>1095<dt><code class="docutils literal notranslate"><span class="pre">epilog</span></code> (default: <code class="docutils literal notranslate"><span class="pre">None</span></code>)</dt><dd><p>A paragraph of help text to print after the option help.</p>1096</dd>1097</dl>1098</dd></dl>1099 1100</section>1101<section id="populating-the-parser">1102<span id="optparse-populating-parser"></span><h3>Populating the parser<a class="headerlink" href="#populating-the-parser" title="Link to this heading">¶</a></h3>1103<p>There are several ways to populate the parser with options. The preferred way1104is by using <a class="reference internal" href="#optparse.OptionParser.add_option" title="optparse.OptionParser.add_option"><code class="xref py py-meth docutils literal notranslate"><span class="pre">OptionParser.add_option()</span></code></a>, as shown in section1105<a class="reference internal" href="#optparse-tutorial"><span class="std std-ref">Tutorial</span></a>. <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_option()</span></code> can be called in one of two ways:</p>1106<ul class="simple">1107<li><p>pass it an Option instance (as returned by <code class="xref py py-func docutils literal notranslate"><span class="pre">make_option()</span></code>)</p></li>1108<li><p>pass it any combination of positional and keyword arguments that are1109acceptable to <code class="xref py py-func docutils literal notranslate"><span class="pre">make_option()</span></code> (i.e., to the Option constructor), and it1110will create the Option instance for you</p></li>1111</ul>1112<p>The other alternative is to pass a list of pre-constructed Option instances to1113the OptionParser constructor, as in:</p>1114<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">option_list</span> <span class="o">=</span> <span class="p">[</span>1115 <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>1116 <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>1117 <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>1118 <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>1119 <span class="p">]</span>1120<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>1121</pre></div>1122</div>1123<p>(<code class="xref py py-func docutils literal notranslate"><span class="pre">make_option()</span></code> is a factory function for creating Option instances;1124currently it is an alias for the Option constructor. A future version of1125<code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> may split Option into several classes, and <code class="xref py py-func docutils literal notranslate"><span class="pre">make_option()</span></code>1126will pick the right class to instantiate. Do not instantiate Option directly.)</p>1127</section>1128<section id="defining-options">1129<span id="optparse-defining-options"></span><h3>Defining options<a class="headerlink" href="#defining-options" title="Link to this heading">¶</a></h3>1130<p>Each Option instance represents a set of synonymous command-line option strings,1131e.g. <code class="docutils literal notranslate"><span class="pre">-f</span></code> and <code class="docutils literal notranslate"><span class="pre">--file</span></code>. You can specify any number of short or1132long option strings, but you must specify at least one overall option string.</p>1133<p>The canonical way to create an <a class="reference internal" href="#optparse.Option" title="optparse.Option"><code class="xref py py-class docutils literal notranslate"><span class="pre">Option</span></code></a> instance is with the1134<code class="xref py py-meth docutils literal notranslate"><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 notranslate"><span class="pre">OptionParser</span></code></a>.</p>1135<dl class="py method">1136<dt class="sig sig-object py" id="optparse.OptionParser.add_option">1137<span class="sig-prename descclassname"><span class="pre">OptionParser.</span></span><span class="sig-name descname"><span class="pre">add_option</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">option</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#optparse.OptionParser.add_option" title="Link to this definition">¶</a></dt>1138<dt class="sig sig-object py">1139<span class="sig-prename descclassname"><span class="pre">OptionParser.</span></span><span class="sig-name descname"><span class="pre">add_option</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">*opt_str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">attr=value</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">...</span></span></em><span class="sig-paren">)</span></dt>1140<dd><p>To define an option with only a short option string:</p>1141<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>1142</pre></div>1143</div>1144<p>And to define an option with only a long option string:</p>1145<div class="highlight-python3 notranslate"><div class="highlight"><pre><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>1146</pre></div>1147</div>1148<p>The keyword arguments define attributes of the new Option object. The most1149important option attribute is <a class="reference internal" href="#optparse.Option.action" title="optparse.Option.action"><code class="xref py py-attr docutils literal notranslate"><span class="pre">action</span></code></a>, and it largely1150determines which other attributes are relevant or required. If you pass1151irrelevant option attributes, or fail to pass required ones, <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code>1152raises an <a class="reference internal" href="#optparse.OptionError" title="optparse.OptionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OptionError</span></code></a> exception explaining your mistake.</p>1153<p>An option’s <em>action</em> determines what <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> does when it encounters1154this option on the command-line. The standard option actions hard-coded into1155<code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> are:</p>1156<dl class="simple">1157<dt><code class="docutils literal notranslate"><span class="pre">"store"</span></code></dt><dd><p>store this option’s argument (default)</p>1158</dd>1159<dt><code class="docutils literal notranslate"><span class="pre">"store_const"</span></code></dt><dd><p>store a constant value, pre-set via <a class="reference internal" href="#optparse.Option.const" title="optparse.Option.const"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Option.const</span></code></a></p>1160</dd>1161<dt><code class="docutils literal notranslate"><span class="pre">"store_true"</span></code></dt><dd><p>store <code class="docutils literal notranslate"><span class="pre">True</span></code></p>1162</dd>1163<dt><code class="docutils literal notranslate"><span class="pre">"store_false"</span></code></dt><dd><p>store <code class="docutils literal notranslate"><span class="pre">False</span></code></p>1164</dd>1165<dt><code class="docutils literal notranslate"><span class="pre">"append"</span></code></dt><dd><p>append this option’s argument to a list</p>1166</dd>1167<dt><code class="docutils literal notranslate"><span class="pre">"append_const"</span></code></dt><dd><p>append a constant value to a list, pre-set via <a class="reference internal" href="#optparse.Option.const" title="optparse.Option.const"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Option.const</span></code></a></p>1168</dd>1169<dt><code class="docutils literal notranslate"><span class="pre">"count"</span></code></dt><dd><p>increment a counter by one</p>1170</dd>1171<dt><code class="docutils literal notranslate"><span class="pre">"callback"</span></code></dt><dd><p>call a specified function</p>1172</dd>1173<dt><code class="docutils literal notranslate"><span class="pre">"help"</span></code></dt><dd><p>print a usage message including all options and the documentation for them</p>1174</dd>1175</dl>1176<p>(If you don’t supply an action, the default is <code class="docutils literal notranslate"><span class="pre">"store"</span></code>. For this action,1177you may also supply <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal notranslate"><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 notranslate"><span class="pre">dest</span></code></a> option1178attributes; see <a class="reference internal" href="#optparse-standard-option-actions"><span class="std std-ref">Standard option actions</span></a>.)</p>1179</dd></dl>1180 1181<p>As you can see, most actions involve storing or updating a value somewhere.1182<code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> always creates a special object for this, conventionally called1183<code class="docutils literal notranslate"><span class="pre">options</span></code>, which is an instance of <a class="reference internal" href="#optparse.Values" title="optparse.Values"><code class="xref py py-class docutils literal notranslate"><span class="pre">optparse.Values</span></code></a>.</p>1184<dl class="py class">1185<dt class="sig sig-object py" id="optparse.Values">1186<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">optparse.</span></span><span class="sig-name descname"><span class="pre">Values</span></span><a class="headerlink" href="#optparse.Values" title="Link to this definition">¶</a></dt>1187<dd><p>An object holding parsed argument names and values as attributes.1188Normally created by calling when calling <a class="reference internal" href="#optparse.OptionParser.parse_args" title="optparse.OptionParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">OptionParser.parse_args()</span></code></a>,1189and can be overridden by a custom subclass passed to the <em>values</em> argument of1190<code class="xref py py-meth docutils literal notranslate"><span class="pre">OptionParser.parse_args()</span></code> (as described in <a class="reference internal" href="#optparse-parsing-arguments"><span class="std std-ref">Parsing arguments</span></a>).</p>1191</dd></dl>1192 1193<p>Option1194arguments (and various other values) are stored as attributes of this object,1195according to the <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a> (destination) option attribute.</p>1196<p>For example, when you call</p>1197<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>1198</pre></div>1199</div>1200<p>one of the first things <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> does is create the <code class="docutils literal notranslate"><span class="pre">options</span></code> object:</p>