Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
關註 1
收藏 0
Wiki 捐赠
gooderp18绿色标准版
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
目錄樹: 0f75e31513
分支列表 標籤列表
${ item.name }
Create branch ${ searchTerm }
from '0f75e31513'
${ noResults }
Green_GoodERP18_FSJ_Standard/python/Doc/html/library/argparse.html

2661 line
321KB
原始文件 Blame 文件歷史 

  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="argparse — Parser for command-line options, arguments and sub-commands" />

  8. <meta property="og:type" content="website" />

  9. <meta property="og:url" content="https://docs.python.org/3/library/argparse.html" />

  10. <meta property="og:site_name" content="Python documentation" />

  11. <meta property="og:description" content="Source code: Lib/argparse.py Tutorial: This page contains the API reference information. For a more gentle introduction to Python command-line parsing, have a look at the argparse tutorial. The arg..." />

  12. <meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />

  13. <meta property="og:image:alt" content="Python documentation" />

  14. <meta name="description" content="Source code: Lib/argparse.py Tutorial: This page contains the API reference information. For a more gentle introduction to Python command-line parsing, have a look at the argparse tutorial. The arg..." />

  15. <meta property="og:image:width" content="200" />

  16. <meta property="og:image:height" content="200" />

  17. <meta name="theme-color" content="#3776ab" />

  18. 

  19.     <title>argparse — Parser for command-line options, arguments and sub-commands &#8212; Python 3.12.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">

  20.     

  21.     <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />

  22.     <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=bb723527" />

  23.     <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=b20cc3f5" />

  24.     

  25.     <script src="../_static/documentation_options.js?v=2c828074"></script>

  26.     <script src="../_static/doctools.js?v=888ff710"></script>

  27.     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>

  28.     

  29.     <script src="../_static/sidebar.js"></script>

  30.     

  31.     <link rel="search" type="application/opensearchdescription+xml"

  32.           title="Search within Python 3.12.3 documentation"

  33.           href="../_static/opensearch.xml"/>

  34.     <link rel="author" title="About these documents" href="../about.html" />

  35.     <link rel="index" title="Index" href="../genindex.html" />

  36.     <link rel="search" title="Search" href="../search.html" />

  37.     <link rel="copyright" title="Copyright" href="../copyright.html" />

  38.     <link rel="next" title="getopt — C-style parser for command line options" href="getopt.html" />

  39.     <link rel="prev" title="time — Time access and conversions" href="time.html" />

  40.     <link rel="canonical" href="https://docs.python.org/3/library/argparse.html" />

  41.     

  42.       

  43.     

  44. 

  45.     

  46.     <style>

  47.       @media only screen {

  48.         table.full-width-table {

  49.             width: 100%;

  50.         }

  51.       }

  52.     </style>

  53. <link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">

  54.     <link rel="shortcut icon" type="image/png" href="../_static/py.svg" />

  55.             <script type="text/javascript" src="../_static/copybutton.js"></script>

  56.             <script type="text/javascript" src="../_static/menu.js"></script>

  57.             <script type="text/javascript" src="../_static/search-focus.js"></script>

  58.             <script type="text/javascript" src="../_static/themetoggle.js"></script> 

  59. 

  60.   </head>

  61. <body>

  62. <div class="mobile-nav">

  63.     <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"

  64.            aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />

  65.     <nav class="nav-content" role="navigation">

  66.         <label for="menuToggler" class="toggler__label">

  67.             <span></span>

  68.         </label>

  69.         <span class="nav-items-wrapper">

  70.             <a href="https://www.python.org/" class="nav-logo">

  71.                 <img src="../_static/py.svg" alt="Python logo"/>

  72.             </a>

  73.             <span class="version_switcher_placeholder"></span>

  74.             <form role="search" class="search" action="../search.html" method="get">

  75.                 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">

  76.                     <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>

  77.                 </svg>

  78.                 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />

  79.                 <input type="submit" value="Go"/>

  80.             </form>

  81.         </span>

  82.     </nav>

  83.     <div class="menu-wrapper">

  84.         <nav class="menu" role="navigation" aria-label="main navigation">

  85.             <div class="language_switcher_placeholder"></div>

  86.             

  87. <label class="theme-selector-label">

  88.     Theme

  89.     <select class="theme-selector" oninput="activateTheme(this.value)">

  90.         <option value="auto" selected>Auto</option>

  91.         <option value="light">Light</option>

  92.         <option value="dark">Dark</option>

  93.     </select>

  94. </label>

  95.   <div>

  96.     <h3><a href="../contents.html">Table of Contents</a></h3>

  97.     <ul>

  98. <li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> — Parser for command-line options, arguments and sub-commands</a><ul>

  99. <li><a class="reference internal" href="#core-functionality">Core Functionality</a></li>

  100. <li><a class="reference internal" href="#quick-links-for-add-argument">Quick Links for add_argument()</a></li>

  101. <li><a class="reference internal" href="#example">Example</a><ul>

  102. <li><a class="reference internal" href="#creating-a-parser">Creating a parser</a></li>

  103. <li><a class="reference internal" href="#adding-arguments">Adding arguments</a></li>

  104. <li><a class="reference internal" href="#parsing-arguments">Parsing arguments</a></li>

  105. </ul>

  106. </li>

  107. <li><a class="reference internal" href="#argumentparser-objects">ArgumentParser objects</a><ul>

  108. <li><a class="reference internal" href="#prog">prog</a></li>

  109. <li><a class="reference internal" href="#usage">usage</a></li>

  110. <li><a class="reference internal" href="#description">description</a></li>

  111. <li><a class="reference internal" href="#epilog">epilog</a></li>

  112. <li><a class="reference internal" href="#parents">parents</a></li>

  113. <li><a class="reference internal" href="#formatter-class">formatter_class</a></li>

  114. <li><a class="reference internal" href="#prefix-chars">prefix_chars</a></li>

  115. <li><a class="reference internal" href="#fromfile-prefix-chars">fromfile_prefix_chars</a></li>

  116. <li><a class="reference internal" href="#argument-default">argument_default</a></li>

  117. <li><a class="reference internal" href="#allow-abbrev">allow_abbrev</a></li>

  118. <li><a class="reference internal" href="#conflict-handler">conflict_handler</a></li>

  119. <li><a class="reference internal" href="#add-help">add_help</a></li>

  120. <li><a class="reference internal" href="#exit-on-error">exit_on_error</a></li>

  121. </ul>

  122. </li>

  123. <li><a class="reference internal" href="#the-add-argument-method">The add_argument() method</a><ul>

  124. <li><a class="reference internal" href="#name-or-flags">name or flags</a></li>

  125. <li><a class="reference internal" href="#action">action</a></li>

  126. <li><a class="reference internal" href="#nargs">nargs</a></li>

  127. <li><a class="reference internal" href="#const">const</a></li>

  128. <li><a class="reference internal" href="#default">default</a></li>

  129. <li><a class="reference internal" href="#type">type</a></li>

  130. <li><a class="reference internal" href="#choices">choices</a></li>

  131. <li><a class="reference internal" href="#required">required</a></li>

  132. <li><a class="reference internal" href="#help">help</a></li>

  133. <li><a class="reference internal" href="#metavar">metavar</a></li>

  134. <li><a class="reference internal" href="#dest">dest</a></li>

  135. <li><a class="reference internal" href="#action-classes">Action classes</a></li>

  136. </ul>

  137. </li>

  138. <li><a class="reference internal" href="#the-parse-args-method">The parse_args() method</a><ul>

  139. <li><a class="reference internal" href="#option-value-syntax">Option value syntax</a></li>

  140. <li><a class="reference internal" href="#invalid-arguments">Invalid arguments</a></li>

  141. <li><a class="reference internal" href="#arguments-containing">Arguments containing <code class="docutils literal notranslate"><span class="pre">-</span></code></a></li>

  142. <li><a class="reference internal" href="#argument-abbreviations-prefix-matching">Argument abbreviations (prefix matching)</a></li>

  143. <li><a class="reference internal" href="#beyond-sys-argv">Beyond <code class="docutils literal notranslate"><span class="pre">sys.argv</span></code></a></li>

  144. <li><a class="reference internal" href="#the-namespace-object">The Namespace object</a></li>

  145. </ul>

  146. </li>

  147. <li><a class="reference internal" href="#other-utilities">Other utilities</a><ul>

  148. <li><a class="reference internal" href="#sub-commands">Sub-commands</a></li>

  149. <li><a class="reference internal" href="#filetype-objects">FileType objects</a></li>

  150. <li><a class="reference internal" href="#argument-groups">Argument groups</a></li>

  151. <li><a class="reference internal" href="#mutual-exclusion">Mutual exclusion</a></li>

  152. <li><a class="reference internal" href="#parser-defaults">Parser defaults</a></li>

  153. <li><a class="reference internal" href="#printing-help">Printing help</a></li>

  154. <li><a class="reference internal" href="#partial-parsing">Partial parsing</a></li>

  155. <li><a class="reference internal" href="#customizing-file-parsing">Customizing file parsing</a></li>

  156. <li><a class="reference internal" href="#exiting-methods">Exiting methods</a></li>

  157. <li><a class="reference internal" href="#intermixed-parsing">Intermixed parsing</a></li>

  158. </ul>

  159. </li>

  160. <li><a class="reference internal" href="#upgrading-optparse-code">Upgrading optparse code</a></li>

  161. <li><a class="reference internal" href="#exceptions">Exceptions</a></li>

  162. </ul>

  163. </li>

  164. </ul>

  165. 

  166.   </div>

  167.   <div>

  168.     <h4>Previous topic</h4>

  169.     <p class="topless"><a href="time.html"

  170.                           title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">time</span></code> — Time access and conversions</a></p>

  171.   </div>

  172.   <div>

  173.     <h4>Next topic</h4>

  174.     <p class="topless"><a href="getopt.html"

  175.                           title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">getopt</span></code> — C-style parser for command line options</a></p>

  176.   </div>

  177.   <div role="note" aria-label="source link">

  178.     <h3>This Page</h3>

  179.     <ul class="this-page-menu">

  180.       <li><a href="../bugs.html">Report a Bug</a></li>

  181.       <li>

  182.         <a href="https://github.com/python/cpython/blob/main/Doc/library/argparse.rst"

  183.             rel="nofollow">Show Source

  184.         </a>

  185.       </li>

  186.     </ul>

  187.   </div>

  188.         </nav>

  189.     </div>

  190. </div>

  191. 

  192.   

  193.     <div class="related" role="navigation" aria-label="related navigation">

  194.       <h3>Navigation</h3>

  195.       <ul>

  196.         <li class="right" style="margin-right: 10px">

  197.           <a href="../genindex.html" title="General Index"

  198.              accesskey="I">index</a></li>

  199.         <li class="right" >

  200.           <a href="../py-modindex.html" title="Python Module Index"

  201.              >modules</a> |</li>

  202.         <li class="right" >

  203.           <a href="getopt.html" title="getopt — C-style parser for command line options"

  204.              accesskey="N">next</a> |</li>

  205.         <li class="right" >

  206.           <a href="time.html" title="time — Time access and conversions"

  207.              accesskey="P">previous</a> |</li>

  208. 

  209.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  210.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  211.           <li class="switchers">

  212.             <div class="language_switcher_placeholder"></div>

  213.             <div class="version_switcher_placeholder"></div>

  214.           </li>

  215.           <li>

  216.               

  217.           </li>

  218.     <li id="cpython-language-and-version">

  219.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  220.     </li>

  221. 

  222.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  223.           <li class="nav-item nav-item-2"><a href="allos.html" accesskey="U">Generic Operating System Services</a> &#187;</li>

  224.         <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> — Parser for command-line options, arguments and sub-commands</a></li>

  225.                 <li class="right">

  226.                     

  227. 

  228.     <div class="inline-search" role="search">

  229.         <form class="inline-search" action="../search.html" method="get">

  230.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  231.           <input type="submit" value="Go" />

  232.         </form>

  233.     </div>

  234.                      |

  235.                 </li>

  236.             <li class="right">

  237. <label class="theme-selector-label">

  238.     Theme

  239.     <select class="theme-selector" oninput="activateTheme(this.value)">

  240.         <option value="auto" selected>Auto</option>

  241.         <option value="light">Light</option>

  242.         <option value="dark">Dark</option>

  243.     </select>

  244. </label> |</li>

  245.             

  246.       </ul>

  247.     </div>    

  248. 

  249.     <div class="document">

  250.       <div class="documentwrapper">

  251.         <div class="bodywrapper">

  252.           <div class="body" role="main">

  253.             

  254.   <section id="module-argparse">

  255. <span id="argparse-parser-for-command-line-options-arguments-and-sub-commands"></span><h1><a class="reference internal" href="#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> — Parser for command-line options, arguments and sub-commands<a class="headerlink" href="#module-argparse" title="Link to this heading">¶</a></h1>

  256. <div class="versionadded">

  257. <p><span class="versionmodified added">New in version 3.2.</span></p>

  258. </div>

  259. <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/argparse.py">Lib/argparse.py</a></p>

  260. <hr class="docutils" />

  261. <aside class="sidebar">

  262. <p class="sidebar-title">Tutorial</p>

  263. <p>This page contains the API reference information. For a more gentle

  264. introduction to Python command-line parsing, have a look at the

  265. <a class="reference internal" href="../howto/argparse.html#argparse-tutorial"><span class="std std-ref">argparse tutorial</span></a>.</p>

  266. </aside>

  267. <p>The <a class="reference internal" href="#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> module makes it easy to write user-friendly command-line

  268. interfaces. The program defines what arguments it requires, and <a class="reference internal" href="#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>

  269. will figure out how to parse those out of <a class="reference internal" href="sys.html#sys.argv" title="sys.argv"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.argv</span></code></a>.  The <a class="reference internal" href="#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>

  270. module also automatically generates help and usage messages.  The module

  271. will also issue errors when users give the program invalid arguments.</p>

  272. <section id="core-functionality">

  273. <h2>Core Functionality<a class="headerlink" href="#core-functionality" title="Link to this heading">¶</a></h2>

  274. <p>The <a class="reference internal" href="#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> module’s support for command-line interfaces is built

  275. around an instance of <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">argparse.ArgumentParser</span></code></a>.  It is a container for

  276. argument specifications and has options that apply to the parser as whole:</p>

  277. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><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>

  278.                     <span class="n">prog</span><span class="o">=</span><span class="s1">&#39;ProgramName&#39;</span><span class="p">,</span>

  279.                     <span class="n">description</span><span class="o">=</span><span class="s1">&#39;What the program does&#39;</span><span class="p">,</span>

  280.                     <span class="n">epilog</span><span class="o">=</span><span class="s1">&#39;Text at the bottom of help&#39;</span><span class="p">)</span>

  281. </pre></div>

  282. </div>

  283. <p>The <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ArgumentParser.add_argument()</span></code></a> method attaches individual argument

  284. specifications to the parser.  It supports positional arguments, options that

  285. accept values, and on/off flags:</p>

  286. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;filename&#39;</span><span class="p">)</span>           <span class="c1"># positional argument</span>

  287. <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-c&#39;</span><span class="p">,</span> <span class="s1">&#39;--count&#39;</span><span class="p">)</span>      <span class="c1"># option that takes a value</span>

  288. <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-v&#39;</span><span class="p">,</span> <span class="s1">&#39;--verbose&#39;</span><span class="p">,</span>

  289.                     <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_true&#39;</span><span class="p">)</span>  <span class="c1"># on/off flag</span>

  290. </pre></div>

  291. </div>

  292. <p>The <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ArgumentParser.parse_args()</span></code></a> method runs the parser and places

  293. the extracted data in a <a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate"><span class="pre">argparse.Namespace</span></code></a> object:</p>

  294. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></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>

  295. <span class="nb">print</span><span class="p">(</span><span class="n">args</span><span class="o">.</span><span class="n">filename</span><span class="p">,</span> <span class="n">args</span><span class="o">.</span><span class="n">count</span><span class="p">,</span> <span class="n">args</span><span class="o">.</span><span class="n">verbose</span><span class="p">)</span>

  296. </pre></div>

  297. </div>

  298. </section>

  299. <section id="quick-links-for-add-argument">

  300. <h2>Quick Links for add_argument()<a class="headerlink" href="#quick-links-for-add-argument" title="Link to this heading">¶</a></h2>

  301. <table class="docutils align-default">

  302. <thead>

  303. <tr class="row-odd"><th class="head"><p>Name</p></th>

  304. <th class="head"><p>Description</p></th>

  305. <th class="head"><p>Values</p></th>

  306. </tr>

  307. </thead>

  308. <tbody>

  309. <tr class="row-even"><td><p><a class="reference internal" href="#action">action</a></p></td>

  310. <td><p>Specify how an argument should be handled</p></td>

  311. <td><p><code class="docutils literal notranslate"><span class="pre">'store'</span></code>, <code class="docutils literal notranslate"><span class="pre">'store_const'</span></code>, <code class="docutils literal notranslate"><span class="pre">'store_true'</span></code>, <code class="docutils literal notranslate"><span class="pre">'append'</span></code>, <code class="docutils literal notranslate"><span class="pre">'append_const'</span></code>, <code class="docutils literal notranslate"><span class="pre">'count'</span></code>, <code class="docutils literal notranslate"><span class="pre">'help'</span></code>, <code class="docutils literal notranslate"><span class="pre">'version'</span></code></p></td>

  312. </tr>

  313. <tr class="row-odd"><td><p><a class="reference internal" href="#choices">choices</a></p></td>

  314. <td><p>Limit values to a specific set of choices</p></td>

  315. <td><p><code class="docutils literal notranslate"><span class="pre">['foo',</span> <span class="pre">'bar']</span></code>, <code class="docutils literal notranslate"><span class="pre">range(1,</span> <span class="pre">10)</span></code>, or <a class="reference internal" href="collections.abc.html#collections.abc.Container" title="collections.abc.Container"><code class="xref py py-class docutils literal notranslate"><span class="pre">Container</span></code></a> instance</p></td>

  316. </tr>

  317. <tr class="row-even"><td><p><a class="reference internal" href="#const">const</a></p></td>

  318. <td><p>Store a constant value</p></td>

  319. <td></td>

  320. </tr>

  321. <tr class="row-odd"><td><p><a class="reference internal" href="#default">default</a></p></td>

  322. <td><p>Default value used when an argument is not provided</p></td>

  323. <td><p>Defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code></p></td>

  324. </tr>

  325. <tr class="row-even"><td><p><a class="reference internal" href="#dest">dest</a></p></td>

  326. <td><p>Specify the attribute name used in the result namespace</p></td>

  327. <td></td>

  328. </tr>

  329. <tr class="row-odd"><td><p><a class="reference internal" href="#help">help</a></p></td>

  330. <td><p>Help message for an argument</p></td>

  331. <td></td>

  332. </tr>

  333. <tr class="row-even"><td><p><a class="reference internal" href="#metavar">metavar</a></p></td>

  334. <td><p>Alternate display name for the argument as shown in help</p></td>

  335. <td></td>

  336. </tr>

  337. <tr class="row-odd"><td><p><a class="reference internal" href="#nargs">nargs</a></p></td>

  338. <td><p>Number of times the argument can be used</p></td>

  339. <td><p><a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>, <code class="docutils literal notranslate"><span class="pre">'?'</span></code>, <code class="docutils literal notranslate"><span class="pre">'*'</span></code>, or <code class="docutils literal notranslate"><span class="pre">'+'</span></code></p></td>

  340. </tr>

  341. <tr class="row-even"><td><p><a class="reference internal" href="#required">required</a></p></td>

  342. <td><p>Indicate whether an argument is required or optional</p></td>

  343. <td><p><code class="docutils literal notranslate"><span class="pre">True</span></code> or <code class="docutils literal notranslate"><span class="pre">False</span></code></p></td>

  344. </tr>

  345. <tr class="row-odd"><td><p><a class="reference internal" href="#argparse-type"><span class="std std-ref">type</span></a></p></td>

  346. <td><p>Automatically convert an argument to the given type</p></td>

  347. <td><p><a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>, <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>, <code class="docutils literal notranslate"><span class="pre">argparse.FileType('w')</span></code>, or callable function</p></td>

  348. </tr>

  349. </tbody>

  350. </table>

  351. </section>

  352. <section id="example">

  353. <h2>Example<a class="headerlink" href="#example" title="Link to this heading">¶</a></h2>

  354. <p>The following code is a Python program that takes a list of integers and

  355. produces either the sum or the max:</p>

  356. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">argparse</span>

  357. 

  358. <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><span class="n">description</span><span class="o">=</span><span class="s1">&#39;Process some integers.&#39;</span><span class="p">)</span>

  359. <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;integers&#39;</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">&#39;N&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;+&#39;</span><span class="p">,</span>

  360.                     <span class="n">help</span><span class="o">=</span><span class="s1">&#39;an integer for the accumulator&#39;</span><span class="p">)</span>

  361. <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--sum&#39;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">&#39;accumulate&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_const&#39;</span><span class="p">,</span>

  362.                     <span class="n">const</span><span class="o">=</span><span class="nb">sum</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="nb">max</span><span class="p">,</span>

  363.                     <span class="n">help</span><span class="o">=</span><span class="s1">&#39;sum the integers (default: find the max)&#39;</span><span class="p">)</span>

  364. 

  365. <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>

  366. <span class="nb">print</span><span class="p">(</span><span class="n">args</span><span class="o">.</span><span class="n">accumulate</span><span class="p">(</span><span class="n">args</span><span class="o">.</span><span class="n">integers</span><span class="p">))</span>

  367. </pre></div>

  368. </div>

  369. <p>Assuming the above Python code is saved into a file called <code class="docutils literal notranslate"><span class="pre">prog.py</span></code>, it can

  370. be run at the command line and it provides useful help messages:</p>

  371. <div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>prog.py<span class="w"> </span>-h

  372. <span class="go">usage: prog.py [-h] [--sum] N [N ...]</span>

  373. 

  374. <span class="go">Process some integers.</span>

  375. 

  376. <span class="go">positional arguments:</span>

  377. <span class="go"> N           an integer for the accumulator</span>

  378. 

  379. <span class="go">options:</span>

  380. <span class="go"> -h, --help  show this help message and exit</span>

  381. <span class="go"> --sum       sum the integers (default: find the max)</span>

  382. </pre></div>

  383. </div>

  384. <p>When run with the appropriate arguments, it prints either the sum or the max of

  385. the command-line integers:</p>

  386. <div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>prog.py<span class="w"> </span><span class="m">1</span><span class="w"> </span><span class="m">2</span><span class="w"> </span><span class="m">3</span><span class="w"> </span><span class="m">4</span>

  387. <span class="go">4</span>

  388. 

  389. <span class="gp">$ </span>python<span class="w"> </span>prog.py<span class="w"> </span><span class="m">1</span><span class="w"> </span><span class="m">2</span><span class="w"> </span><span class="m">3</span><span class="w"> </span><span class="m">4</span><span class="w"> </span>--sum

  390. <span class="go">10</span>

  391. </pre></div>

  392. </div>

  393. <p>If invalid arguments are passed in, an error will be displayed:</p>

  394. <div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>prog.py<span class="w"> </span>a<span class="w"> </span>b<span class="w"> </span>c

  395. <span class="go">usage: prog.py [-h] [--sum] N [N ...]</span>

  396. <span class="go">prog.py: error: argument N: invalid int value: &#39;a&#39;</span>

  397. </pre></div>

  398. </div>

  399. <p>The following sections walk you through this example.</p>

  400. <section id="creating-a-parser">

  401. <h3>Creating a parser<a class="headerlink" href="#creating-a-parser" title="Link to this heading">¶</a></h3>

  402. <p>The first step in using the <a class="reference internal" href="#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> is creating an

  403. <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> object:</p>

  404. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">description</span><span class="o">=</span><span class="s1">&#39;Process some integers.&#39;</span><span class="p">)</span>

  405. </pre></div>

  406. </div>

  407. <p>The <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> object will hold all the information necessary to

  408. parse the command line into Python data types.</p>

  409. </section>

  410. <section id="adding-arguments">

  411. <h3>Adding arguments<a class="headerlink" href="#adding-arguments" title="Link to this heading">¶</a></h3>

  412. <p>Filling an <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> with information about program arguments is

  413. done by making calls to the <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> method.

  414. Generally, these calls tell the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> how to take the strings

  415. on the command line and turn them into objects.  This information is stored and

  416. used when <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> is called. For example:</p>

  417. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;integers&#39;</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">&#39;N&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;+&#39;</span><span class="p">,</span>

  418. <span class="gp">... </span>                    <span class="n">help</span><span class="o">=</span><span class="s1">&#39;an integer for the accumulator&#39;</span><span class="p">)</span>

  419. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--sum&#39;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">&#39;accumulate&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_const&#39;</span><span class="p">,</span>

  420. <span class="gp">... </span>                    <span class="n">const</span><span class="o">=</span><span class="nb">sum</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="nb">max</span><span class="p">,</span>

  421. <span class="gp">... </span>                    <span class="n">help</span><span class="o">=</span><span class="s1">&#39;sum the integers (default: find the max)&#39;</span><span class="p">)</span>

  422. </pre></div>

  423. </div>

  424. <p>Later, calling <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> will return an object with

  425. two attributes, <code class="docutils literal notranslate"><span class="pre">integers</span></code> and <code class="docutils literal notranslate"><span class="pre">accumulate</span></code>.  The <code class="docutils literal notranslate"><span class="pre">integers</span></code> attribute

  426. will be a list of one or more integers, and the <code class="docutils literal notranslate"><span class="pre">accumulate</span></code> attribute will be

  427. either the <a class="reference internal" href="functions.html#sum" title="sum"><code class="xref py py-func docutils literal notranslate"><span class="pre">sum()</span></code></a> function, if <code class="docutils literal notranslate"><span class="pre">--sum</span></code> was specified at the command line,

  428. or the <a class="reference internal" href="functions.html#max" title="max"><code class="xref py py-func docutils literal notranslate"><span class="pre">max()</span></code></a> function if it was not.</p>

  429. </section>

  430. <section id="parsing-arguments">

  431. <h3>Parsing arguments<a class="headerlink" href="#parsing-arguments" title="Link to this heading">¶</a></h3>

  432. <p><a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> parses arguments through the

  433. <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> method.  This will inspect the command line,

  434. convert each argument to the appropriate type and then invoke the appropriate action.

  435. In most cases, this means a simple <a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate"><span class="pre">Namespace</span></code></a> object will be built up from

  436. attributes parsed out of the command line:</p>

  437. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--sum&#39;</span><span class="p">,</span> <span class="s1">&#39;7&#39;</span><span class="p">,</span> <span class="s1">&#39;-1&#39;</span><span class="p">,</span> <span class="s1">&#39;42&#39;</span><span class="p">])</span>

  438. <span class="go">Namespace(accumulate=&lt;built-in function sum&gt;, integers=[7, -1, 42])</span>

  439. </pre></div>

  440. </div>

  441. <p>In a script, <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> will typically be called with no

  442. arguments, and the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> will automatically determine the

  443. command-line arguments from <a class="reference internal" href="sys.html#sys.argv" title="sys.argv"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.argv</span></code></a>.</p>

  444. </section>

  445. </section>

  446. <section id="argumentparser-objects">

  447. <h2>ArgumentParser objects<a class="headerlink" href="#argumentparser-objects" title="Link to this heading">¶</a></h2>

  448. <dl class="py class">

  449. <dt class="sig sig-object py" id="argparse.ArgumentParser">

  450. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">argparse.</span></span><span class="sig-name descname"><span class="pre">ArgumentParser</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">prog</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">usage</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</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>, <em class="sig-param"><span class="n"><span class="pre">epilog</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">parents</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">[]</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">formatter_class</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">argparse.HelpFormatter</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">prefix_chars</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'-'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fromfile_prefix_chars</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">argument_default</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">conflict_handler</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'error'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">add_help</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">allow_abbrev</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">exit_on_error</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser" title="Link to this definition">¶</a></dt>

  451. <dd><p>Create a new <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> object. All parameters should be passed

  452. as keyword arguments. Each parameter has its own more detailed description

  453. below, but in short they are:</p>

  454. <ul class="simple">

  455. <li><p><a class="reference internal" href="#prog">prog</a> - The name of the program (default:

  456. <code class="docutils literal notranslate"><span class="pre">os.path.basename(sys.argv[0])</span></code>)</p></li>

  457. <li><p><a class="reference internal" href="#usage">usage</a> - The string describing the program usage (default: generated from

  458. arguments added to parser)</p></li>

  459. <li><p><a class="reference internal" href="#description">description</a> - Text to display before the argument help

  460. (by default, no text)</p></li>

  461. <li><p><a class="reference internal" href="#epilog">epilog</a> - Text to display after the argument help (by default, no text)</p></li>

  462. <li><p><a class="reference internal" href="#parents">parents</a> - A list of <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> objects whose arguments should

  463. also be included</p></li>

  464. <li><p><a class="reference internal" href="#formatter-class">formatter_class</a> - A class for customizing the help output</p></li>

  465. <li><p><a class="reference internal" href="#prefix-chars">prefix_chars</a> - The set of characters that prefix optional arguments

  466. (default: ‘-‘)</p></li>

  467. <li><p><a class="reference internal" href="#fromfile-prefix-chars">fromfile_prefix_chars</a> - The set of characters that prefix files from

  468. which additional arguments should be read (default: <code class="docutils literal notranslate"><span class="pre">None</span></code>)</p></li>

  469. <li><p><a class="reference internal" href="#argument-default">argument_default</a> - The global default value for arguments

  470. (default: <code class="docutils literal notranslate"><span class="pre">None</span></code>)</p></li>

  471. <li><p><a class="reference internal" href="#conflict-handler">conflict_handler</a> - The strategy for resolving conflicting optionals

  472. (usually unnecessary)</p></li>

  473. <li><p><a class="reference internal" href="#add-help">add_help</a> - Add a <code class="docutils literal notranslate"><span class="pre">-h/--help</span></code> option to the parser (default: <code class="docutils literal notranslate"><span class="pre">True</span></code>)</p></li>

  474. <li><p><a class="reference internal" href="#allow-abbrev">allow_abbrev</a> - Allows long options to be abbreviated if the

  475. abbreviation is unambiguous. (default: <code class="docutils literal notranslate"><span class="pre">True</span></code>)</p></li>

  476. <li><p><a class="reference internal" href="#exit-on-error">exit_on_error</a> - Determines whether or not ArgumentParser exits with

  477. error info when an error occurs. (default: <code class="docutils literal notranslate"><span class="pre">True</span></code>)</p></li>

  478. </ul>

  479. <div class="versionchanged">

  480. <p><span class="versionmodified changed">Changed in version 3.5: </span><em>allow_abbrev</em> parameter was added.</p>

  481. </div>

  482. <div class="versionchanged">

  483. <p><span class="versionmodified changed">Changed in version 3.8: </span>In previous versions, <em>allow_abbrev</em> also disabled grouping of short

  484. flags such as <code class="docutils literal notranslate"><span class="pre">-vv</span></code> to mean <code class="docutils literal notranslate"><span class="pre">-v</span> <span class="pre">-v</span></code>.</p>

  485. </div>

  486. <div class="versionchanged">

  487. <p><span class="versionmodified changed">Changed in version 3.9: </span><em>exit_on_error</em> parameter was added.</p>

  488. </div>

  489. </dd></dl>

  490. 

  491. <p>The following sections describe how each of these are used.</p>

  492. <section id="prog">

  493. <span id="id1"></span><h3>prog<a class="headerlink" href="#prog" title="Link to this heading">¶</a></h3>

  494. <p>By default, <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> objects use <code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code> to determine

  495. how to display the name of the program in help messages.  This default is almost

  496. always desirable because it will make the help messages match how the program was

  497. invoked on the command line.  For example, consider a file named

  498. <code class="docutils literal notranslate"><span class="pre">myprogram.py</span></code> with the following code:</p>

  499. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">argparse</span>

  500. <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>

  501. <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;foo help&#39;</span><span class="p">)</span>

  502. <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>

  503. </pre></div>

  504. </div>

  505. <p>The help for this program will display <code class="docutils literal notranslate"><span class="pre">myprogram.py</span></code> as the program name

  506. (regardless of where the program was invoked from):</p>

  507. <div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>myprogram.py<span class="w"> </span>--help

  508. <span class="go">usage: myprogram.py [-h] [--foo FOO]</span>

  509. 

  510. <span class="go">options:</span>

  511. <span class="go"> -h, --help  show this help message and exit</span>

  512. <span class="go"> --foo FOO   foo help</span>

  513. <span class="gp">$ </span><span class="nb">cd</span><span class="w"> </span>..

  514. <span class="gp">$ </span>python<span class="w"> </span>subdir/myprogram.py<span class="w"> </span>--help

  515. <span class="go">usage: myprogram.py [-h] [--foo FOO]</span>

  516. 

  517. <span class="go">options:</span>

  518. <span class="go"> -h, --help  show this help message and exit</span>

  519. <span class="go"> --foo FOO   foo help</span>

  520. </pre></div>

  521. </div>

  522. <p>To change this default behavior, another value can be supplied using the

  523. <code class="docutils literal notranslate"><span class="pre">prog=</span></code> argument to <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>:</p>

  524. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;myprogram&#39;</span><span class="p">)</span>

  525. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>

  526. <span class="go">usage: myprogram [-h]</span>

  527. 

  528. <span class="go">options:</span>

  529. <span class="go"> -h, --help  show this help message and exit</span>

  530. </pre></div>

  531. </div>

  532. <p>Note that the program name, whether determined from <code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code> or from the

  533. <code class="docutils literal notranslate"><span class="pre">prog=</span></code> argument, is available to help messages using the <code class="docutils literal notranslate"><span class="pre">%(prog)s</span></code> format

  534. specifier.</p>

  535. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;myprogram&#39;</span><span class="p">)</span>

  536. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;foo of the </span><span class="si">%(prog)s</span><span class="s1"> program&#39;</span><span class="p">)</span>

  537. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>

  538. <span class="go">usage: myprogram [-h] [--foo FOO]</span>

  539. 

  540. <span class="go">options:</span>

  541. <span class="go"> -h, --help  show this help message and exit</span>

  542. <span class="go"> --foo FOO   foo of the myprogram program</span>

  543. </pre></div>

  544. </div>

  545. </section>

  546. <section id="usage">

  547. <h3>usage<a class="headerlink" href="#usage" title="Link to this heading">¶</a></h3>

  548. <p>By default, <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> calculates the usage message from the

  549. arguments it contains:</p>

  550. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">)</span>

  551. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;foo help&#39;</span><span class="p">)</span>

  552. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;+&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;bar help&#39;</span><span class="p">)</span>

  553. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>

  554. <span class="go">usage: PROG [-h] [--foo [FOO]] bar [bar ...]</span>

  555. 

  556. <span class="go">positional arguments:</span>

  557. <span class="go"> bar          bar help</span>

  558. 

  559. <span class="go">options:</span>

  560. <span class="go"> -h, --help   show this help message and exit</span>

  561. <span class="go"> --foo [FOO]  foo help</span>

  562. </pre></div>

  563. </div>

  564. <p>The default message can be overridden with the <code class="docutils literal notranslate"><span class="pre">usage=</span></code> keyword argument:</p>

  565. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">,</span> <span class="n">usage</span><span class="o">=</span><span class="s1">&#39;</span><span class="si">%(prog)s</span><span class="s1"> [options]&#39;</span><span class="p">)</span>

  566. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;foo help&#39;</span><span class="p">)</span>

  567. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;+&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;bar help&#39;</span><span class="p">)</span>

  568. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>

  569. <span class="go">usage: PROG [options]</span>

  570. 

  571. <span class="go">positional arguments:</span>

  572. <span class="go"> bar          bar help</span>

  573. 

  574. <span class="go">options:</span>

  575. <span class="go"> -h, --help   show this help message and exit</span>

  576. <span class="go"> --foo [FOO]  foo help</span>

  577. </pre></div>

  578. </div>

  579. <p>The <code class="docutils literal notranslate"><span class="pre">%(prog)s</span></code> format specifier is available to fill in the program name in

  580. your usage messages.</p>

  581. </section>

  582. <section id="description">

  583. <span id="id2"></span><h3>description<a class="headerlink" href="#description" title="Link to this heading">¶</a></h3>

  584. <p>Most calls to the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> constructor will use the

  585. <code class="docutils literal notranslate"><span class="pre">description=</span></code> keyword argument.  This argument gives a brief description of

  586. what the program does and how it works.  In help messages, the description is

  587. displayed between the command-line usage string and the help messages for the

  588. various arguments:</p>

  589. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">description</span><span class="o">=</span><span class="s1">&#39;A foo that bars&#39;</span><span class="p">)</span>

  590. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>

  591. <span class="go">usage: argparse.py [-h]</span>

  592. 

  593. <span class="go">A foo that bars</span>

  594. 

  595. <span class="go">options:</span>

  596. <span class="go"> -h, --help  show this help message and exit</span>

  597. </pre></div>

  598. </div>

  599. <p>By default, the description will be line-wrapped so that it fits within the

  600. given space.  To change this behavior, see the <a class="reference internal" href="#formatter-class">formatter_class</a> argument.</p>

  601. </section>

  602. <section id="epilog">

  603. <h3>epilog<a class="headerlink" href="#epilog" title="Link to this heading">¶</a></h3>

  604. <p>Some programs like to display additional description of the program after the

  605. description of the arguments.  Such text can be specified using the <code class="docutils literal notranslate"><span class="pre">epilog=</span></code>

  606. argument to <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>:</p>

  607. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  608. <span class="gp">... </span>    <span class="n">description</span><span class="o">=</span><span class="s1">&#39;A foo that bars&#39;</span><span class="p">,</span>

  609. <span class="gp">... </span>    <span class="n">epilog</span><span class="o">=</span><span class="s2">&quot;And that&#39;s how you&#39;d foo a bar&quot;</span><span class="p">)</span>

  610. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>

  611. <span class="go">usage: argparse.py [-h]</span>

  612. 

  613. <span class="go">A foo that bars</span>

  614. 

  615. <span class="go">options:</span>

  616. <span class="go"> -h, --help  show this help message and exit</span>

  617. 

  618. <span class="go">And that&#39;s how you&#39;d foo a bar</span>

  619. </pre></div>

  620. </div>

  621. <p>As with the <a class="reference internal" href="#description">description</a> argument, the <code class="docutils literal notranslate"><span class="pre">epilog=</span></code> text is by default

  622. line-wrapped, but this behavior can be adjusted with the <a class="reference internal" href="#formatter-class">formatter_class</a>

  623. argument to <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>.</p>

  624. </section>

  625. <section id="parents">

  626. <h3>parents<a class="headerlink" href="#parents" title="Link to this heading">¶</a></h3>

  627. <p>Sometimes, several parsers share a common set of arguments. Rather than

  628. repeating the definitions of these arguments, a single parser with all the

  629. shared arguments and passed to <code class="docutils literal notranslate"><span class="pre">parents=</span></code> argument to <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>

  630. can be used.  The <code class="docutils literal notranslate"><span class="pre">parents=</span></code> argument takes a list of <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>

  631. objects, collects all the positional and optional actions from them, and adds

  632. these actions to the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> object being constructed:</p>

  633. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">parent_parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">add_help</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>

  634. <span class="gp">&gt;&gt;&gt; </span><span class="n">parent_parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--parent&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>

  635. 

  636. <span class="gp">&gt;&gt;&gt; </span><span class="n">foo_parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">parents</span><span class="o">=</span><span class="p">[</span><span class="n">parent_parser</span><span class="p">])</span>

  637. <span class="gp">&gt;&gt;&gt; </span><span class="n">foo_parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">)</span>

  638. <span class="gp">&gt;&gt;&gt; </span><span class="n">foo_parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--parent&#39;</span><span class="p">,</span> <span class="s1">&#39;2&#39;</span><span class="p">,</span> <span class="s1">&#39;XXX&#39;</span><span class="p">])</span>

  639. <span class="go">Namespace(foo=&#39;XXX&#39;, parent=2)</span>

  640. 

  641. <span class="gp">&gt;&gt;&gt; </span><span class="n">bar_parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">parents</span><span class="o">=</span><span class="p">[</span><span class="n">parent_parser</span><span class="p">])</span>

  642. <span class="gp">&gt;&gt;&gt; </span><span class="n">bar_parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--bar&#39;</span><span class="p">)</span>

  643. <span class="gp">&gt;&gt;&gt; </span><span class="n">bar_parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--bar&#39;</span><span class="p">,</span> <span class="s1">&#39;YYY&#39;</span><span class="p">])</span>

  644. <span class="go">Namespace(bar=&#39;YYY&#39;, parent=None)</span>

  645. </pre></div>

  646. </div>

  647. <p>Note that most parent parsers will specify <code class="docutils literal notranslate"><span class="pre">add_help=False</span></code>.  Otherwise, the

  648. <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> will see two <code class="docutils literal notranslate"><span class="pre">-h/--help</span></code> options (one in the parent

  649. and one in the child) and raise an error.</p>

  650. <div class="admonition note">

  651. <p class="admonition-title">Note</p>

  652. <p>You must fully initialize the parsers before passing them via <code class="docutils literal notranslate"><span class="pre">parents=</span></code>.

  653. If you change the parent parsers after the child parser, those changes will

  654. not be reflected in the child.</p>

  655. </div>

  656. </section>

  657. <section id="formatter-class">

  658. <span id="id3"></span><h3>formatter_class<a class="headerlink" href="#formatter-class" title="Link to this heading">¶</a></h3>

  659. <p><a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> objects allow the help formatting to be customized by

  660. specifying an alternate formatting class.  Currently, there are four such

  661. classes:</p>

  662. <dl class="py class">

  663. <dt class="sig sig-object py" id="argparse.RawDescriptionHelpFormatter">

  664. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">argparse.</span></span><span class="sig-name descname"><span class="pre">RawDescriptionHelpFormatter</span></span><a class="headerlink" href="#argparse.RawDescriptionHelpFormatter" title="Link to this definition">¶</a></dt>

  665. <dt class="sig sig-object py" id="argparse.RawTextHelpFormatter">

  666. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">argparse.</span></span><span class="sig-name descname"><span class="pre">RawTextHelpFormatter</span></span><a class="headerlink" href="#argparse.RawTextHelpFormatter" title="Link to this definition">¶</a></dt>

  667. <dt class="sig sig-object py" id="argparse.ArgumentDefaultsHelpFormatter">

  668. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">argparse.</span></span><span class="sig-name descname"><span class="pre">ArgumentDefaultsHelpFormatter</span></span><a class="headerlink" href="#argparse.ArgumentDefaultsHelpFormatter" title="Link to this definition">¶</a></dt>

  669. <dt class="sig sig-object py" id="argparse.MetavarTypeHelpFormatter">

  670. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">argparse.</span></span><span class="sig-name descname"><span class="pre">MetavarTypeHelpFormatter</span></span><a class="headerlink" href="#argparse.MetavarTypeHelpFormatter" title="Link to this definition">¶</a></dt>

  671. <dd></dd></dl>

  672. 

  673. <p><a class="reference internal" href="#argparse.RawDescriptionHelpFormatter" title="argparse.RawDescriptionHelpFormatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawDescriptionHelpFormatter</span></code></a> and <a class="reference internal" href="#argparse.RawTextHelpFormatter" title="argparse.RawTextHelpFormatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawTextHelpFormatter</span></code></a> give

  674. more control over how textual descriptions are displayed.

  675. By default, <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> objects line-wrap the <a class="reference internal" href="#description">description</a> and

  676. <a class="reference internal" href="#epilog">epilog</a> texts in command-line help messages:</p>

  677. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  678. <span class="gp">... </span>    <span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">,</span>

  679. <span class="gp">... </span>    <span class="n">description</span><span class="o">=</span><span class="s1">&#39;&#39;&#39;this description</span>

  680. <span class="gp">... </span><span class="s1">        was indented weird</span>

  681. <span class="gp">... </span><span class="s1">            but that is okay&#39;&#39;&#39;</span><span class="p">,</span>

  682. <span class="gp">... </span>    <span class="n">epilog</span><span class="o">=</span><span class="s1">&#39;&#39;&#39;</span>

  683. <span class="gp">... </span><span class="s1">            likewise for this epilog whose whitespace will</span>

  684. <span class="gp">... </span><span class="s1">        be cleaned up and whose words will be wrapped</span>

  685. <span class="gp">... </span><span class="s1">        across a couple lines&#39;&#39;&#39;</span><span class="p">)</span>

  686. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>

  687. <span class="go">usage: PROG [-h]</span>

  688. 

  689. <span class="go">this description was indented weird but that is okay</span>

  690. 

  691. <span class="go">options:</span>

  692. <span class="go"> -h, --help  show this help message and exit</span>

  693. 

  694. <span class="go">likewise for this epilog whose whitespace will be cleaned up and whose words</span>

  695. <span class="go">will be wrapped across a couple lines</span>

  696. </pre></div>

  697. </div>

  698. <p>Passing <a class="reference internal" href="#argparse.RawDescriptionHelpFormatter" title="argparse.RawDescriptionHelpFormatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawDescriptionHelpFormatter</span></code></a> as <code class="docutils literal notranslate"><span class="pre">formatter_class=</span></code>

  699. indicates that <a class="reference internal" href="#description">description</a> and <a class="reference internal" href="#epilog">epilog</a> are already correctly formatted and

  700. should not be line-wrapped:</p>

  701. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  702. <span class="gp">... </span>    <span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">,</span>

  703. <span class="gp">... </span>    <span class="n">formatter_class</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">RawDescriptionHelpFormatter</span><span class="p">,</span>

  704. <span class="gp">... </span>    <span class="n">description</span><span class="o">=</span><span class="n">textwrap</span><span class="o">.</span><span class="n">dedent</span><span class="p">(</span><span class="s1">&#39;&#39;&#39;</span><span class="se">\</span>

  705. <span class="gp">... </span><span class="s1">        Please do not mess up this text!</span>

  706. <span class="gp">... </span><span class="s1">        --------------------------------</span>

  707. <span class="gp">... </span><span class="s1">            I have indented it</span>

  708. <span class="gp">... </span><span class="s1">            exactly the way</span>

  709. <span class="gp">... </span><span class="s1">            I want it</span>

  710. <span class="gp">... </span><span class="s1">        &#39;&#39;&#39;</span><span class="p">))</span>

  711. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>

  712. <span class="go">usage: PROG [-h]</span>

  713. 

  714. <span class="go">Please do not mess up this text!</span>

  715. <span class="go">--------------------------------</span>

  716. <span class="go">   I have indented it</span>

  717. <span class="go">   exactly the way</span>

  718. <span class="go">   I want it</span>

  719. 

  720. <span class="go">options:</span>

  721. <span class="go"> -h, --help  show this help message and exit</span>

  722. </pre></div>

  723. </div>

  724. <p><a class="reference internal" href="#argparse.RawTextHelpFormatter" title="argparse.RawTextHelpFormatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawTextHelpFormatter</span></code></a> maintains whitespace for all sorts of help text,

  725. including argument descriptions. However, multiple new lines are replaced with

  726. one. If you wish to preserve multiple blank lines, add spaces between the

  727. newlines.</p>

  728. <p><a class="reference internal" href="#argparse.ArgumentDefaultsHelpFormatter" title="argparse.ArgumentDefaultsHelpFormatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentDefaultsHelpFormatter</span></code></a> automatically adds information about

  729. default values to each of the argument help messages:</p>

  730. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  731. <span class="gp">... </span>    <span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">,</span>

  732. <span class="gp">... </span>    <span class="n">formatter_class</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentDefaultsHelpFormatter</span><span class="p">)</span>

  733. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">42</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;FOO!&#39;</span><span class="p">)</span>

  734. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;*&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;BAR!&#39;</span><span class="p">)</span>

  735. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>

  736. <span class="go">usage: PROG [-h] [--foo FOO] [bar ...]</span>

  737. 

  738. <span class="go">positional arguments:</span>

  739. <span class="go"> bar         BAR! (default: [1, 2, 3])</span>

  740. 

  741. <span class="go">options:</span>

  742. <span class="go"> -h, --help  show this help message and exit</span>

  743. <span class="go"> --foo FOO   FOO! (default: 42)</span>

  744. </pre></div>

  745. </div>

  746. <p><a class="reference internal" href="#argparse.MetavarTypeHelpFormatter" title="argparse.MetavarTypeHelpFormatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">MetavarTypeHelpFormatter</span></code></a> uses the name of the <a class="reference internal" href="#type">type</a> argument for each

  747. argument as the display name for its values (rather than using the <a class="reference internal" href="#dest">dest</a>

  748. as the regular formatter does):</p>

  749. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  750. <span class="gp">... </span>    <span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">,</span>

  751. <span class="gp">... </span>    <span class="n">formatter_class</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">MetavarTypeHelpFormatter</span><span class="p">)</span>

  752. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>

  753. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">float</span><span class="p">)</span>

  754. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>

  755. <span class="go">usage: PROG [-h] [--foo int] float</span>

  756. 

  757. <span class="go">positional arguments:</span>

  758. <span class="go">  float</span>

  759. 

  760. <span class="go">options:</span>

  761. <span class="go">  -h, --help  show this help message and exit</span>

  762. <span class="go">  --foo int</span>

  763. </pre></div>

  764. </div>

  765. </section>

  766. <section id="prefix-chars">

  767. <h3>prefix_chars<a class="headerlink" href="#prefix-chars" title="Link to this heading">¶</a></h3>

  768. <p>Most command-line options will use <code class="docutils literal notranslate"><span class="pre">-</span></code> as the prefix, e.g. <code class="docutils literal notranslate"><span class="pre">-f/--foo</span></code>.

  769. Parsers that need to support different or additional prefix

  770. characters, e.g. for options

  771. like <code class="docutils literal notranslate"><span class="pre">+f</span></code> or <code class="docutils literal notranslate"><span class="pre">/foo</span></code>, may specify them using the <code class="docutils literal notranslate"><span class="pre">prefix_chars=</span></code> argument

  772. to the ArgumentParser constructor:</p>

  773. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">,</span> <span class="n">prefix_chars</span><span class="o">=</span><span class="s1">&#39;-+&#39;</span><span class="p">)</span>

  774. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;+f&#39;</span><span class="p">)</span>

  775. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;++bar&#39;</span><span class="p">)</span>

  776. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;+f X ++bar Y&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>

  777. <span class="go">Namespace(bar=&#39;Y&#39;, f=&#39;X&#39;)</span>

  778. </pre></div>

  779. </div>

  780. <p>The <code class="docutils literal notranslate"><span class="pre">prefix_chars=</span></code> argument defaults to <code class="docutils literal notranslate"><span class="pre">'-'</span></code>. Supplying a set of

  781. characters that does not include <code class="docutils literal notranslate"><span class="pre">-</span></code> will cause <code class="docutils literal notranslate"><span class="pre">-f/--foo</span></code> options to be

  782. disallowed.</p>

  783. </section>

  784. <section id="fromfile-prefix-chars">

  785. <h3>fromfile_prefix_chars<a class="headerlink" href="#fromfile-prefix-chars" title="Link to this heading">¶</a></h3>

  786. <p>Sometimes, when dealing with a particularly long argument list, it

  787. may make sense to keep the list of arguments in a file rather than typing it out

  788. at the command line.  If the <code class="docutils literal notranslate"><span class="pre">fromfile_prefix_chars=</span></code> argument is given to the

  789. <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> constructor, then arguments that start with any of the

  790. specified characters will be treated as files, and will be replaced by the

  791. arguments they contain.  For example:</p>

  792. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;args.txt&#39;</span><span class="p">,</span> <span class="s1">&#39;w&#39;</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="n">sys</span><span class="o">.</span><span class="n">getfilesystemencoding</span><span class="p">())</span> <span class="k">as</span> <span class="n">fp</span><span class="p">:</span>

  793. <span class="gp">... </span>    <span class="n">fp</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s1">&#39;-f</span><span class="se">\n</span><span class="s1">bar&#39;</span><span class="p">)</span>

  794. <span class="gp">...</span>

  795. <span class="gp">&gt;&gt;&gt; </span><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><span class="n">fromfile_prefix_chars</span><span class="o">=</span><span class="s1">&#39;@&#39;</span><span class="p">)</span>

  796. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-f&#39;</span><span class="p">)</span>

  797. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-f&#39;</span><span class="p">,</span> <span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="s1">&#39;@args.txt&#39;</span><span class="p">])</span>

  798. <span class="go">Namespace(f=&#39;bar&#39;)</span>

  799. </pre></div>

  800. </div>

  801. <p>Arguments read from a file must by default be one per line (but see also

  802. <a class="reference internal" href="#argparse.ArgumentParser.convert_arg_line_to_args" title="argparse.ArgumentParser.convert_arg_line_to_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">convert_arg_line_to_args()</span></code></a>) and are treated as if they

  803. were in the same place as the original file referencing argument on the command

  804. line.  So in the example above, the expression <code class="docutils literal notranslate"><span class="pre">['-f',</span> <span class="pre">'foo',</span> <span class="pre">'&#64;args.txt']</span></code>

  805. is considered equivalent to the expression <code class="docutils literal notranslate"><span class="pre">['-f',</span> <span class="pre">'foo',</span> <span class="pre">'-f',</span> <span class="pre">'bar']</span></code>.</p>

  806. <p><a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> uses <a class="reference internal" href="../glossary.html#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem encoding and error handler</span></a>

  807. to read the file containing arguments.</p>

  808. <p>The <code class="docutils literal notranslate"><span class="pre">fromfile_prefix_chars=</span></code> argument defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>, meaning that

  809. arguments will never be treated as file references.</p>

  810. <div class="versionchanged">

  811. <p><span class="versionmodified changed">Changed in version 3.12: </span><a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> changed encoding and errors to read arguments files

  812. from default (e.g. <a class="reference internal" href="locale.html#locale.getpreferredencoding" title="locale.getpreferredencoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">locale.getpreferredencoding(False)</span></code></a> and

  813. <code class="docutils literal notranslate"><span class="pre">&quot;strict&quot;</span></code>) to <a class="reference internal" href="../glossary.html#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem encoding and error handler</span></a>.

  814. Arguments file should be encoded in UTF-8 instead of ANSI Codepage on Windows.</p>

  815. </div>

  816. </section>

  817. <section id="argument-default">

  818. <h3>argument_default<a class="headerlink" href="#argument-default" title="Link to this heading">¶</a></h3>

  819. <p>Generally, argument defaults are specified either by passing a default to

  820. <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> or by calling the

  821. <a class="reference internal" href="#argparse.ArgumentParser.set_defaults" title="argparse.ArgumentParser.set_defaults"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_defaults()</span></code></a> methods with a specific set of name-value

  822. pairs.  Sometimes however, it may be useful to specify a single parser-wide

  823. default for arguments.  This can be accomplished by passing the

  824. <code class="docutils literal notranslate"><span class="pre">argument_default=</span></code> keyword argument to <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>.  For example,

  825. to globally suppress attribute creation on <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a>

  826. calls, we supply <code class="docutils literal notranslate"><span class="pre">argument_default=SUPPRESS</span></code>:</p>

  827. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">argument_default</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">SUPPRESS</span><span class="p">)</span>

  828. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">)</span>

  829. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</span><span class="p">)</span>

  830. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;1&#39;</span><span class="p">,</span> <span class="s1">&#39;BAR&#39;</span><span class="p">])</span>

  831. <span class="go">Namespace(bar=&#39;BAR&#39;, foo=&#39;1&#39;)</span>

  832. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>

  833. <span class="go">Namespace()</span>

  834. </pre></div>

  835. </div>

  836. </section>

  837. <section id="allow-abbrev">

  838. <span id="id4"></span><h3>allow_abbrev<a class="headerlink" href="#allow-abbrev" title="Link to this heading">¶</a></h3>

  839. <p>Normally, when you pass an argument list to the

  840. <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> method of an <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>,

  841. it <a class="reference internal" href="#prefix-matching"><span class="std std-ref">recognizes abbreviations</span></a> of long options.</p>

  842. <p>This feature can be disabled by setting <code class="docutils literal notranslate"><span class="pre">allow_abbrev</span></code> to <code class="docutils literal notranslate"><span class="pre">False</span></code>:</p>

  843. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">,</span> <span class="n">allow_abbrev</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>

  844. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foobar&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_true&#39;</span><span class="p">)</span>

  845. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foonley&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_false&#39;</span><span class="p">)</span>

  846. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foon&#39;</span><span class="p">])</span>

  847. <span class="go">usage: PROG [-h] [--foobar] [--foonley]</span>

  848. <span class="go">PROG: error: unrecognized arguments: --foon</span>

  849. </pre></div>

  850. </div>

  851. <div class="versionadded">

  852. <p><span class="versionmodified added">New in version 3.5.</span></p>

  853. </div>

  854. </section>

  855. <section id="conflict-handler">

  856. <h3>conflict_handler<a class="headerlink" href="#conflict-handler" title="Link to this heading">¶</a></h3>

  857. <p><a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> objects do not allow two actions with the same option

  858. string.  By default, <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> objects raise an exception if an

  859. attempt is made to create an argument with an option string that is already in

  860. use:</p>

  861. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">)</span>

  862. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-f&#39;</span><span class="p">,</span> <span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;old foo help&#39;</span><span class="p">)</span>

  863. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;new foo help&#39;</span><span class="p">)</span>

  864. <span class="gt">Traceback (most recent call last):</span>

  865. <span class="gr"> ..</span>

  866. <span class="gr">ArgumentError</span>: <span class="n">argument --foo: conflicting option string(s): --foo</span>

  867. </pre></div>

  868. </div>

  869. <p>Sometimes (e.g. when using <a class="reference internal" href="#parents">parents</a>) it may be useful to simply override any

  870. older arguments with the same option string.  To get this behavior, the value

  871. <code class="docutils literal notranslate"><span class="pre">'resolve'</span></code> can be supplied to the <code class="docutils literal notranslate"><span class="pre">conflict_handler=</span></code> argument of

  872. <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>:</p>

  873. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">,</span> <span class="n">conflict_handler</span><span class="o">=</span><span class="s1">&#39;resolve&#39;</span><span class="p">)</span>

  874. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-f&#39;</span><span class="p">,</span> <span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;old foo help&#39;</span><span class="p">)</span>

  875. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;new foo help&#39;</span><span class="p">)</span>

  876. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>

  877. <span class="go">usage: PROG [-h] [-f FOO] [--foo FOO]</span>

  878. 

  879. <span class="go">options:</span>

  880. <span class="go"> -h, --help  show this help message and exit</span>

  881. <span class="go"> -f FOO      old foo help</span>

  882. <span class="go"> --foo FOO   new foo help</span>

  883. </pre></div>

  884. </div>

  885. <p>Note that <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> objects only remove an action if all of its

  886. option strings are overridden.  So, in the example above, the old <code class="docutils literal notranslate"><span class="pre">-f/--foo</span></code>

  887. action is retained as the <code class="docutils literal notranslate"><span class="pre">-f</span></code> action, because only the <code class="docutils literal notranslate"><span class="pre">--foo</span></code> option

  888. string was overridden.</p>

  889. </section>

  890. <section id="add-help">

  891. <h3>add_help<a class="headerlink" href="#add-help" title="Link to this heading">¶</a></h3>

  892. <p>By default, ArgumentParser objects add an option which simply displays

  893. the parser’s help message. For example, consider a file named

  894. <code class="docutils literal notranslate"><span class="pre">myprogram.py</span></code> containing the following code:</p>

  895. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">argparse</span>

  896. <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>

  897. <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;foo help&#39;</span><span class="p">)</span>

  898. <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>

  899. </pre></div>

  900. </div>

  901. <p>If <code class="docutils literal notranslate"><span class="pre">-h</span></code> or <code class="docutils literal notranslate"><span class="pre">--help</span></code> is supplied at the command line, the ArgumentParser

  902. help will be printed:</p>

  903. <div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>myprogram.py<span class="w"> </span>--help

  904. <span class="go">usage: myprogram.py [-h] [--foo FOO]</span>

  905. 

  906. <span class="go">options:</span>

  907. <span class="go"> -h, --help  show this help message and exit</span>

  908. <span class="go"> --foo FOO   foo help</span>

  909. </pre></div>

  910. </div>

  911. <p>Occasionally, it may be useful to disable the addition of this help option.

  912. This can be achieved by passing <code class="docutils literal notranslate"><span class="pre">False</span></code> as the <code class="docutils literal notranslate"><span class="pre">add_help=</span></code> argument to

  913. <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>:</p>

  914. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">,</span> <span class="n">add_help</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>

  915. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;foo help&#39;</span><span class="p">)</span>

  916. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>

  917. <span class="go">usage: PROG [--foo FOO]</span>

  918. 

  919. <span class="go">options:</span>

  920. <span class="go"> --foo FOO  foo help</span>

  921. </pre></div>

  922. </div>

  923. <p>The help option is typically <code class="docutils literal notranslate"><span class="pre">-h/--help</span></code>. The exception to this is

  924. if the <code class="docutils literal notranslate"><span class="pre">prefix_chars=</span></code> is specified and does not include <code class="docutils literal notranslate"><span class="pre">-</span></code>, in

  925. which case <code class="docutils literal notranslate"><span class="pre">-h</span></code> and <code class="docutils literal notranslate"><span class="pre">--help</span></code> are not valid options.  In

  926. this case, the first character in <code class="docutils literal notranslate"><span class="pre">prefix_chars</span></code> is used to prefix

  927. the help options:</p>

  928. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">,</span> <span class="n">prefix_chars</span><span class="o">=</span><span class="s1">&#39;+/&#39;</span><span class="p">)</span>

  929. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>

  930. <span class="go">usage: PROG [+h]</span>

  931. 

  932. <span class="go">options:</span>

  933. <span class="go">  +h, ++help  show this help message and exit</span>

  934. </pre></div>

  935. </div>

  936. </section>

  937. <section id="exit-on-error">

  938. <h3>exit_on_error<a class="headerlink" href="#exit-on-error" title="Link to this heading">¶</a></h3>

  939. <p>Normally, when you pass an invalid argument list to the <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a>

  940. method of an <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>, it will exit with error info.</p>

  941. <p>If the user would like to catch errors manually, the feature can be enabled by setting

  942. <code class="docutils literal notranslate"><span class="pre">exit_on_error</span></code> to <code class="docutils literal notranslate"><span class="pre">False</span></code>:</p>

  943. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">exit_on_error</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>

  944. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--integers&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>

  945. <span class="go">_StoreAction(option_strings=[&#39;--integers&#39;], dest=&#39;integers&#39;, nargs=None, const=None, default=None, type=&lt;class &#39;int&#39;&gt;, choices=None, help=None, metavar=None)</span>

  946. <span class="gp">&gt;&gt;&gt; </span><span class="k">try</span><span class="p">:</span>

  947. <span class="gp">... </span>    <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;--integers a&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>

  948. <span class="gp">... </span><span class="k">except</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentError</span><span class="p">:</span>

  949. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Catching an argumentError&#39;</span><span class="p">)</span>

  950. <span class="gp">...</span>

  951. <span class="go">Catching an argumentError</span>

  952. </pre></div>

  953. </div>

  954. <div class="versionadded">

  955. <p><span class="versionmodified added">New in version 3.9.</span></p>

  956. </div>

  957. </section>

  958. </section>

  959. <section id="the-add-argument-method">

  960. <h2>The add_argument() method<a class="headerlink" href="#the-add-argument-method" title="Link to this heading">¶</a></h2>

  961. <dl class="py method">

  962. <dt class="sig sig-object py" id="argparse.ArgumentParser.add_argument">

  963. <span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">add_argument</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span> <span class="pre">or</span> <span class="pre">flags...</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">action</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">nargs</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">const</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">default</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">type</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">choices</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">required</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">help</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">metavar</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">dest</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.add_argument" title="Link to this definition">¶</a></dt>

  964. <dd><p>Define how a single command-line argument should be parsed.  Each parameter

  965. has its own more detailed description below, but in short they are:</p>

  966. <ul class="simple">

  967. <li><p><a class="reference internal" href="#id5">name or flags</a> - Either a name or a list of option strings, e.g. <code class="docutils literal notranslate"><span class="pre">foo</span></code>

  968. or <code class="docutils literal notranslate"><span class="pre">-f,</span> <span class="pre">--foo</span></code>.</p></li>

  969. <li><p><a class="reference internal" href="#action">action</a> - The basic type of action to be taken when this argument is

  970. encountered at the command line.</p></li>

  971. <li><p><a class="reference internal" href="#nargs">nargs</a> - The number of command-line arguments that should be consumed.</p></li>

  972. <li><p><a class="reference internal" href="#const">const</a> - A constant value required by some <a class="reference internal" href="#action">action</a> and <a class="reference internal" href="#nargs">nargs</a> selections.</p></li>

  973. <li><p><a class="reference internal" href="#default">default</a> - The value produced if the argument is absent from the

  974. command line and if it is absent from the namespace object.</p></li>

  975. <li><p><a class="reference internal" href="#type">type</a> - The type to which the command-line argument should be converted.</p></li>

  976. <li><p><a class="reference internal" href="#choices">choices</a> - A sequence of the allowable values for the argument.</p></li>

  977. <li><p><a class="reference internal" href="#required">required</a> - Whether or not the command-line option may be omitted

  978. (optionals only).</p></li>

  979. <li><p><a class="reference internal" href="#help">help</a> - A brief description of what the argument does.</p></li>

  980. <li><p><a class="reference internal" href="#metavar">metavar</a> - A name for the argument in usage messages.</p></li>

  981. <li><p><a class="reference internal" href="#dest">dest</a> - The name of the attribute to be added to the object returned by

  982. <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a>.</p></li>

  983. </ul>

  984. </dd></dl>

  985. 

  986. <p>The following sections describe how each of these are used.</p>

  987. <section id="name-or-flags">

  988. <span id="id5"></span><h3>name or flags<a class="headerlink" href="#name-or-flags" title="Link to this heading">¶</a></h3>

  989. <p>The <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> method must know whether an optional

  990. argument, like <code class="docutils literal notranslate"><span class="pre">-f</span></code> or <code class="docutils literal notranslate"><span class="pre">--foo</span></code>, or a positional argument, like a list of

  991. filenames, is expected.  The first arguments passed to

  992. <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> must therefore be either a series of

  993. flags, or a simple argument name.</p>

  994. <p>For example, an optional argument could be created like:</p>

  995. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-f&#39;</span><span class="p">,</span> <span class="s1">&#39;--foo&#39;</span><span class="p">)</span>

  996. </pre></div>

  997. </div>

  998. <p>while a positional argument could be created like:</p>

  999. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>

  1000. </pre></div>

  1001. </div>

  1002. <p>When <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> is called, optional arguments will be

  1003. identified by the <code class="docutils literal notranslate"><span class="pre">-</span></code> prefix, and the remaining arguments will be assumed to

  1004. be positional:</p>

  1005. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">)</span>

  1006. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-f&#39;</span><span class="p">,</span> <span class="s1">&#39;--foo&#39;</span><span class="p">)</span>

  1007. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>

  1008. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;BAR&#39;</span><span class="p">])</span>

  1009. <span class="go">Namespace(bar=&#39;BAR&#39;, foo=None)</span>

  1010. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;BAR&#39;</span><span class="p">,</span> <span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;FOO&#39;</span><span class="p">])</span>

  1011. <span class="go">Namespace(bar=&#39;BAR&#39;, foo=&#39;FOO&#39;)</span>

  1012. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;FOO&#39;</span><span class="p">])</span>

  1013. <span class="go">usage: PROG [-h] [-f FOO] bar</span>

  1014. <span class="go">PROG: error: the following arguments are required: bar</span>

  1015. </pre></div>

  1016. </div>

  1017. </section>

  1018. <section id="action">

  1019. <span id="id6"></span><h3>action<a class="headerlink" href="#action" title="Link to this heading">¶</a></h3>

  1020. <p><a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> objects associate command-line arguments with actions.  These

  1021. actions can do just about anything with the command-line arguments associated with

  1022. them, though most actions simply add an attribute to the object returned by

  1023. <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a>.  The <code class="docutils literal notranslate"><span class="pre">action</span></code> keyword argument specifies

  1024. how the command-line arguments should be handled. The supplied actions are:</p>

  1025. <ul>

  1026. <li><p><code class="docutils literal notranslate"><span class="pre">'store'</span></code> - This just stores the argument’s value.  This is the default

  1027. action. For example:</p>

  1028. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1029. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">)</span>

  1030. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;--foo 1&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>

  1031. <span class="go">Namespace(foo=&#39;1&#39;)</span>

  1032. </pre></div>

  1033. </div>

  1034. </li>

  1035. <li><p><code class="docutils literal notranslate"><span class="pre">'store_const'</span></code> - This stores the value specified by the <a class="reference internal" href="#const">const</a> keyword

  1036. argument; note that the <a class="reference internal" href="#const">const</a> keyword argument defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>.  The

  1037. <code class="docutils literal notranslate"><span class="pre">'store_const'</span></code> action is most commonly used with optional arguments that

  1038. specify some sort of flag.  For example:</p>

  1039. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1040. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_const&#39;</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="mi">42</span><span class="p">)</span>

  1041. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">])</span>

  1042. <span class="go">Namespace(foo=42)</span>

  1043. </pre></div>

  1044. </div>

  1045. </li>

  1046. <li><p><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> - These are special cases of

  1047. <code class="docutils literal notranslate"><span class="pre">'store_const'</span></code> used for storing the values <code class="docutils literal notranslate"><span class="pre">True</span></code> and <code class="docutils literal notranslate"><span class="pre">False</span></code>

  1048. respectively.  In addition, they create default values of <code class="docutils literal notranslate"><span class="pre">False</span></code> and

  1049. <code class="docutils literal notranslate"><span class="pre">True</span></code> respectively.  For example:</p>

  1050. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1051. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_true&#39;</span><span class="p">)</span>

  1052. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--bar&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_false&#39;</span><span class="p">)</span>

  1053. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--baz&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_false&#39;</span><span class="p">)</span>

  1054. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;--foo --bar&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>

  1055. <span class="go">Namespace(foo=True, bar=False, baz=True)</span>

  1056. </pre></div>

  1057. </div>

  1058. </li>

  1059. <li><p><code class="docutils literal notranslate"><span class="pre">'append'</span></code> - This stores a list, and appends each argument value to the

  1060. list. It is useful to allow an option to be specified multiple times.

  1061. If the default value is non-empty, the default elements will be present

  1062. in the parsed value for the option, with any values from the

  1063. command line appended after those default values. Example usage:</p>

  1064. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1065. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;append&#39;</span><span class="p">)</span>

  1066. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;--foo 1 --foo 2&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>

  1067. <span class="go">Namespace(foo=[&#39;1&#39;, &#39;2&#39;])</span>

  1068. </pre></div>

  1069. </div>

  1070. </li>

  1071. <li><p><code class="docutils literal notranslate"><span class="pre">'append_const'</span></code> - This stores a list, and appends the value specified by

  1072. the <a class="reference internal" href="#const">const</a> keyword argument to the list; note that the <a class="reference internal" href="#const">const</a> keyword

  1073. argument defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>. The <code class="docutils literal notranslate"><span class="pre">'append_const'</span></code> action is typically

  1074. useful when multiple arguments need to store constants to the same list. For

  1075. example:</p>

  1076. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1077. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--str&#39;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">&#39;types&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;append_const&#39;</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="nb">str</span><span class="p">)</span>

  1078. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--int&#39;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">&#39;types&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;append_const&#39;</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>

  1079. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;--str --int&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>

  1080. <span class="go">Namespace(types=[&lt;class &#39;str&#39;&gt;, &lt;class &#39;int&#39;&gt;])</span>

  1081. </pre></div>

  1082. </div>

  1083. </li>

  1084. <li><p><code class="docutils literal notranslate"><span class="pre">'count'</span></code> - This counts the number of times a keyword argument occurs. For

  1085. example, this is useful for increasing verbosity levels:</p>

  1086. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1087. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--verbose&#39;</span><span class="p">,</span> <span class="s1">&#39;-v&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;count&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>

  1088. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-vvv&#39;</span><span class="p">])</span>

  1089. <span class="go">Namespace(verbose=3)</span>

  1090. </pre></div>

  1091. </div>

  1092. <p>Note, the <em>default</em> will be <code class="docutils literal notranslate"><span class="pre">None</span></code> unless explicitly set to <em>0</em>.</p>

  1093. </li>

  1094. <li><p><code class="docutils literal notranslate"><span class="pre">'help'</span></code> - This prints a complete help message for all the options in the

  1095. current parser and then exits. By default a help action is automatically

  1096. added to the parser. See <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> for details of how the

  1097. output is created.</p></li>

  1098. <li><p><code class="docutils literal notranslate"><span class="pre">'version'</span></code> - This expects a <code class="docutils literal notranslate"><span class="pre">version=</span></code> keyword argument in the

  1099. <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> call, and prints version information

  1100. and exits when invoked:</p>

  1101. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">argparse</span>

  1102. <span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">)</span>

  1103. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--version&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;version&#39;</span><span class="p">,</span> <span class="n">version</span><span class="o">=</span><span class="s1">&#39;</span><span class="si">%(prog)s</span><span class="s1"> 2.0&#39;</span><span class="p">)</span>

  1104. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--version&#39;</span><span class="p">])</span>

  1105. <span class="go">PROG 2.0</span>

  1106. </pre></div>

  1107. </div>

  1108. </li>

  1109. <li><p><code class="docutils literal notranslate"><span class="pre">'extend'</span></code> - This stores a list, and extends each argument value to the

  1110. list.

  1111. Example usage:</p>

  1112. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1113. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s2">&quot;--foo&quot;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">&quot;extend&quot;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s2">&quot;+&quot;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">str</span><span class="p">)</span>

  1114. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s2">&quot;--foo&quot;</span><span class="p">,</span> <span class="s2">&quot;f1&quot;</span><span class="p">,</span> <span class="s2">&quot;--foo&quot;</span><span class="p">,</span> <span class="s2">&quot;f2&quot;</span><span class="p">,</span> <span class="s2">&quot;f3&quot;</span><span class="p">,</span> <span class="s2">&quot;f4&quot;</span><span class="p">])</span>

  1115. <span class="go">Namespace(foo=[&#39;f1&#39;, &#39;f2&#39;, &#39;f3&#39;, &#39;f4&#39;])</span>

  1116. </pre></div>

  1117. </div>

  1118. <div class="versionadded">

  1119. <p><span class="versionmodified added">New in version 3.8.</span></p>

  1120. </div>

  1121. </li>

  1122. </ul>

  1123. <p>You may also specify an arbitrary action by passing an Action subclass or

  1124. other object that implements the same interface. The <code class="docutils literal notranslate"><span class="pre">BooleanOptionalAction</span></code>

  1125. is available in <code class="docutils literal notranslate"><span class="pre">argparse</span></code> and adds support for boolean actions such as

  1126. <code class="docutils literal notranslate"><span class="pre">--foo</span></code> and <code class="docutils literal notranslate"><span class="pre">--no-foo</span></code>:</p>

  1127. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">argparse</span>

  1128. <span class="gp">&gt;&gt;&gt; </span><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>

  1129. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">BooleanOptionalAction</span><span class="p">)</span>

  1130. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--no-foo&#39;</span><span class="p">])</span>

  1131. <span class="go">Namespace(foo=False)</span>

  1132. </pre></div>

  1133. </div>

  1134. <div class="versionadded">

  1135. <p><span class="versionmodified added">New in version 3.9.</span></p>

  1136. </div>

  1137. <p>The recommended way to create a custom action is to extend <a class="reference internal" href="#argparse.Action" title="argparse.Action"><code class="xref py py-class docutils literal notranslate"><span class="pre">Action</span></code></a>,

  1138. overriding the <code class="docutils literal notranslate"><span class="pre">__call__</span></code> method and optionally the <code class="docutils literal notranslate"><span class="pre">__init__</span></code> and

  1139. <code class="docutils literal notranslate"><span class="pre">format_usage</span></code> methods.</p>

  1140. <p>An example of a custom action:</p>

  1141. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">FooAction</span><span class="p">(</span><span class="n">argparse</span><span class="o">.</span><span class="n">Action</span><span class="p">):</span>

  1142. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">option_strings</span><span class="p">,</span> <span class="n">dest</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  1143. <span class="gp">... </span>        <span class="k">if</span> <span class="n">nargs</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>

  1144. <span class="gp">... </span>            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;nargs not allowed&quot;</span><span class="p">)</span>

  1145. <span class="gp">... </span>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="n">option_strings</span><span class="p">,</span> <span class="n">dest</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>

  1146. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__call__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">parser</span><span class="p">,</span> <span class="n">namespace</span><span class="p">,</span> <span class="n">values</span><span class="p">,</span> <span class="n">option_string</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  1147. <span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%r</span><span class="s1"> </span><span class="si">%r</span><span class="s1"> </span><span class="si">%r</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">namespace</span><span class="p">,</span> <span class="n">values</span><span class="p">,</span> <span class="n">option_string</span><span class="p">))</span>

  1148. <span class="gp">... </span>        <span class="nb">setattr</span><span class="p">(</span><span class="n">namespace</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">dest</span><span class="p">,</span> <span class="n">values</span><span class="p">)</span>

  1149. <span class="gp">...</span>

  1150. <span class="gp">&gt;&gt;&gt; </span><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>

  1151. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="n">FooAction</span><span class="p">)</span>

  1152. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="n">FooAction</span><span class="p">)</span>

  1153. <span class="gp">&gt;&gt;&gt; </span><span class="n">args</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;1 --foo 2&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>

  1154. <span class="go">Namespace(bar=None, foo=None) &#39;1&#39; None</span>

  1155. <span class="go">Namespace(bar=&#39;1&#39;, foo=None) &#39;2&#39; &#39;--foo&#39;</span>

  1156. <span class="gp">&gt;&gt;&gt; </span><span class="n">args</span>

  1157. <span class="go">Namespace(bar=&#39;1&#39;, foo=&#39;2&#39;)</span>

  1158. </pre></div>

  1159. </div>

  1160. <p>For more details, see <a class="reference internal" href="#argparse.Action" title="argparse.Action"><code class="xref py py-class docutils literal notranslate"><span class="pre">Action</span></code></a>.</p>

  1161. </section>

  1162. <section id="nargs">

  1163. <span id="id7"></span><h3>nargs<a class="headerlink" href="#nargs" title="Link to this heading">¶</a></h3>

  1164. <p>ArgumentParser objects usually associate a single command-line argument with a

  1165. single action to be taken.  The <code class="docutils literal notranslate"><span class="pre">nargs</span></code> keyword argument associates a

  1166. different number of command-line arguments with a single action.

  1167. See also <a class="reference internal" href="../howto/argparse.html#specifying-ambiguous-arguments"><span class="std std-ref">Specifying ambiguous arguments</span></a>. The supported values are:</p>

  1168. <ul>

  1169. <li><p><code class="docutils literal notranslate"><span class="pre">N</span></code> (an integer).  <code class="docutils literal notranslate"><span class="pre">N</span></code> arguments from the command line will be gathered

  1170. together into a list.  For example:</p>

  1171. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1172. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>

  1173. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>

  1174. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;c --foo a b&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>

  1175. <span class="go">Namespace(bar=[&#39;c&#39;], foo=[&#39;a&#39;, &#39;b&#39;])</span>

  1176. </pre></div>

  1177. </div>

  1178. <p>Note that <code class="docutils literal notranslate"><span class="pre">nargs=1</span></code> produces a list of one item.  This is different from

  1179. the default, in which the item is produced by itself.</p>

  1180. </li>

  1181. </ul>

  1182. <ul id="index-0">

  1183. <li><p><code class="docutils literal notranslate"><span class="pre">'?'</span></code>. One argument will be consumed from the command line if possible, and

  1184. produced as a single item.  If no command-line argument is present, the value from

  1185. <a class="reference internal" href="#default">default</a> will be produced.  Note that for optional arguments, there is an

  1186. additional case - the option string is present but not followed by a

  1187. command-line argument.  In this case the value from <a class="reference internal" href="#const">const</a> will be produced.  Some

  1188. examples to illustrate this:</p>

  1189. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1190. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s1">&#39;c&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">&#39;d&#39;</span><span class="p">)</span>

  1191. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">&#39;d&#39;</span><span class="p">)</span>

  1192. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;XX&#39;</span><span class="p">,</span> <span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;YY&#39;</span><span class="p">])</span>

  1193. <span class="go">Namespace(bar=&#39;XX&#39;, foo=&#39;YY&#39;)</span>

  1194. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;XX&#39;</span><span class="p">,</span> <span class="s1">&#39;--foo&#39;</span><span class="p">])</span>

  1195. <span class="go">Namespace(bar=&#39;XX&#39;, foo=&#39;c&#39;)</span>

  1196. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>

  1197. <span class="go">Namespace(bar=&#39;d&#39;, foo=&#39;d&#39;)</span>

  1198. </pre></div>

  1199. </div>

  1200. <p>One of the more common uses of <code class="docutils literal notranslate"><span class="pre">nargs='?'</span></code> is to allow optional input and

  1201. output files:</p>

  1202. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1203. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;infile&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">FileType</span><span class="p">(</span><span class="s1">&#39;r&#39;</span><span class="p">),</span>

  1204. <span class="gp">... </span>                    <span class="n">default</span><span class="o">=</span><span class="n">sys</span><span class="o">.</span><span class="n">stdin</span><span class="p">)</span>

  1205. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;outfile&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">FileType</span><span class="p">(</span><span class="s1">&#39;w&#39;</span><span class="p">),</span>

  1206. <span class="gp">... </span>                    <span class="n">default</span><span class="o">=</span><span class="n">sys</span><span class="o">.</span><span class="n">stdout</span><span class="p">)</span>

  1207. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;input.txt&#39;</span><span class="p">,</span> <span class="s1">&#39;output.txt&#39;</span><span class="p">])</span>

  1208. <span class="go">Namespace(infile=&lt;_io.TextIOWrapper name=&#39;input.txt&#39; encoding=&#39;UTF-8&#39;&gt;,</span>

  1209. <span class="go">          outfile=&lt;_io.TextIOWrapper name=&#39;output.txt&#39; encoding=&#39;UTF-8&#39;&gt;)</span>

  1210. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>

  1211. <span class="go">Namespace(infile=&lt;_io.TextIOWrapper name=&#39;&lt;stdin&gt;&#39; encoding=&#39;UTF-8&#39;&gt;,</span>

  1212. <span class="go">          outfile=&lt;_io.TextIOWrapper name=&#39;&lt;stdout&gt;&#39; encoding=&#39;UTF-8&#39;&gt;)</span>

  1213. </pre></div>

  1214. </div>

  1215. </li>

  1216. </ul>

  1217. <ul id="index-1">

  1218. <li><p><code class="docutils literal notranslate"><span class="pre">'*'</span></code>.  All command-line arguments present are gathered into a list.  Note that

  1219. it generally doesn’t make much sense to have more than one positional argument

  1220. with <code class="docutils literal notranslate"><span class="pre">nargs='*'</span></code>, but multiple optional arguments with <code class="docutils literal notranslate"><span class="pre">nargs='*'</span></code> is

  1221. possible.  For example:</p>

  1222. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1223. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;*&#39;</span><span class="p">)</span>

  1224. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--bar&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;*&#39;</span><span class="p">)</span>

  1225. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;baz&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;*&#39;</span><span class="p">)</span>

  1226. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;a b --foo x y --bar 1 2&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>

  1227. <span class="go">Namespace(bar=[&#39;1&#39;, &#39;2&#39;], baz=[&#39;a&#39;, &#39;b&#39;], foo=[&#39;x&#39;, &#39;y&#39;])</span>

  1228. </pre></div>

  1229. </div>

  1230. </li>

  1231. </ul>

  1232. <ul id="index-2">

  1233. <li><p><code class="docutils literal notranslate"><span class="pre">'+'</span></code>. Just like <code class="docutils literal notranslate"><span class="pre">'*'</span></code>, all command-line args present are gathered into a

  1234. list.  Additionally, an error message will be generated if there wasn’t at

  1235. least one command-line argument present.  For example:</p>

  1236. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">)</span>

  1237. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;+&#39;</span><span class="p">)</span>

  1238. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;a&#39;</span><span class="p">,</span> <span class="s1">&#39;b&#39;</span><span class="p">])</span>

  1239. <span class="go">Namespace(foo=[&#39;a&#39;, &#39;b&#39;])</span>

  1240. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>

  1241. <span class="go">usage: PROG [-h] foo [foo ...]</span>

  1242. <span class="go">PROG: error: the following arguments are required: foo</span>

  1243. </pre></div>

  1244. </div>

  1245. </li>

  1246. </ul>

  1247. <p>If the <code class="docutils literal notranslate"><span class="pre">nargs</span></code> keyword argument is not provided, the number of arguments consumed

  1248. is determined by the <a class="reference internal" href="#action">action</a>.  Generally this means a single command-line argument

  1249. will be consumed and a single item (not a list) will be produced.</p>

  1250. </section>

  1251. <section id="const">

  1252. <span id="id8"></span><h3>const<a class="headerlink" href="#const" title="Link to this heading">¶</a></h3>

  1253. <p>The <code class="docutils literal notranslate"><span class="pre">const</span></code> argument of <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> is used to hold

  1254. constant values that are not read from the command line but are required for

  1255. the various <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> actions.  The two most common uses of it are:</p>

  1256. <ul class="simple">

  1257. <li><p>When <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> is called with

  1258. <code class="docutils literal notranslate"><span class="pre">action='store_const'</span></code> or <code class="docutils literal notranslate"><span class="pre">action='append_const'</span></code>.  These actions add the

  1259. <code class="docutils literal notranslate"><span class="pre">const</span></code> value to one of the attributes of the object returned by

  1260. <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a>. See the <a class="reference internal" href="#action">action</a> description for examples.

  1261. If <code class="docutils literal notranslate"><span class="pre">const</span></code> is not provided to <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a>, it will

  1262. receive a default value of <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>

  1263. <li><p>When <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> is called with option strings

  1264. (like <code class="docutils literal notranslate"><span class="pre">-f</span></code> or <code class="docutils literal notranslate"><span class="pre">--foo</span></code>) and <code class="docutils literal notranslate"><span class="pre">nargs='?'</span></code>.  This creates an optional

  1265. argument that can be followed by zero or one command-line arguments.

  1266. When parsing the command line, if the option string is encountered with no

  1267. command-line argument following it, the value of <code class="docutils literal notranslate"><span class="pre">const</span></code> will be assumed to

  1268. be <code class="docutils literal notranslate"><span class="pre">None</span></code> instead.  See the <a class="reference internal" href="#nargs">nargs</a> description for examples.</p></li>

  1269. </ul>

  1270. <div class="versionchanged">

  1271. <p><span class="versionmodified changed">Changed in version 3.11: </span><code class="docutils literal notranslate"><span class="pre">const=None</span></code> by default, including when <code class="docutils literal notranslate"><span class="pre">action='append_const'</span></code> or

  1272. <code class="docutils literal notranslate"><span class="pre">action='store_const'</span></code>.</p>

  1273. </div>

  1274. </section>

  1275. <section id="default">

  1276. <span id="id9"></span><h3>default<a class="headerlink" href="#default" title="Link to this heading">¶</a></h3>

  1277. <p>All optional arguments and some positional arguments may be omitted at the

  1278. command line.  The <code class="docutils literal notranslate"><span class="pre">default</span></code> keyword argument of

  1279. <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a>, whose value defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>,

  1280. specifies what value should be used if the command-line argument is not present.

  1281. For optional arguments, the <code class="docutils literal notranslate"><span class="pre">default</span></code> value is used when the option string

  1282. was not present at the command line:</p>

  1283. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1284. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">42</span><span class="p">)</span>

  1285. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;2&#39;</span><span class="p">])</span>

  1286. <span class="go">Namespace(foo=&#39;2&#39;)</span>

  1287. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>

  1288. <span class="go">Namespace(foo=42)</span>

  1289. </pre></div>

  1290. </div>

  1291. <p>If the target namespace already has an attribute set, the action <em>default</em>

  1292. will not over write it:</p>

  1293. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1294. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">42</span><span class="p">)</span>

  1295. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([],</span> <span class="n">namespace</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">Namespace</span><span class="p">(</span><span class="n">foo</span><span class="o">=</span><span class="mi">101</span><span class="p">))</span>

  1296. <span class="go">Namespace(foo=101)</span>

  1297. </pre></div>

  1298. </div>

  1299. <p>If the <code class="docutils literal notranslate"><span class="pre">default</span></code> value is a string, the parser parses the value as if it

  1300. were a command-line argument.  In particular, the parser applies any <a class="reference internal" href="#type">type</a>

  1301. conversion argument, if provided, before setting the attribute on the

  1302. <a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate"><span class="pre">Namespace</span></code></a> return value.  Otherwise, the parser uses the value as is:</p>

  1303. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1304. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--length&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">&#39;10&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>

  1305. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--width&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mf">10.5</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>

  1306. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>

  1307. <span class="go">Namespace(length=10, width=10.5)</span>

  1308. </pre></div>

  1309. </div>

  1310. <p>For positional arguments with <a class="reference internal" href="#nargs">nargs</a> equal to <code class="docutils literal notranslate"><span class="pre">?</span></code> or <code class="docutils literal notranslate"><span class="pre">*</span></code>, the <code class="docutils literal notranslate"><span class="pre">default</span></code> value

  1311. is used when no command-line argument was present:</p>

  1312. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1313. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">42</span><span class="p">)</span>

  1314. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;a&#39;</span><span class="p">])</span>

  1315. <span class="go">Namespace(foo=&#39;a&#39;)</span>

  1316. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>

  1317. <span class="go">Namespace(foo=42)</span>

  1318. </pre></div>

  1319. </div>

  1320. <p>Providing <code class="docutils literal notranslate"><span class="pre">default=argparse.SUPPRESS</span></code> causes no attribute to be added if the

  1321. command-line argument was not present:</p>

  1322. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1323. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">SUPPRESS</span><span class="p">)</span>

  1324. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>

  1325. <span class="go">Namespace()</span>

  1326. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;1&#39;</span><span class="p">])</span>

  1327. <span class="go">Namespace(foo=&#39;1&#39;)</span>

  1328. </pre></div>

  1329. </div>

  1330. </section>

  1331. <section id="type">

  1332. <span id="argparse-type"></span><h3>type<a class="headerlink" href="#type" title="Link to this heading">¶</a></h3>

  1333. <p>By default, the parser reads command-line arguments in as simple

  1334. strings. However, quite often the command-line string should instead be

  1335. interpreted as another type, such as a <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a> or <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>.  The

  1336. <code class="docutils literal notranslate"><span class="pre">type</span></code> keyword for <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> allows any

  1337. necessary type-checking and type conversions to be performed.</p>

  1338. <p>If the <a class="reference internal" href="#type">type</a> keyword is used with the <a class="reference internal" href="#default">default</a> keyword, the type converter

  1339. is only applied if the default is a string.</p>

  1340. <p>The argument to <code class="docutils literal notranslate"><span class="pre">type</span></code> can be any callable that accepts a single string.

  1341. If the function raises <a class="reference internal" href="#argparse.ArgumentTypeError" title="argparse.ArgumentTypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ArgumentTypeError</span></code></a>, <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>, or

  1342. <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>, the exception is caught and a nicely formatted error

  1343. message is displayed.  No other exception types are handled.</p>

  1344. <p>Common built-in types and functions can be used as type converters:</p>

  1345. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">argparse</span>

  1346. <span class="kn">import</span> <span class="nn">pathlib</span>

  1347. 

  1348. <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>

  1349. <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;count&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>

  1350. <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;distance&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">float</span><span class="p">)</span>

  1351. <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;street&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="n">ascii</span><span class="p">)</span>

  1352. <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;code_point&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">ord</span><span class="p">)</span>

  1353. <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;source_file&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">open</span><span class="p">)</span>

  1354. <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;dest_file&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">FileType</span><span class="p">(</span><span class="s1">&#39;w&#39;</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s1">&#39;latin-1&#39;</span><span class="p">))</span>

  1355. <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;datapath&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">)</span>

  1356. </pre></div>

  1357. </div>

  1358. <p>User defined functions can be used as well:</p>

  1359. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">hyphenated</span><span class="p">(</span><span class="n">string</span><span class="p">):</span>

  1360. <span class="gp">... </span>    <span class="k">return</span> <span class="s1">&#39;-&#39;</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="n">word</span><span class="p">[:</span><span class="mi">4</span><span class="p">]</span> <span class="k">for</span> <span class="n">word</span> <span class="ow">in</span> <span class="n">string</span><span class="o">.</span><span class="n">casefold</span><span class="p">()</span><span class="o">.</span><span class="n">split</span><span class="p">()])</span>

  1361. <span class="gp">...</span>

  1362. <span class="gp">&gt;&gt;&gt; </span><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>

  1363. <span class="gp">&gt;&gt;&gt; </span><span class="n">_</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;short_title&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="n">hyphenated</span><span class="p">)</span>

  1364. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;&quot;The Tale of Two Cities&quot;&#39;</span><span class="p">])</span>

  1365. <span class="go">Namespace(short_title=&#39;&quot;the-tale-of-two-citi&#39;)</span>

  1366. </pre></div>

  1367. </div>

  1368. <p>The <a class="reference internal" href="functions.html#bool" title="bool"><code class="xref py py-func docutils literal notranslate"><span class="pre">bool()</span></code></a> function is not recommended as a type converter.  All it does

  1369. is convert empty strings to <code class="docutils literal notranslate"><span class="pre">False</span></code> and non-empty strings to <code class="docutils literal notranslate"><span class="pre">True</span></code>.

  1370. This is usually not what is desired.</p>

  1371. <p>In general, the <code class="docutils literal notranslate"><span class="pre">type</span></code> keyword is a convenience that should only be used for

  1372. simple conversions that can only raise one of the three supported exceptions.

  1373. Anything with more interesting error-handling or resource management should be

  1374. done downstream after the arguments are parsed.</p>

  1375. <p>For example, JSON or YAML conversions have complex error cases that require

  1376. better reporting than can be given by the <code class="docutils literal notranslate"><span class="pre">type</span></code> keyword.  A

  1377. <a class="reference internal" href="json.html#json.JSONDecodeError" title="json.JSONDecodeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">JSONDecodeError</span></code></a> would not be well formatted and a

  1378. <a class="reference internal" href="exceptions.html#FileNotFoundError" title="FileNotFoundError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileNotFoundError</span></code></a> exception would not be handled at all.</p>

  1379. <p>Even <a class="reference internal" href="#argparse.FileType" title="argparse.FileType"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileType</span></code></a> has its limitations for use with the <code class="docutils literal notranslate"><span class="pre">type</span></code>

  1380. keyword.  If one argument uses <em>FileType</em> and then a subsequent argument fails,

  1381. an error is reported but the file is not automatically closed.  In this case, it

  1382. would be better to wait until after the parser has run and then use the

  1383. <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a>-statement to manage the files.</p>

  1384. <p>For type checkers that simply check against a fixed set of values, consider

  1385. using the <a class="reference internal" href="#choices">choices</a> keyword instead.</p>

  1386. </section>

  1387. <section id="choices">

  1388. <span id="id10"></span><h3>choices<a class="headerlink" href="#choices" title="Link to this heading">¶</a></h3>

  1389. <p>Some command-line arguments should be selected from a restricted set of values.

  1390. These can be handled by passing a sequence object as the <em>choices</em> keyword

  1391. argument to <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a>.  When the command line is

  1392. parsed, argument values will be checked, and an error message will be displayed

  1393. if the argument was not one of the acceptable values:</p>

  1394. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;game.py&#39;</span><span class="p">)</span>

  1395. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;move&#39;</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;rock&#39;</span><span class="p">,</span> <span class="s1">&#39;paper&#39;</span><span class="p">,</span> <span class="s1">&#39;scissors&#39;</span><span class="p">])</span>

  1396. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;rock&#39;</span><span class="p">])</span>

  1397. <span class="go">Namespace(move=&#39;rock&#39;)</span>

  1398. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;fire&#39;</span><span class="p">])</span>

  1399. <span class="go">usage: game.py [-h] {rock,paper,scissors}</span>

  1400. <span class="go">game.py: error: argument move: invalid choice: &#39;fire&#39; (choose from &#39;rock&#39;,</span>

  1401. <span class="go">&#39;paper&#39;, &#39;scissors&#39;)</span>

  1402. </pre></div>

  1403. </div>

  1404. <p>Note that inclusion in the <em>choices</em> sequence is checked after any <a class="reference internal" href="#type">type</a>

  1405. conversions have been performed, so the type of the objects in the <em>choices</em>

  1406. sequence should match the <a class="reference internal" href="#type">type</a> specified:</p>

  1407. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;doors.py&#39;</span><span class="p">)</span>

  1408. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;door&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="nb">range</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">4</span><span class="p">))</span>

  1409. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;3&#39;</span><span class="p">]))</span>

  1410. <span class="go">Namespace(door=3)</span>

  1411. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;4&#39;</span><span class="p">])</span>

  1412. <span class="go">usage: doors.py [-h] {1,2,3}</span>

  1413. <span class="go">doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)</span>

  1414. </pre></div>

  1415. </div>

  1416. <p>Any sequence can be passed as the <em>choices</em> value, so <a class="reference internal" href="stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a> objects,

  1417. <a class="reference internal" href="stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a> objects, and custom sequences are all supported.</p>

  1418. <p>Use of <a class="reference internal" href="enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">enum.Enum</span></code></a> is not recommended because it is difficult to

  1419. control its appearance in usage, help, and error messages.</p>

  1420. <p>Formatted choices override the default <em>metavar</em> which is normally derived

  1421. from <em>dest</em>.  This is usually what you want because the user never sees the

  1422. <em>dest</em> parameter.  If this display isn’t desirable (perhaps because there are

  1423. many choices), just specify an explicit <a class="reference internal" href="#metavar">metavar</a>.</p>

  1424. </section>

  1425. <section id="required">

  1426. <span id="id11"></span><h3>required<a class="headerlink" href="#required" title="Link to this heading">¶</a></h3>

  1427. <p>In general, the <a class="reference internal" href="#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> module assumes that flags like <code class="docutils literal notranslate"><span class="pre">-f</span></code> and <code class="docutils literal notranslate"><span class="pre">--bar</span></code>

  1428. indicate <em>optional</em> arguments, which can always be omitted at the command line.

  1429. To make an option <em>required</em>, <code class="docutils literal notranslate"><span class="pre">True</span></code> can be specified for the <code class="docutils literal notranslate"><span class="pre">required=</span></code>

  1430. keyword argument to <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a>:</p>

  1431. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1432. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">required</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>

  1433. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;BAR&#39;</span><span class="p">])</span>

  1434. <span class="go">Namespace(foo=&#39;BAR&#39;)</span>

  1435. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>

  1436. <span class="go">usage: [-h] --foo FOO</span>

  1437. <span class="go">: error: the following arguments are required: --foo</span>

  1438. </pre></div>

  1439. </div>

  1440. <p>As the example shows, if an option is marked as <code class="docutils literal notranslate"><span class="pre">required</span></code>,

  1441. <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> will report an error if that option is not

  1442. present at the command line.</p>

  1443. <div class="admonition note">

  1444. <p class="admonition-title">Note</p>

  1445. <p>Required options are generally considered bad form because users expect

  1446. <em>options</em> to be <em>optional</em>, and thus they should be avoided when possible.</p>

  1447. </div>

  1448. </section>

  1449. <section id="help">

  1450. <span id="id12"></span><h3>help<a class="headerlink" href="#help" title="Link to this heading">¶</a></h3>

  1451. <p>The <code class="docutils literal notranslate"><span class="pre">help</span></code> value is a string containing a brief description of the argument.

  1452. When a user requests help (usually by using <code class="docutils literal notranslate"><span class="pre">-h</span></code> or <code class="docutils literal notranslate"><span class="pre">--help</span></code> at the

  1453. command line), these <code class="docutils literal notranslate"><span class="pre">help</span></code> descriptions will be displayed with each

  1454. argument:</p>

  1455. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;frobble&#39;</span><span class="p">)</span>

  1456. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_true&#39;</span><span class="p">,</span>

  1457. <span class="gp">... </span>                    <span class="n">help</span><span class="o">=</span><span class="s1">&#39;foo the bars before frobbling&#39;</span><span class="p">)</span>

  1458. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;+&#39;</span><span class="p">,</span>

  1459. <span class="gp">... </span>                    <span class="n">help</span><span class="o">=</span><span class="s1">&#39;one of the bars to be frobbled&#39;</span><span class="p">)</span>

  1460. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-h&#39;</span><span class="p">])</span>

  1461. <span class="go">usage: frobble [-h] [--foo] bar [bar ...]</span>

  1462. 

  1463. <span class="go">positional arguments:</span>

  1464. <span class="go"> bar     one of the bars to be frobbled</span>

  1465. 

  1466. <span class="go">options:</span>

  1467. <span class="go"> -h, --help  show this help message and exit</span>

  1468. <span class="go"> --foo   foo the bars before frobbling</span>

  1469. </pre></div>

  1470. </div>

  1471. <p>The <code class="docutils literal notranslate"><span class="pre">help</span></code> strings can include various format specifiers to avoid repetition

  1472. of things like the program name or the argument <a class="reference internal" href="#default">default</a>.  The available

  1473. specifiers include the program name, <code class="docutils literal notranslate"><span class="pre">%(prog)s</span></code> and most keyword arguments to

  1474. <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a>, e.g. <code class="docutils literal notranslate"><span class="pre">%(default)s</span></code>, <code class="docutils literal notranslate"><span class="pre">%(type)s</span></code>, etc.:</p>

  1475. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;frobble&#39;</span><span class="p">)</span>

  1476. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">42</span><span class="p">,</span>

  1477. <span class="gp">... </span>                    <span class="n">help</span><span class="o">=</span><span class="s1">&#39;the bar to </span><span class="si">%(prog)s</span><span class="s1"> (default: </span><span class="si">%(default)s</span><span class="s1">)&#39;</span><span class="p">)</span>

  1478. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>

  1479. <span class="go">usage: frobble [-h] [bar]</span>

  1480. 

  1481. <span class="go">positional arguments:</span>

  1482. <span class="go"> bar     the bar to frobble (default: 42)</span>

  1483. 

  1484. <span class="go">options:</span>

  1485. <span class="go"> -h, --help  show this help message and exit</span>

  1486. </pre></div>

  1487. </div>

  1488. <p>As the help string supports %-formatting, if you want a literal <code class="docutils literal notranslate"><span class="pre">%</span></code> to appear

  1489. in the help string, you must escape it as <code class="docutils literal notranslate"><span class="pre">%%</span></code>.</p>

  1490. <p><a class="reference internal" href="#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> supports silencing the help entry for certain options, by

  1491. setting the <code class="docutils literal notranslate"><span class="pre">help</span></code> value to <code class="docutils literal notranslate"><span class="pre">argparse.SUPPRESS</span></code>:</p>

  1492. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;frobble&#39;</span><span class="p">)</span>

  1493. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">SUPPRESS</span><span class="p">)</span>

  1494. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>

  1495. <span class="go">usage: frobble [-h]</span>

  1496. 

  1497. <span class="go">options:</span>

  1498. <span class="go">  -h, --help  show this help message and exit</span>

  1499. </pre></div>

  1500. </div>

  1501. </section>

  1502. <section id="metavar">

  1503. <span id="id13"></span><h3>metavar<a class="headerlink" href="#metavar" title="Link to this heading">¶</a></h3>

  1504. <p>When <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> generates help messages, it needs some way to refer

  1505. to each expected argument.  By default, ArgumentParser objects use the <a class="reference internal" href="#dest">dest</a>

  1506. value as the “name” of each object.  By default, for positional argument

  1507. actions, the <a class="reference internal" href="#dest">dest</a> value is used directly, and for optional argument actions,

  1508. the <a class="reference internal" href="#dest">dest</a> value is uppercased.  So, a single positional argument with

  1509. <code class="docutils literal notranslate"><span class="pre">dest='bar'</span></code> will be referred to as <code class="docutils literal notranslate"><span class="pre">bar</span></code>. A single

  1510. optional argument <code class="docutils literal notranslate"><span class="pre">--foo</span></code> that should be followed by a single command-line argument

  1511. will be referred to as <code class="docutils literal notranslate"><span class="pre">FOO</span></code>.  An example:</p>

  1512. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1513. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">)</span>

  1514. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>

  1515. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;X --foo Y&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>

  1516. <span class="go">Namespace(bar=&#39;X&#39;, foo=&#39;Y&#39;)</span>

  1517. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>

  1518. <span class="go">usage:  [-h] [--foo FOO] bar</span>

  1519. 

  1520. <span class="go">positional arguments:</span>

  1521. <span class="go"> bar</span>

  1522. 

  1523. <span class="go">options:</span>

  1524. <span class="go"> -h, --help  show this help message and exit</span>

  1525. <span class="go"> --foo FOO</span>

  1526. </pre></div>

  1527. </div>

  1528. <p>An alternative name can be specified with <code class="docutils literal notranslate"><span class="pre">metavar</span></code>:</p>

  1529. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1530. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">&#39;YYY&#39;</span><span class="p">)</span>

  1531. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">&#39;XXX&#39;</span><span class="p">)</span>

  1532. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;X --foo Y&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>

  1533. <span class="go">Namespace(bar=&#39;X&#39;, foo=&#39;Y&#39;)</span>

  1534. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>

  1535. <span class="go">usage:  [-h] [--foo YYY] XXX</span>

  1536. 

  1537. <span class="go">positional arguments:</span>

  1538. <span class="go"> XXX</span>

  1539. 

  1540. <span class="go">options:</span>

  1541. <span class="go"> -h, --help  show this help message and exit</span>

  1542. <span class="go"> --foo YYY</span>

  1543. </pre></div>

  1544. </div>

  1545. <p>Note that <code class="docutils literal notranslate"><span class="pre">metavar</span></code> only changes the <em>displayed</em> name - the name of the

  1546. attribute on the <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> object is still determined

  1547. by the <a class="reference internal" href="#dest">dest</a> value.</p>

  1548. <p>Different values of <code class="docutils literal notranslate"><span class="pre">nargs</span></code> may cause the metavar to be used multiple times.

  1549. Providing a tuple to <code class="docutils literal notranslate"><span class="pre">metavar</span></code> specifies a different display for each of the

  1550. arguments:</p>

  1551. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">)</span>

  1552. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-x&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>

  1553. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="s1">&#39;baz&#39;</span><span class="p">))</span>

  1554. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>

  1555. <span class="go">usage: PROG [-h] [-x X X] [--foo bar baz]</span>

  1556. 

  1557. <span class="go">options:</span>

  1558. <span class="go"> -h, --help     show this help message and exit</span>

  1559. <span class="go"> -x X X</span>

  1560. <span class="go"> --foo bar baz</span>

  1561. </pre></div>

  1562. </div>

  1563. </section>

  1564. <section id="dest">

  1565. <span id="id14"></span><h3>dest<a class="headerlink" href="#dest" title="Link to this heading">¶</a></h3>

  1566. <p>Most <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> actions add some value as an attribute of the

  1567. object returned by <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a>.  The name of this

  1568. attribute is determined by the <code class="docutils literal notranslate"><span class="pre">dest</span></code> keyword argument of

  1569. <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a>.  For positional argument actions,

  1570. <code class="docutils literal notranslate"><span class="pre">dest</span></code> is normally supplied as the first argument to

  1571. <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a>:</p>

  1572. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1573. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>

  1574. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;XXX&#39;</span><span class="p">])</span>

  1575. <span class="go">Namespace(bar=&#39;XXX&#39;)</span>

  1576. </pre></div>

  1577. </div>

  1578. <p>For optional argument actions, the value of <code class="docutils literal notranslate"><span class="pre">dest</span></code> is normally inferred from

  1579. the option strings.  <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> generates the value of <code class="docutils literal notranslate"><span class="pre">dest</span></code> by

  1580. taking the first long option string and stripping away the initial <code class="docutils literal notranslate"><span class="pre">--</span></code>

  1581. string.  If no long option strings were supplied, <code class="docutils literal notranslate"><span class="pre">dest</span></code> will be derived from

  1582. the first short option string by stripping the initial <code class="docutils literal notranslate"><span class="pre">-</span></code> character.  Any

  1583. internal <code class="docutils literal notranslate"><span class="pre">-</span></code> characters will be converted to <code class="docutils literal notranslate"><span class="pre">_</span></code> characters to make sure

  1584. the string is a valid attribute name.  The examples below illustrate this

  1585. behavior:</p>

  1586. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1587. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-f&#39;</span><span class="p">,</span> <span class="s1">&#39;--foo-bar&#39;</span><span class="p">,</span> <span class="s1">&#39;--foo&#39;</span><span class="p">)</span>

  1588. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-x&#39;</span><span class="p">,</span> <span class="s1">&#39;-y&#39;</span><span class="p">)</span>

  1589. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;-f 1 -x 2&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>

  1590. <span class="go">Namespace(foo_bar=&#39;1&#39;, x=&#39;2&#39;)</span>

  1591. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;--foo 1 -y 2&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>

  1592. <span class="go">Namespace(foo_bar=&#39;1&#39;, x=&#39;2&#39;)</span>

  1593. </pre></div>

  1594. </div>

  1595. <p><code class="docutils literal notranslate"><span class="pre">dest</span></code> allows a custom attribute name to be provided:</p>

  1596. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1597. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>

  1598. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;--foo XXX&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>

  1599. <span class="go">Namespace(bar=&#39;XXX&#39;)</span>

  1600. </pre></div>

  1601. </div>

  1602. </section>

  1603. <section id="action-classes">

  1604. <h3>Action classes<a class="headerlink" href="#action-classes" title="Link to this heading">¶</a></h3>

  1605. <p>Action classes implement the Action API, a callable which returns a callable

  1606. which processes arguments from the command-line. Any object which follows

  1607. this API may be passed as the <code class="docutils literal notranslate"><span class="pre">action</span></code> parameter to

  1608. <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a>.</p>

  1609. <dl class="py class">

  1610. <dt class="sig sig-object py" id="argparse.Action">

  1611. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">argparse.</span></span><span class="sig-name descname"><span class="pre">Action</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">option_strings</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dest</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">nargs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">const</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">default</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">type</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">choices</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">required</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">help</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">metavar</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="#argparse.Action" title="Link to this definition">¶</a></dt>

  1612. <dd></dd></dl>

  1613. 

  1614. <p>Action objects are used by an ArgumentParser to represent the information

  1615. needed to parse a single argument from one or more strings from the

  1616. command line. The Action class must accept the two positional arguments

  1617. plus any keyword arguments passed to <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ArgumentParser.add_argument()</span></code></a>

  1618. except for the <code class="docutils literal notranslate"><span class="pre">action</span></code> itself.</p>

  1619. <p>Instances of Action (or return value of any callable to the <code class="docutils literal notranslate"><span class="pre">action</span></code>

  1620. parameter) should have attributes “dest”, “option_strings”, “default”, “type”,

  1621. “required”, “help”, etc. defined. The easiest way to ensure these attributes

  1622. are defined is to call <code class="docutils literal notranslate"><span class="pre">Action.__init__</span></code>.</p>

  1623. <p>Action instances should be callable, so subclasses must override the

  1624. <code class="docutils literal notranslate"><span class="pre">__call__</span></code> method, which should accept four parameters:</p>

  1625. <ul class="simple">

  1626. <li><p><code class="docutils literal notranslate"><span class="pre">parser</span></code> - The ArgumentParser object which contains this action.</p></li>

  1627. <li><p><code class="docutils literal notranslate"><span class="pre">namespace</span></code> - The <a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate"><span class="pre">Namespace</span></code></a> object that will be returned by

  1628. <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a>.  Most actions add an attribute to this

  1629. object using <a class="reference internal" href="functions.html#setattr" title="setattr"><code class="xref py py-func docutils literal notranslate"><span class="pre">setattr()</span></code></a>.</p></li>

  1630. <li><p><code class="docutils literal notranslate"><span class="pre">values</span></code> - The associated command-line arguments, with any type conversions

  1631. applied.  Type conversions are specified with the <a class="reference internal" href="#type">type</a> keyword argument to

  1632. <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a>.</p></li>

  1633. <li><p><code class="docutils literal notranslate"><span class="pre">option_string</span></code> - The option string that was used to invoke this action.

  1634. The <code class="docutils literal notranslate"><span class="pre">option_string</span></code> argument is optional, and will be absent if the action

  1635. is associated with a positional argument.</p></li>

  1636. </ul>

  1637. <p>The <code class="docutils literal notranslate"><span class="pre">__call__</span></code> method may perform arbitrary actions, but will typically set

  1638. attributes on the <code class="docutils literal notranslate"><span class="pre">namespace</span></code> based on <code class="docutils literal notranslate"><span class="pre">dest</span></code> and <code class="docutils literal notranslate"><span class="pre">values</span></code>.</p>

  1639. <p>Action subclasses can define a <code class="docutils literal notranslate"><span class="pre">format_usage</span></code> method that takes no argument

  1640. and return a string which will be used when printing the usage of the program.

  1641. If such method is not provided, a sensible default will be used.</p>

  1642. </section>

  1643. </section>

  1644. <section id="the-parse-args-method">

  1645. <h2>The parse_args() method<a class="headerlink" href="#the-parse-args-method" title="Link to this heading">¶</a></h2>

  1646. <dl class="py method">

  1647. <dt class="sig sig-object py" id="argparse.ArgumentParser.parse_args">

  1648. <span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">parse_args</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">namespace</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="#argparse.ArgumentParser.parse_args" title="Link to this definition">¶</a></dt>

  1649. <dd><p>Convert argument strings to objects and assign them as attributes of the

  1650. namespace.  Return the populated namespace.</p>

  1651. <p>Previous calls to <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> determine exactly what objects are

  1652. created and how they are assigned. See the documentation for

  1653. <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> for details.</p>

  1654. <ul class="simple">

  1655. <li><p><a class="reference internal" href="#args">args</a> - List of strings to parse.  The default is taken from

  1656. <a class="reference internal" href="sys.html#sys.argv" title="sys.argv"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.argv</span></code></a>.</p></li>

  1657. <li><p><a class="reference internal" href="#namespace">namespace</a> - An object to take the attributes.  The default is a new empty

  1658. <a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate"><span class="pre">Namespace</span></code></a> object.</p></li>

  1659. </ul>

  1660. </dd></dl>

  1661. 

  1662. <section id="option-value-syntax">

  1663. <h3>Option value syntax<a class="headerlink" href="#option-value-syntax" title="Link to this heading">¶</a></h3>

  1664. <p>The <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> method supports several ways of

  1665. specifying the value of an option (if it takes one).  In the simplest case, the

  1666. option and its value are passed as two separate arguments:</p>

  1667. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">)</span>

  1668. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-x&#39;</span><span class="p">)</span>

  1669. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">)</span>

  1670. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-x&#39;</span><span class="p">,</span> <span class="s1">&#39;X&#39;</span><span class="p">])</span>

  1671. <span class="go">Namespace(foo=None, x=&#39;X&#39;)</span>

  1672. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;FOO&#39;</span><span class="p">])</span>

  1673. <span class="go">Namespace(foo=&#39;FOO&#39;, x=None)</span>

  1674. </pre></div>

  1675. </div>

  1676. <p>For long options (options with names longer than a single character), the option

  1677. and value can also be passed as a single command-line argument, using <code class="docutils literal notranslate"><span class="pre">=</span></code> to

  1678. separate them:</p>

  1679. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo=FOO&#39;</span><span class="p">])</span>

  1680. <span class="go">Namespace(foo=&#39;FOO&#39;, x=None)</span>

  1681. </pre></div>

  1682. </div>

  1683. <p>For short options (options only one character long), the option and its value

  1684. can be concatenated:</p>

  1685. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-xX&#39;</span><span class="p">])</span>

  1686. <span class="go">Namespace(foo=None, x=&#39;X&#39;)</span>

  1687. </pre></div>

  1688. </div>

  1689. <p>Several short options can be joined together, using only a single <code class="docutils literal notranslate"><span class="pre">-</span></code> prefix,

  1690. as long as only the last option (or none of them) requires a value:</p>

  1691. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">)</span>

  1692. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-x&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_true&#39;</span><span class="p">)</span>

  1693. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-y&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_true&#39;</span><span class="p">)</span>

  1694. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-z&#39;</span><span class="p">)</span>

  1695. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-xyzZ&#39;</span><span class="p">])</span>

  1696. <span class="go">Namespace(x=True, y=True, z=&#39;Z&#39;)</span>

  1697. </pre></div>

  1698. </div>

  1699. </section>

  1700. <section id="invalid-arguments">

  1701. <h3>Invalid arguments<a class="headerlink" href="#invalid-arguments" title="Link to this heading">¶</a></h3>

  1702. <p>While parsing the command line, <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> checks for a

  1703. variety of errors, including ambiguous options, invalid types, invalid options,

  1704. wrong number of positional arguments, etc.  When it encounters such an error,

  1705. it exits and prints the error along with a usage message:</p>

  1706. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">)</span>

  1707. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>

  1708. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</span><span class="p">)</span>

  1709. 

  1710. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># invalid type</span>

  1711. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;spam&#39;</span><span class="p">])</span>

  1712. <span class="go">usage: PROG [-h] [--foo FOO] [bar]</span>

  1713. <span class="go">PROG: error: argument --foo: invalid int value: &#39;spam&#39;</span>

  1714. 

  1715. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># invalid option</span>

  1716. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--bar&#39;</span><span class="p">])</span>

  1717. <span class="go">usage: PROG [-h] [--foo FOO] [bar]</span>

  1718. <span class="go">PROG: error: no such option: --bar</span>

  1719. 

  1720. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># wrong number of arguments</span>

  1721. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;spam&#39;</span><span class="p">,</span> <span class="s1">&#39;badger&#39;</span><span class="p">])</span>

  1722. <span class="go">usage: PROG [-h] [--foo FOO] [bar]</span>

  1723. <span class="go">PROG: error: extra arguments found: badger</span>

  1724. </pre></div>

  1725. </div>

  1726. </section>

  1727. <section id="arguments-containing">

  1728. <h3>Arguments containing <code class="docutils literal notranslate"><span class="pre">-</span></code><a class="headerlink" href="#arguments-containing" title="Link to this heading">¶</a></h3>

  1729. <p>The <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> method attempts to give errors whenever

  1730. the user has clearly made a mistake, but some situations are inherently

  1731. ambiguous.  For example, the command-line argument <code class="docutils literal notranslate"><span class="pre">-1</span></code> could either be an

  1732. attempt to specify an option or an attempt to provide a positional argument.

  1733. The <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> method is cautious here: positional

  1734. arguments may only begin with <code class="docutils literal notranslate"><span class="pre">-</span></code> if they look like negative numbers and

  1735. there are no options in the parser that look like negative numbers:</p>

  1736. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">)</span>

  1737. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-x&#39;</span><span class="p">)</span>

  1738. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</span><span class="p">)</span>

  1739. 

  1740. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># no negative number options, so -1 is a positional argument</span>

  1741. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-x&#39;</span><span class="p">,</span> <span class="s1">&#39;-1&#39;</span><span class="p">])</span>

  1742. <span class="go">Namespace(foo=None, x=&#39;-1&#39;)</span>

  1743. 

  1744. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># no negative number options, so -1 and -5 are positional arguments</span>

  1745. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-x&#39;</span><span class="p">,</span> <span class="s1">&#39;-1&#39;</span><span class="p">,</span> <span class="s1">&#39;-5&#39;</span><span class="p">])</span>

  1746. <span class="go">Namespace(foo=&#39;-5&#39;, x=&#39;-1&#39;)</span>

  1747. 

  1748. <span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">)</span>

  1749. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-1&#39;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">&#39;one&#39;</span><span class="p">)</span>

  1750. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</span><span class="p">)</span>

  1751. 

  1752. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># negative number options present, so -1 is an option</span>

  1753. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-1&#39;</span><span class="p">,</span> <span class="s1">&#39;X&#39;</span><span class="p">])</span>

  1754. <span class="go">Namespace(foo=None, one=&#39;X&#39;)</span>

  1755. 

  1756. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># negative number options present, so -2 is an option</span>

  1757. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-2&#39;</span><span class="p">])</span>

  1758. <span class="go">usage: PROG [-h] [-1 ONE] [foo]</span>

  1759. <span class="go">PROG: error: no such option: -2</span>

  1760. 

  1761. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># negative number options present, so both -1s are options</span>

  1762. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-1&#39;</span><span class="p">,</span> <span class="s1">&#39;-1&#39;</span><span class="p">])</span>

  1763. <span class="go">usage: PROG [-h] [-1 ONE] [foo]</span>

  1764. <span class="go">PROG: error: argument -1: expected one argument</span>

  1765. </pre></div>

  1766. </div>

  1767. <p>If you have positional arguments that must begin with <code class="docutils literal notranslate"><span class="pre">-</span></code> and don’t look

  1768. like negative numbers, you can insert the pseudo-argument <code class="docutils literal notranslate"><span class="pre">'--'</span></code> which tells

  1769. <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> that everything after that is a positional

  1770. argument:</p>

  1771. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--&#39;</span><span class="p">,</span> <span class="s1">&#39;-f&#39;</span><span class="p">])</span>

  1772. <span class="go">Namespace(foo=&#39;-f&#39;, one=None)</span>

  1773. </pre></div>

  1774. </div>

  1775. <p>See also <a class="reference internal" href="../howto/argparse.html#specifying-ambiguous-arguments"><span class="std std-ref">the argparse howto on ambiguous arguments</span></a>

  1776. for more details.</p>

  1777. </section>

  1778. <section id="argument-abbreviations-prefix-matching">

  1779. <span id="prefix-matching"></span><h3>Argument abbreviations (prefix matching)<a class="headerlink" href="#argument-abbreviations-prefix-matching" title="Link to this heading">¶</a></h3>

  1780. <p>The <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> method <a class="reference internal" href="#allow-abbrev"><span class="std std-ref">by default</span></a>

  1781. allows long options to be abbreviated to a prefix, if the abbreviation is

  1782. unambiguous (the prefix matches a unique option):</p>

  1783. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">)</span>

  1784. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-bacon&#39;</span><span class="p">)</span>

  1785. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-badger&#39;</span><span class="p">)</span>

  1786. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;-bac MMM&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>

  1787. <span class="go">Namespace(bacon=&#39;MMM&#39;, badger=None)</span>

  1788. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;-bad WOOD&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>

  1789. <span class="go">Namespace(bacon=None, badger=&#39;WOOD&#39;)</span>

  1790. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;-ba BA&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>

  1791. <span class="go">usage: PROG [-h] [-bacon BACON] [-badger BADGER]</span>

  1792. <span class="go">PROG: error: ambiguous option: -ba could match -badger, -bacon</span>

  1793. </pre></div>

  1794. </div>

  1795. <p>An error is produced for arguments that could produce more than one options.

  1796. This feature can be disabled by setting <a class="reference internal" href="#allow-abbrev"><span class="std std-ref">allow_abbrev</span></a> to <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>

  1797. </section>

  1798. <section id="beyond-sys-argv">

  1799. <span id="args"></span><h3>Beyond <code class="docutils literal notranslate"><span class="pre">sys.argv</span></code><a class="headerlink" href="#beyond-sys-argv" title="Link to this heading">¶</a></h3>

  1800. <p>Sometimes it may be useful to have an ArgumentParser parse arguments other than those

  1801. of <a class="reference internal" href="sys.html#sys.argv" title="sys.argv"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.argv</span></code></a>.  This can be accomplished by passing a list of strings to

  1802. <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a>.  This is useful for testing at the

  1803. interactive prompt:</p>

  1804. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1805. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span>

  1806. <span class="gp">... </span>    <span class="s1">&#39;integers&#39;</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">&#39;int&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">),</span>

  1807. <span class="gp">... </span>    <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;+&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;an integer in the range 0..9&#39;</span><span class="p">)</span>

  1808. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span>

  1809. <span class="gp">... </span>    <span class="s1">&#39;--sum&#39;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">&#39;accumulate&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_const&#39;</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="nb">sum</span><span class="p">,</span>

  1810. <span class="gp">... </span>    <span class="n">default</span><span class="o">=</span><span class="nb">max</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;sum the integers (default: find the max)&#39;</span><span class="p">)</span>

  1811. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;1&#39;</span><span class="p">,</span> <span class="s1">&#39;2&#39;</span><span class="p">,</span> <span class="s1">&#39;3&#39;</span><span class="p">,</span> <span class="s1">&#39;4&#39;</span><span class="p">])</span>

  1812. <span class="go">Namespace(accumulate=&lt;built-in function max&gt;, integers=[1, 2, 3, 4])</span>

  1813. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;1&#39;</span><span class="p">,</span> <span class="s1">&#39;2&#39;</span><span class="p">,</span> <span class="s1">&#39;3&#39;</span><span class="p">,</span> <span class="s1">&#39;4&#39;</span><span class="p">,</span> <span class="s1">&#39;--sum&#39;</span><span class="p">])</span>

  1814. <span class="go">Namespace(accumulate=&lt;built-in function sum&gt;, integers=[1, 2, 3, 4])</span>

  1815. </pre></div>

  1816. </div>

  1817. </section>

  1818. <section id="the-namespace-object">

  1819. <span id="namespace"></span><h3>The Namespace object<a class="headerlink" href="#the-namespace-object" title="Link to this heading">¶</a></h3>

  1820. <dl class="py class">

  1821. <dt class="sig sig-object py" id="argparse.Namespace">

  1822. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">argparse.</span></span><span class="sig-name descname"><span class="pre">Namespace</span></span><a class="headerlink" href="#argparse.Namespace" title="Link to this definition">¶</a></dt>

  1823. <dd><p>Simple class used by default by <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> to create

  1824. an object holding attributes and return it.</p>

  1825. </dd></dl>

  1826. 

  1827. <p>This class is deliberately simple, just an <a class="reference internal" href="functions.html#object" title="object"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a> subclass with a

  1828. readable string representation. If you prefer to have dict-like view of the

  1829. attributes, you can use the standard Python idiom, <a class="reference internal" href="functions.html#vars" title="vars"><code class="xref py py-func docutils literal notranslate"><span class="pre">vars()</span></code></a>:</p>

  1830. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1831. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">)</span>

  1832. <span class="gp">&gt;&gt;&gt; </span><span class="n">args</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;BAR&#39;</span><span class="p">])</span>

  1833. <span class="gp">&gt;&gt;&gt; </span><span class="nb">vars</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>

  1834. <span class="go">{&#39;foo&#39;: &#39;BAR&#39;}</span>

  1835. </pre></div>

  1836. </div>

  1837. <p>It may also be useful to have an <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> assign attributes to an

  1838. already existing object, rather than a new <a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate"><span class="pre">Namespace</span></code></a> object.  This can

  1839. be achieved by specifying the <code class="docutils literal notranslate"><span class="pre">namespace=</span></code> keyword argument:</p>

  1840. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">C</span><span class="p">:</span>

  1841. <span class="gp">... </span>    <span class="k">pass</span>

  1842. <span class="gp">...</span>

  1843. <span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">C</span><span class="p">()</span>

  1844. <span class="gp">&gt;&gt;&gt; </span><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>

  1845. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">)</span>

  1846. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="n">args</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;BAR&#39;</span><span class="p">],</span> <span class="n">namespace</span><span class="o">=</span><span class="n">c</span><span class="p">)</span>

  1847. <span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="o">.</span><span class="n">foo</span>

  1848. <span class="go">&#39;BAR&#39;</span>

  1849. </pre></div>

  1850. </div>

  1851. </section>

  1852. </section>

  1853. <section id="other-utilities">

  1854. <h2>Other utilities<a class="headerlink" href="#other-utilities" title="Link to this heading">¶</a></h2>

  1855. <section id="sub-commands">

  1856. <h3>Sub-commands<a class="headerlink" href="#sub-commands" title="Link to this heading">¶</a></h3>

  1857. <dl class="py method">

  1858. <dt class="sig sig-object py" id="argparse.ArgumentParser.add_subparsers">

  1859. <span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">add_subparsers</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">title</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">description</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">prog</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">parser_class</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">action</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">option_strings</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">dest</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">required</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">help</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">metavar</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.add_subparsers" title="Link to this definition">¶</a></dt>

  1860. <dd><p>Many programs split up their functionality into a number of sub-commands,

  1861. for example, the <code class="docutils literal notranslate"><span class="pre">svn</span></code> program can invoke sub-commands like <code class="docutils literal notranslate"><span class="pre">svn</span>

  1862. <span class="pre">checkout</span></code>, <code class="docutils literal notranslate"><span class="pre">svn</span> <span class="pre">update</span></code>, and <code class="docutils literal notranslate"><span class="pre">svn</span> <span class="pre">commit</span></code>.  Splitting up functionality

  1863. this way can be a particularly good idea when a program performs several

  1864. different functions which require different kinds of command-line arguments.

  1865. <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> supports the creation of such sub-commands with the

  1866. <a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_subparsers()</span></code></a> method.  The <a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_subparsers()</span></code></a> method is normally

  1867. called with no arguments and returns a special action object.  This object

  1868. has a single method, <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_parser()</span></code>, which takes a

  1869. command name and any <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> constructor arguments, and

  1870. returns an <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> object that can be modified as usual.</p>

  1871. <p>Description of parameters:</p>

  1872. <ul class="simple">

  1873. <li><p>title - title for the sub-parser group in help output; by default

  1874. “subcommands” if description is provided, otherwise uses title for

  1875. positional arguments</p></li>

  1876. <li><p>description - description for the sub-parser group in help output, by

  1877. default <code class="docutils literal notranslate"><span class="pre">None</span></code></p></li>

  1878. <li><p>prog - usage information that will be displayed with sub-command help,

  1879. by default the name of the program and any positional arguments before the

  1880. subparser argument</p></li>

  1881. <li><p>parser_class - class which will be used to create sub-parser instances, by

  1882. default the class of the current parser (e.g. ArgumentParser)</p></li>

  1883. <li><p><a class="reference internal" href="#action">action</a> - the basic type of action to be taken when this argument is

  1884. encountered at the command line</p></li>

  1885. <li><p><a class="reference internal" href="#dest">dest</a> - name of the attribute under which sub-command name will be

  1886. stored; by default <code class="docutils literal notranslate"><span class="pre">None</span></code> and no value is stored</p></li>

  1887. <li><p><a class="reference internal" href="#required">required</a> - Whether or not a subcommand must be provided, by default

  1888. <code class="docutils literal notranslate"><span class="pre">False</span></code> (added in 3.7)</p></li>

  1889. <li><p><a class="reference internal" href="#help">help</a> - help for sub-parser group in help output, by default <code class="docutils literal notranslate"><span class="pre">None</span></code></p></li>

  1890. <li><p><a class="reference internal" href="#metavar">metavar</a> - string presenting available sub-commands in help; by default it

  1891. is <code class="docutils literal notranslate"><span class="pre">None</span></code> and presents sub-commands in form {cmd1, cmd2, ..}</p></li>

  1892. </ul>

  1893. <p>Some example usage:</p>

  1894. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># create the top-level parser</span>

  1895. <span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">)</span>

  1896. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_true&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;foo help&#39;</span><span class="p">)</span>

  1897. <span class="gp">&gt;&gt;&gt; </span><span class="n">subparsers</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_subparsers</span><span class="p">(</span><span class="n">help</span><span class="o">=</span><span class="s1">&#39;sub-command help&#39;</span><span class="p">)</span>

  1898. <span class="gp">&gt;&gt;&gt;</span>

  1899. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># create the parser for the &quot;a&quot; command</span>

  1900. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser_a</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;a&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;a help&#39;</span><span class="p">)</span>

  1901. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser_a</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;bar help&#39;</span><span class="p">)</span>

  1902. <span class="gp">&gt;&gt;&gt;</span>

  1903. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># create the parser for the &quot;b&quot; command</span>

  1904. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser_b</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;b&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;b help&#39;</span><span class="p">)</span>

  1905. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser_b</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--baz&#39;</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="s1">&#39;XYZ&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;baz help&#39;</span><span class="p">)</span>

  1906. <span class="gp">&gt;&gt;&gt;</span>

  1907. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># parse some argument lists</span>

  1908. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;a&#39;</span><span class="p">,</span> <span class="s1">&#39;12&#39;</span><span class="p">])</span>

  1909. <span class="go">Namespace(bar=12, foo=False)</span>

  1910. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;b&#39;</span><span class="p">,</span> <span class="s1">&#39;--baz&#39;</span><span class="p">,</span> <span class="s1">&#39;Z&#39;</span><span class="p">])</span>

  1911. <span class="go">Namespace(baz=&#39;Z&#39;, foo=True)</span>

  1912. </pre></div>

  1913. </div>

  1914. <p>Note that the object returned by <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> will only contain

  1915. attributes for the main parser and the subparser that was selected by the

  1916. command line (and not any other subparsers).  So in the example above, when

  1917. the <code class="docutils literal notranslate"><span class="pre">a</span></code> command is specified, only the <code class="docutils literal notranslate"><span class="pre">foo</span></code> and <code class="docutils literal notranslate"><span class="pre">bar</span></code> attributes are

  1918. present, and when the <code class="docutils literal notranslate"><span class="pre">b</span></code> command is specified, only the <code class="docutils literal notranslate"><span class="pre">foo</span></code> and

  1919. <code class="docutils literal notranslate"><span class="pre">baz</span></code> attributes are present.</p>

  1920. <p>Similarly, when a help message is requested from a subparser, only the help

  1921. for that particular parser will be printed.  The help message will not

  1922. include parent parser or sibling parser messages.  (A help message for each

  1923. subparser command, however, can be given by supplying the <code class="docutils literal notranslate"><span class="pre">help=</span></code> argument

  1924. to <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_parser()</span></code> as above.)</p>

  1925. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--help&#39;</span><span class="p">])</span>

  1926. <span class="go">usage: PROG [-h] [--foo] {a,b} ...</span>

  1927. 

  1928. <span class="go">positional arguments:</span>

  1929. <span class="go">  {a,b}   sub-command help</span>

  1930. <span class="go">    a     a help</span>

  1931. <span class="go">    b     b help</span>

  1932. 

  1933. <span class="go">options:</span>

  1934. <span class="go">  -h, --help  show this help message and exit</span>

  1935. <span class="go">  --foo   foo help</span>

  1936. 

  1937. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;a&#39;</span><span class="p">,</span> <span class="s1">&#39;--help&#39;</span><span class="p">])</span>

  1938. <span class="go">usage: PROG a [-h] bar</span>

  1939. 

  1940. <span class="go">positional arguments:</span>

  1941. <span class="go">  bar     bar help</span>

  1942. 

  1943. <span class="go">options:</span>

  1944. <span class="go">  -h, --help  show this help message and exit</span>

  1945. 

  1946. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;b&#39;</span><span class="p">,</span> <span class="s1">&#39;--help&#39;</span><span class="p">])</span>

  1947. <span class="go">usage: PROG b [-h] [--baz {X,Y,Z}]</span>

  1948. 

  1949. <span class="go">options:</span>

  1950. <span class="go">  -h, --help     show this help message and exit</span>

  1951. <span class="go">  --baz {X,Y,Z}  baz help</span>

  1952. </pre></div>

  1953. </div>

  1954. <p>The <a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_subparsers()</span></code></a> method also supports <code class="docutils literal notranslate"><span class="pre">title</span></code> and <code class="docutils literal notranslate"><span class="pre">description</span></code>

  1955. keyword arguments.  When either is present, the subparser’s commands will

  1956. appear in their own group in the help output.  For example:</p>

  1957. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1958. <span class="gp">&gt;&gt;&gt; </span><span class="n">subparsers</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_subparsers</span><span class="p">(</span><span class="n">title</span><span class="o">=</span><span class="s1">&#39;subcommands&#39;</span><span class="p">,</span>

  1959. <span class="gp">... </span>                                   <span class="n">description</span><span class="o">=</span><span class="s1">&#39;valid subcommands&#39;</span><span class="p">,</span>

  1960. <span class="gp">... </span>                                   <span class="n">help</span><span class="o">=</span><span class="s1">&#39;additional help&#39;</span><span class="p">)</span>

  1961. <span class="gp">&gt;&gt;&gt; </span><span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">)</span>

  1962. <span class="gp">&gt;&gt;&gt; </span><span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>

  1963. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-h&#39;</span><span class="p">])</span>

  1964. <span class="go">usage:  [-h] {foo,bar} ...</span>

  1965. 

  1966. <span class="go">options:</span>

  1967. <span class="go">  -h, --help  show this help message and exit</span>

  1968. 

  1969. <span class="go">subcommands:</span>

  1970. <span class="go">  valid subcommands</span>

  1971. 

  1972. <span class="go">  {foo,bar}   additional help</span>

  1973. </pre></div>

  1974. </div>

  1975. <p>Furthermore, <code class="docutils literal notranslate"><span class="pre">add_parser</span></code> supports an additional <code class="docutils literal notranslate"><span class="pre">aliases</span></code> argument,

  1976. which allows multiple strings to refer to the same subparser. This example,

  1977. like <code class="docutils literal notranslate"><span class="pre">svn</span></code>, aliases <code class="docutils literal notranslate"><span class="pre">co</span></code> as a shorthand for <code class="docutils literal notranslate"><span class="pre">checkout</span></code>:</p>

  1978. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  1979. <span class="gp">&gt;&gt;&gt; </span><span class="n">subparsers</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_subparsers</span><span class="p">()</span>

  1980. <span class="gp">&gt;&gt;&gt; </span><span class="n">checkout</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;checkout&#39;</span><span class="p">,</span> <span class="n">aliases</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;co&#39;</span><span class="p">])</span>

  1981. <span class="gp">&gt;&gt;&gt; </span><span class="n">checkout</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">)</span>

  1982. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;co&#39;</span><span class="p">,</span> <span class="s1">&#39;bar&#39;</span><span class="p">])</span>

  1983. <span class="go">Namespace(foo=&#39;bar&#39;)</span>

  1984. </pre></div>

  1985. </div>

  1986. <p>One particularly effective way of handling sub-commands is to combine the use

  1987. of the <a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_subparsers()</span></code></a> method with calls to <a class="reference internal" href="#argparse.ArgumentParser.set_defaults" title="argparse.ArgumentParser.set_defaults"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_defaults()</span></code></a> so

  1988. that each subparser knows which Python function it should execute.  For

  1989. example:</p>

  1990. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># sub-command functions</span>

  1991. <span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="n">args</span><span class="p">):</span>

  1992. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="n">args</span><span class="o">.</span><span class="n">x</span> <span class="o">*</span> <span class="n">args</span><span class="o">.</span><span class="n">y</span><span class="p">)</span>

  1993. <span class="gp">...</span>

  1994. <span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">bar</span><span class="p">(</span><span class="n">args</span><span class="p">):</span>

  1995. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;((</span><span class="si">%s</span><span class="s1">))&#39;</span> <span class="o">%</span> <span class="n">args</span><span class="o">.</span><span class="n">z</span><span class="p">)</span>

  1996. <span class="gp">...</span>

  1997. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># create the top-level parser</span>

  1998. <span class="gp">&gt;&gt;&gt; </span><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>

  1999. <span class="gp">&gt;&gt;&gt; </span><span class="n">subparsers</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_subparsers</span><span class="p">(</span><span class="n">required</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>

  2000. <span class="gp">&gt;&gt;&gt;</span>

  2001. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># create the parser for the &quot;foo&quot; command</span>

  2002. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser_foo</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">)</span>

  2003. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser_foo</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-x&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>

  2004. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser_foo</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;y&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">float</span><span class="p">)</span>

  2005. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser_foo</span><span class="o">.</span><span class="n">set_defaults</span><span class="p">(</span><span class="n">func</span><span class="o">=</span><span class="n">foo</span><span class="p">)</span>

  2006. <span class="gp">&gt;&gt;&gt;</span>

  2007. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># create the parser for the &quot;bar&quot; command</span>

  2008. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser_bar</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>

  2009. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser_bar</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;z&#39;</span><span class="p">)</span>

  2010. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser_bar</span><span class="o">.</span><span class="n">set_defaults</span><span class="p">(</span><span class="n">func</span><span class="o">=</span><span class="n">bar</span><span class="p">)</span>

  2011. <span class="gp">&gt;&gt;&gt;</span>

  2012. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># parse the args and call whatever function was selected</span>

  2013. <span class="gp">&gt;&gt;&gt; </span><span class="n">args</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;foo 1 -x 2&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>

  2014. <span class="gp">&gt;&gt;&gt; </span><span class="n">args</span><span class="o">.</span><span class="n">func</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>

  2015. <span class="go">2.0</span>

  2016. <span class="gp">&gt;&gt;&gt;</span>

  2017. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># parse the args and call whatever function was selected</span>

  2018. <span class="gp">&gt;&gt;&gt; </span><span class="n">args</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;bar XYZYX&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>

  2019. <span class="gp">&gt;&gt;&gt; </span><span class="n">args</span><span class="o">.</span><span class="n">func</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>

  2020. <span class="go">((XYZYX))</span>

  2021. </pre></div>

  2022. </div>

  2023. <p>This way, you can let <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> do the job of calling the

  2024. appropriate function after argument parsing is complete.  Associating

  2025. functions with actions like this is typically the easiest way to handle the

  2026. different actions for each of your subparsers.  However, if it is necessary

  2027. to check the name of the subparser that was invoked, the <code class="docutils literal notranslate"><span class="pre">dest</span></code> keyword

  2028. argument to the <a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_subparsers()</span></code></a> call will work:</p>

  2029. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  2030. <span class="gp">&gt;&gt;&gt; </span><span class="n">subparsers</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_subparsers</span><span class="p">(</span><span class="n">dest</span><span class="o">=</span><span class="s1">&#39;subparser_name&#39;</span><span class="p">)</span>

  2031. <span class="gp">&gt;&gt;&gt; </span><span class="n">subparser1</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;1&#39;</span><span class="p">)</span>

  2032. <span class="gp">&gt;&gt;&gt; </span><span class="n">subparser1</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-x&#39;</span><span class="p">)</span>

  2033. <span class="gp">&gt;&gt;&gt; </span><span class="n">subparser2</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;2&#39;</span><span class="p">)</span>

  2034. <span class="gp">&gt;&gt;&gt; </span><span class="n">subparser2</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;y&#39;</span><span class="p">)</span>

  2035. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;2&#39;</span><span class="p">,</span> <span class="s1">&#39;frobble&#39;</span><span class="p">])</span>

  2036. <span class="go">Namespace(subparser_name=&#39;2&#39;, y=&#39;frobble&#39;)</span>

  2037. </pre></div>

  2038. </div>

  2039. <div class="versionchanged">

  2040. <p><span class="versionmodified changed">Changed in version 3.7: </span>New <em>required</em> keyword argument.</p>

  2041. </div>

  2042. </dd></dl>

  2043. 

  2044. </section>

  2045. <section id="filetype-objects">

  2046. <h3>FileType objects<a class="headerlink" href="#filetype-objects" title="Link to this heading">¶</a></h3>

  2047. <dl class="py class">

  2048. <dt class="sig sig-object py" id="argparse.FileType">

  2049. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">argparse.</span></span><span class="sig-name descname"><span class="pre">FileType</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">mode</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'r'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">bufsize</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">errors</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="#argparse.FileType" title="Link to this definition">¶</a></dt>

  2050. <dd><p>The <a class="reference internal" href="#argparse.FileType" title="argparse.FileType"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileType</span></code></a> factory creates objects that can be passed to the type

  2051. argument of <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ArgumentParser.add_argument()</span></code></a>.  Arguments that have

  2052. <a class="reference internal" href="#argparse.FileType" title="argparse.FileType"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileType</span></code></a> objects as their type will open command-line arguments as

  2053. files with the requested modes, buffer sizes, encodings and error handling

  2054. (see the <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> function for more details):</p>

  2055. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  2056. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--raw&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">FileType</span><span class="p">(</span><span class="s1">&#39;wb&#39;</span><span class="p">,</span> <span class="mi">0</span><span class="p">))</span>

  2057. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;out&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">FileType</span><span class="p">(</span><span class="s1">&#39;w&#39;</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s1">&#39;UTF-8&#39;</span><span class="p">))</span>

  2058. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--raw&#39;</span><span class="p">,</span> <span class="s1">&#39;raw.dat&#39;</span><span class="p">,</span> <span class="s1">&#39;file.txt&#39;</span><span class="p">])</span>

  2059. <span class="go">Namespace(out=&lt;_io.TextIOWrapper name=&#39;file.txt&#39; mode=&#39;w&#39; encoding=&#39;UTF-8&#39;&gt;, raw=&lt;_io.FileIO name=&#39;raw.dat&#39; mode=&#39;wb&#39;&gt;)</span>

  2060. </pre></div>

  2061. </div>

  2062. <p>FileType objects understand the pseudo-argument <code class="docutils literal notranslate"><span class="pre">'-'</span></code> and automatically

  2063. convert this into <a class="reference internal" href="sys.html#sys.stdin" title="sys.stdin"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdin</span></code></a> for readable <a class="reference internal" href="#argparse.FileType" title="argparse.FileType"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileType</span></code></a> objects and

  2064. <a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdout</span></code></a> for writable <a class="reference internal" href="#argparse.FileType" title="argparse.FileType"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileType</span></code></a> objects:</p>

  2065. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  2066. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;infile&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">FileType</span><span class="p">(</span><span class="s1">&#39;r&#39;</span><span class="p">))</span>

  2067. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-&#39;</span><span class="p">])</span>

  2068. <span class="go">Namespace(infile=&lt;_io.TextIOWrapper name=&#39;&lt;stdin&gt;&#39; encoding=&#39;UTF-8&#39;&gt;)</span>

  2069. </pre></div>

  2070. </div>

  2071. <div class="versionchanged">

  2072. <p><span class="versionmodified changed">Changed in version 3.4: </span>Added the <em>encodings</em> and <em>errors</em> parameters.</p>

  2073. </div>

  2074. </dd></dl>

  2075. 

  2076. </section>

  2077. <section id="argument-groups">

  2078. <h3>Argument groups<a class="headerlink" href="#argument-groups" title="Link to this heading">¶</a></h3>

  2079. <dl class="py method">

  2080. <dt class="sig sig-object py" id="argparse.ArgumentParser.add_argument_group">

  2081. <span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">add_argument_group</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">title</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</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="#argparse.ArgumentParser.add_argument_group" title="Link to this definition">¶</a></dt>

  2082. <dd><p>By default, <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> groups command-line arguments into

  2083. “positional arguments” and “options” when displaying help

  2084. messages. When there is a better conceptual grouping of arguments than this

  2085. default one, appropriate groups can be created using the

  2086. <a class="reference internal" href="#argparse.ArgumentParser.add_argument_group" title="argparse.ArgumentParser.add_argument_group"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument_group()</span></code></a> method:</p>

  2087. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">,</span> <span class="n">add_help</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>

  2088. <span class="gp">&gt;&gt;&gt; </span><span class="n">group</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_argument_group</span><span class="p">(</span><span class="s1">&#39;group&#39;</span><span class="p">)</span>

  2089. <span class="gp">&gt;&gt;&gt; </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;foo help&#39;</span><span class="p">)</span>

  2090. <span class="gp">&gt;&gt;&gt; </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;bar help&#39;</span><span class="p">)</span>

  2091. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>

  2092. <span class="go">usage: PROG [--foo FOO] bar</span>

  2093. 

  2094. <span class="go">group:</span>

  2095. <span class="go">  bar    bar help</span>

  2096. <span class="go">  --foo FOO  foo help</span>

  2097. </pre></div>

  2098. </div>

  2099. <p>The <a class="reference internal" href="#argparse.ArgumentParser.add_argument_group" title="argparse.ArgumentParser.add_argument_group"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument_group()</span></code></a> method returns an argument group object which

  2100. has an <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> method just like a regular

  2101. <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>.  When an argument is added to the group, the parser

  2102. treats it just like a normal argument, but displays the argument in a

  2103. separate group for help messages.  The <a class="reference internal" href="#argparse.ArgumentParser.add_argument_group" title="argparse.ArgumentParser.add_argument_group"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument_group()</span></code></a> method

  2104. accepts <em>title</em> and <em>description</em> arguments which can be used to

  2105. customize this display:</p>

  2106. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">,</span> <span class="n">add_help</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>

  2107. <span class="gp">&gt;&gt;&gt; </span><span class="n">group1</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_argument_group</span><span class="p">(</span><span class="s1">&#39;group1&#39;</span><span class="p">,</span> <span class="s1">&#39;group1 description&#39;</span><span class="p">)</span>

  2108. <span class="gp">&gt;&gt;&gt; </span><span class="n">group1</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;foo help&#39;</span><span class="p">)</span>

  2109. <span class="gp">&gt;&gt;&gt; </span><span class="n">group2</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_argument_group</span><span class="p">(</span><span class="s1">&#39;group2&#39;</span><span class="p">,</span> <span class="s1">&#39;group2 description&#39;</span><span class="p">)</span>

  2110. <span class="gp">&gt;&gt;&gt; </span><span class="n">group2</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--bar&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;bar help&#39;</span><span class="p">)</span>

  2111. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>

  2112. <span class="go">usage: PROG [--bar BAR] foo</span>

  2113. 

  2114. <span class="go">group1:</span>

  2115. <span class="go">  group1 description</span>

  2116. 

  2117. <span class="go">  foo    foo help</span>

  2118. 

  2119. <span class="go">group2:</span>

  2120. <span class="go">  group2 description</span>

  2121. 

  2122. <span class="go">  --bar BAR  bar help</span>

  2123. </pre></div>

  2124. </div>

  2125. <p>Note that any arguments not in your user-defined groups will end up back

  2126. in the usual “positional arguments” and “optional arguments” sections.</p>

  2127. <div class="versionchanged">

  2128. <p><span class="versionmodified changed">Changed in version 3.11: </span>Calling <a class="reference internal" href="#argparse.ArgumentParser.add_argument_group" title="argparse.ArgumentParser.add_argument_group"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument_group()</span></code></a> on an argument group is deprecated.

  2129. This feature was never supported and does not always work correctly.

  2130. The function exists on the API by accident through inheritance and

  2131. will be removed in the future.</p>

  2132. </div>

  2133. </dd></dl>

  2134. 

  2135. </section>

  2136. <section id="mutual-exclusion">

  2137. <h3>Mutual exclusion<a class="headerlink" href="#mutual-exclusion" title="Link to this heading">¶</a></h3>

  2138. <dl class="py method">

  2139. <dt class="sig sig-object py" id="argparse.ArgumentParser.add_mutually_exclusive_group">

  2140. <span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">add_mutually_exclusive_group</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">required</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.add_mutually_exclusive_group" title="Link to this definition">¶</a></dt>

  2141. <dd><p>Create a mutually exclusive group. <a class="reference internal" href="#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> will make sure that only

  2142. one of the arguments in the mutually exclusive group was present on the

  2143. command line:</p>

  2144. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">)</span>

  2145. <span class="gp">&gt;&gt;&gt; </span><span class="n">group</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_mutually_exclusive_group</span><span class="p">()</span>

  2146. <span class="gp">&gt;&gt;&gt; </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_true&#39;</span><span class="p">)</span>

  2147. <span class="gp">&gt;&gt;&gt; </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--bar&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_false&#39;</span><span class="p">)</span>

  2148. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">])</span>

  2149. <span class="go">Namespace(bar=True, foo=True)</span>

  2150. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--bar&#39;</span><span class="p">])</span>

  2151. <span class="go">Namespace(bar=False, foo=False)</span>

  2152. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;--bar&#39;</span><span class="p">])</span>

  2153. <span class="go">usage: PROG [-h] [--foo | --bar]</span>

  2154. <span class="go">PROG: error: argument --bar: not allowed with argument --foo</span>

  2155. </pre></div>

  2156. </div>

  2157. <p>The <a class="reference internal" href="#argparse.ArgumentParser.add_mutually_exclusive_group" title="argparse.ArgumentParser.add_mutually_exclusive_group"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_mutually_exclusive_group()</span></code></a> method also accepts a <em>required</em>

  2158. argument, to indicate that at least one of the mutually exclusive arguments

  2159. is required:</p>

  2160. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">)</span>

  2161. <span class="gp">&gt;&gt;&gt; </span><span class="n">group</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_mutually_exclusive_group</span><span class="p">(</span><span class="n">required</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>

  2162. <span class="gp">&gt;&gt;&gt; </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_true&#39;</span><span class="p">)</span>

  2163. <span class="gp">&gt;&gt;&gt; </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--bar&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_false&#39;</span><span class="p">)</span>

  2164. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>

  2165. <span class="go">usage: PROG [-h] (--foo | --bar)</span>

  2166. <span class="go">PROG: error: one of the arguments --foo --bar is required</span>

  2167. </pre></div>

  2168. </div>

  2169. <p>Note that currently mutually exclusive argument groups do not support the

  2170. <em>title</em> and <em>description</em> arguments of

  2171. <a class="reference internal" href="#argparse.ArgumentParser.add_argument_group" title="argparse.ArgumentParser.add_argument_group"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument_group()</span></code></a>. However, a mutually exclusive

  2172. group can be added to an argument group that has a title and description.

  2173. For example:</p>

  2174. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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><span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">)</span>

  2175. <span class="gp">&gt;&gt;&gt; </span><span class="n">group</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_argument_group</span><span class="p">(</span><span class="s1">&#39;Group title&#39;</span><span class="p">,</span> <span class="s1">&#39;Group description&#39;</span><span class="p">)</span>

  2176. <span class="gp">&gt;&gt;&gt; </span><span class="n">exclusive_group</span> <span class="o">=</span> <span class="n">group</span><span class="o">.</span><span class="n">add_mutually_exclusive_group</span><span class="p">(</span><span class="n">required</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>

  2177. <span class="gp">&gt;&gt;&gt; </span><span class="n">exclusive_group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;foo help&#39;</span><span class="p">)</span>

  2178. <span class="gp">&gt;&gt;&gt; </span><span class="n">exclusive_group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--bar&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;bar help&#39;</span><span class="p">)</span>

  2179. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>

  2180. <span class="go">usage: PROG [-h] (--foo FOO | --bar BAR)</span>

  2181. 

  2182. <span class="go">options:</span>

  2183. <span class="go">  -h, --help  show this help message and exit</span>

  2184. 

  2185. <span class="go">Group title:</span>

  2186. <span class="go">  Group description</span>

  2187. 

  2188. <span class="go">  --foo FOO   foo help</span>

  2189. <span class="go">  --bar BAR   bar help</span>

  2190. </pre></div>

  2191. </div>

  2192. <div class="versionchanged">

  2193. <p><span class="versionmodified changed">Changed in version 3.11: </span>Calling <a class="reference internal" href="#argparse.ArgumentParser.add_argument_group" title="argparse.ArgumentParser.add_argument_group"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument_group()</span></code></a> or <a class="reference internal" href="#argparse.ArgumentParser.add_mutually_exclusive_group" title="argparse.ArgumentParser.add_mutually_exclusive_group"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_mutually_exclusive_group()</span></code></a>

  2194. on a mutually exclusive group is deprecated. These features were never

  2195. supported and do not always work correctly. The functions exist on the

  2196. API by accident through inheritance and will be removed in the future.</p>

  2197. </div>

  2198. </dd></dl>

  2199. 

  2200. </section>

  2201. <section id="parser-defaults">

  2202. <h3>Parser defaults<a class="headerlink" href="#parser-defaults" title="Link to this heading">¶</a></h3>

  2203. <dl class="py method">

  2204. <dt class="sig sig-object py" id="argparse.ArgumentParser.set_defaults">

  2205. <span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">set_defaults</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.set_defaults" title="Link to this definition">¶</a></dt>

  2206. <dd><p>Most of the time, the attributes of the object returned by <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a>

  2207. will be fully determined by inspecting the command-line arguments and the argument

  2208. actions.  <a class="reference internal" href="#argparse.ArgumentParser.set_defaults" title="argparse.ArgumentParser.set_defaults"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_defaults()</span></code></a> allows some additional

  2209. attributes that are determined without any inspection of the command line to

  2210. be added:</p>

  2211. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  2212. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>

  2213. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">set_defaults</span><span class="p">(</span><span class="n">bar</span><span class="o">=</span><span class="mi">42</span><span class="p">,</span> <span class="n">baz</span><span class="o">=</span><span class="s1">&#39;badger&#39;</span><span class="p">)</span>

  2214. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;736&#39;</span><span class="p">])</span>

  2215. <span class="go">Namespace(bar=42, baz=&#39;badger&#39;, foo=736)</span>

  2216. </pre></div>

  2217. </div>

  2218. <p>Note that parser-level defaults always override argument-level defaults:</p>

  2219. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  2220. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>

  2221. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">set_defaults</span><span class="p">(</span><span class="n">foo</span><span class="o">=</span><span class="s1">&#39;spam&#39;</span><span class="p">)</span>

  2222. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>

  2223. <span class="go">Namespace(foo=&#39;spam&#39;)</span>

  2224. </pre></div>

  2225. </div>

  2226. <p>Parser-level defaults can be particularly useful when working with multiple

  2227. parsers.  See the <a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_subparsers()</span></code></a> method for an

  2228. example of this type.</p>

  2229. </dd></dl>

  2230. 

  2231. <dl class="py method">

  2232. <dt class="sig sig-object py" id="argparse.ArgumentParser.get_default">

  2233. <span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">get_default</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dest</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.get_default" title="Link to this definition">¶</a></dt>

  2234. <dd><p>Get the default value for a namespace attribute, as set by either

  2235. <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> or by

  2236. <a class="reference internal" href="#argparse.ArgumentParser.set_defaults" title="argparse.ArgumentParser.set_defaults"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_defaults()</span></code></a>:</p>

  2237. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  2238. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">&#39;badger&#39;</span><span class="p">)</span>

  2239. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">get_default</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">)</span>

  2240. <span class="go">&#39;badger&#39;</span>

  2241. </pre></div>

  2242. </div>

  2243. </dd></dl>

  2244. 

  2245. </section>

  2246. <section id="printing-help">

  2247. <h3>Printing help<a class="headerlink" href="#printing-help" title="Link to this heading">¶</a></h3>

  2248. <p>In most typical applications, <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> will take

  2249. care of formatting and printing any usage or error messages.  However, several

  2250. formatting methods are available:</p>

  2251. <dl class="py method">

  2252. <dt class="sig sig-object py" id="argparse.ArgumentParser.print_usage">

  2253. <span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">print_usage</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="#argparse.ArgumentParser.print_usage" title="Link to this definition">¶</a></dt>

  2254. <dd><p>Print a brief description of how the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> should be

  2255. invoked on the command line.  If <em>file</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, <a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdout</span></code></a> is

  2256. assumed.</p>

  2257. </dd></dl>

  2258. 

  2259. <dl class="py method">

  2260. <dt class="sig sig-object py" id="argparse.ArgumentParser.print_help">

  2261. <span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">print_help</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="#argparse.ArgumentParser.print_help" title="Link to this definition">¶</a></dt>

  2262. <dd><p>Print a help message, including the program usage and information about the

  2263. arguments registered with the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>.  If <em>file</em> is

  2264. <code class="docutils literal notranslate"><span class="pre">None</span></code>, <a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdout</span></code></a> is assumed.</p>

  2265. </dd></dl>

  2266. 

  2267. <p>There are also variants of these methods that simply return a string instead of

  2268. printing it:</p>

  2269. <dl class="py method">

  2270. <dt class="sig sig-object py" id="argparse.ArgumentParser.format_usage">

  2271. <span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">format_usage</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.format_usage" title="Link to this definition">¶</a></dt>

  2272. <dd><p>Return a string containing a brief description of how the

  2273. <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> should be invoked on the command line.</p>

  2274. </dd></dl>

  2275. 

  2276. <dl class="py method">

  2277. <dt class="sig sig-object py" id="argparse.ArgumentParser.format_help">

  2278. <span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">format_help</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.format_help" title="Link to this definition">¶</a></dt>

  2279. <dd><p>Return a string containing a help message, including the program usage and

  2280. information about the arguments registered with the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>.</p>

  2281. </dd></dl>

  2282. 

  2283. </section>

  2284. <section id="partial-parsing">

  2285. <h3>Partial parsing<a class="headerlink" href="#partial-parsing" title="Link to this heading">¶</a></h3>

  2286. <dl class="py method">

  2287. <dt class="sig sig-object py" id="argparse.ArgumentParser.parse_known_args">

  2288. <span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">parse_known_args</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">namespace</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="#argparse.ArgumentParser.parse_known_args" title="Link to this definition">¶</a></dt>

  2289. <dd></dd></dl>

  2290. 

  2291. <p>Sometimes a script may only parse a few of the command-line arguments, passing

  2292. the remaining arguments on to another script or program. In these cases, the

  2293. <a class="reference internal" href="#argparse.ArgumentParser.parse_known_args" title="argparse.ArgumentParser.parse_known_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_known_args()</span></code></a> method can be useful.  It works much like

  2294. <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> except that it does not produce an error when

  2295. extra arguments are present.  Instead, it returns a two item tuple containing

  2296. the populated namespace and the list of remaining argument strings.</p>

  2297. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  2298. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_true&#39;</span><span class="p">)</span>

  2299. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>

  2300. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_known_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;--badger&#39;</span><span class="p">,</span> <span class="s1">&#39;BAR&#39;</span><span class="p">,</span> <span class="s1">&#39;spam&#39;</span><span class="p">])</span>

  2301. <span class="go">(Namespace(bar=&#39;BAR&#39;, foo=True), [&#39;--badger&#39;, &#39;spam&#39;])</span>

  2302. </pre></div>

  2303. </div>

  2304. <div class="admonition warning">

  2305. <p class="admonition-title">Warning</p>

  2306. <p><a class="reference internal" href="#prefix-matching"><span class="std std-ref">Prefix matching</span></a> rules apply to

  2307. <a class="reference internal" href="#argparse.ArgumentParser.parse_known_args" title="argparse.ArgumentParser.parse_known_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_known_args()</span></code></a>. The parser may consume an option even if it’s just

  2308. a prefix of one of its known options, instead of leaving it in the remaining

  2309. arguments list.</p>

  2310. </div>

  2311. </section>

  2312. <section id="customizing-file-parsing">

  2313. <h3>Customizing file parsing<a class="headerlink" href="#customizing-file-parsing" title="Link to this heading">¶</a></h3>

  2314. <dl class="py method">

  2315. <dt class="sig sig-object py" id="argparse.ArgumentParser.convert_arg_line_to_args">

  2316. <span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">convert_arg_line_to_args</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">arg_line</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.convert_arg_line_to_args" title="Link to this definition">¶</a></dt>

  2317. <dd><p>Arguments that are read from a file (see the <em>fromfile_prefix_chars</em>

  2318. keyword argument to the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> constructor) are read one

  2319. argument per line. <a class="reference internal" href="#argparse.ArgumentParser.convert_arg_line_to_args" title="argparse.ArgumentParser.convert_arg_line_to_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">convert_arg_line_to_args()</span></code></a> can be overridden for

  2320. fancier reading.</p>

  2321. <p>This method takes a single argument <em>arg_line</em> which is a string read from

  2322. the argument file.  It returns a list of arguments parsed from this string.

  2323. The method is called once per line read from the argument file, in order.</p>

  2324. <p>A useful override of this method is one that treats each space-separated word

  2325. as an argument.  The following example demonstrates how to do this:</p>

  2326. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MyArgumentParser</span><span class="p">(</span><span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">):</span>

  2327.     <span class="k">def</span> <span class="nf">convert_arg_line_to_args</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">arg_line</span><span class="p">):</span>

  2328.         <span class="k">return</span> <span class="n">arg_line</span><span class="o">.</span><span class="n">split</span><span class="p">()</span>

  2329. </pre></div>

  2330. </div>

  2331. </dd></dl>

  2332. 

  2333. </section>

  2334. <section id="exiting-methods">

  2335. <h3>Exiting methods<a class="headerlink" href="#exiting-methods" title="Link to this heading">¶</a></h3>

  2336. <dl class="py method">

  2337. <dt class="sig sig-object py" id="argparse.ArgumentParser.exit">

  2338. <span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">exit</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">status</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">message</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="#argparse.ArgumentParser.exit" title="Link to this definition">¶</a></dt>

  2339. <dd><p>This method terminates the program, exiting with the specified <em>status</em>

  2340. and, if given, it prints a <em>message</em> before that. The user can override

  2341. this method to handle these steps differently:</p>

  2342. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">ErrorCatchingArgumentParser</span><span class="p">(</span><span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">):</span>

  2343.     <span class="k">def</span> <span class="nf">exit</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">status</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">message</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  2344.         <span class="k">if</span> <span class="n">status</span><span class="p">:</span>

  2345.             <span class="k">raise</span> <span class="ne">Exception</span><span class="p">(</span><span class="sa">f</span><span class="s1">&#39;Exiting because of an error: </span><span class="si">{</span><span class="n">message</span><span class="si">}</span><span class="s1">&#39;</span><span class="p">)</span>

  2346.         <span class="n">exit</span><span class="p">(</span><span class="n">status</span><span class="p">)</span>

  2347. </pre></div>

  2348. </div>

  2349. </dd></dl>

  2350. 

  2351. <dl class="py method">

  2352. <dt class="sig sig-object py" id="argparse.ArgumentParser.error">

  2353. <span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">error</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">message</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.error" title="Link to this definition">¶</a></dt>

  2354. <dd><p>This method prints a usage message including the <em>message</em> to the

  2355. standard error and terminates the program with a status code of 2.</p>

  2356. </dd></dl>

  2357. 

  2358. </section>

  2359. <section id="intermixed-parsing">

  2360. <h3>Intermixed parsing<a class="headerlink" href="#intermixed-parsing" title="Link to this heading">¶</a></h3>

  2361. <dl class="py method">

  2362. <dt class="sig sig-object py" id="argparse.ArgumentParser.parse_intermixed_args">

  2363. <span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">parse_intermixed_args</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">namespace</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="#argparse.ArgumentParser.parse_intermixed_args" title="Link to this definition">¶</a></dt>

  2364. <dd></dd></dl>

  2365. 

  2366. <dl class="py method">

  2367. <dt class="sig sig-object py" id="argparse.ArgumentParser.parse_known_intermixed_args">

  2368. <span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">parse_known_intermixed_args</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">namespace</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="#argparse.ArgumentParser.parse_known_intermixed_args" title="Link to this definition">¶</a></dt>

  2369. <dd></dd></dl>

  2370. 

  2371. <p>A number of Unix commands allow the user to intermix optional arguments with

  2372. positional arguments.  The <a class="reference internal" href="#argparse.ArgumentParser.parse_intermixed_args" title="argparse.ArgumentParser.parse_intermixed_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_intermixed_args()</span></code></a>

  2373. and <a class="reference internal" href="#argparse.ArgumentParser.parse_known_intermixed_args" title="argparse.ArgumentParser.parse_known_intermixed_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_known_intermixed_args()</span></code></a> methods

  2374. support this parsing style.</p>

  2375. <p>These parsers do not support all the argparse features, and will raise

  2376. exceptions if unsupported features are used.  In particular, subparsers,

  2377. and mutually exclusive groups that include both

  2378. optionals and positionals are not supported.</p>

  2379. <p>The following example shows the difference between

  2380. <a class="reference internal" href="#argparse.ArgumentParser.parse_known_args" title="argparse.ArgumentParser.parse_known_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_known_args()</span></code></a> and

  2381. <a class="reference internal" href="#argparse.ArgumentParser.parse_intermixed_args" title="argparse.ArgumentParser.parse_intermixed_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_intermixed_args()</span></code></a>: the former returns <code class="docutils literal notranslate"><span class="pre">['2',</span>

  2382. <span class="pre">'3']</span></code> as unparsed arguments, while the latter collects all the positionals

  2383. into <code class="docutils literal notranslate"><span class="pre">rest</span></code>.</p>

  2384. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><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>

  2385. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">)</span>

  2386. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;cmd&#39;</span><span class="p">)</span>

  2387. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;rest&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;*&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>

  2388. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_known_args</span><span class="p">(</span><span class="s1">&#39;doit 1 --foo bar 2 3&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>

  2389. <span class="go">(Namespace(cmd=&#39;doit&#39;, foo=&#39;bar&#39;, rest=[1]), [&#39;2&#39;, &#39;3&#39;])</span>

  2390. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_intermixed_args</span><span class="p">(</span><span class="s1">&#39;doit 1 --foo bar 2 3&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>

  2391. <span class="go">Namespace(cmd=&#39;doit&#39;, foo=&#39;bar&#39;, rest=[1, 2, 3])</span>

  2392. </pre></div>

  2393. </div>

  2394. <p><a class="reference internal" href="#argparse.ArgumentParser.parse_known_intermixed_args" title="argparse.ArgumentParser.parse_known_intermixed_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_known_intermixed_args()</span></code></a> returns a two item tuple

  2395. containing the populated namespace and the list of remaining argument strings.

  2396. <a class="reference internal" href="#argparse.ArgumentParser.parse_intermixed_args" title="argparse.ArgumentParser.parse_intermixed_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_intermixed_args()</span></code></a> raises an error if there are any

  2397. remaining unparsed argument strings.</p>

  2398. <div class="versionadded">

  2399. <p><span class="versionmodified added">New in version 3.7.</span></p>

  2400. </div>

  2401. </section>

  2402. </section>

  2403. <section id="upgrading-optparse-code">

  2404. <span id="id15"></span><h2>Upgrading optparse code<a class="headerlink" href="#upgrading-optparse-code" title="Link to this heading">¶</a></h2>

  2405. <p>Originally, the <a class="reference internal" href="#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> module had attempted to maintain compatibility

  2406. with <a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a>.  However, <a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> was difficult to extend

  2407. transparently, particularly with the changes required to support the new

  2408. <code class="docutils literal notranslate"><span class="pre">nargs=</span></code> specifiers and better usage messages.  When most everything in

  2409. <a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> had either been copy-pasted over or monkey-patched, it no

  2410. longer seemed practical to try to maintain the backwards compatibility.</p>

  2411. <p>The <a class="reference internal" href="#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> module improves on the standard library <a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a>

  2412. module in a number of ways including:</p>

  2413. <ul class="simple">

  2414. <li><p>Handling positional arguments.</p></li>

  2415. <li><p>Supporting sub-commands.</p></li>

  2416. <li><p>Allowing alternative option prefixes like <code class="docutils literal notranslate"><span class="pre">+</span></code> and <code class="docutils literal notranslate"><span class="pre">/</span></code>.</p></li>

  2417. <li><p>Handling zero-or-more and one-or-more style arguments.</p></li>

  2418. <li><p>Producing more informative usage messages.</p></li>

  2419. <li><p>Providing a much simpler interface for custom <code class="docutils literal notranslate"><span class="pre">type</span></code> and <code class="docutils literal notranslate"><span class="pre">action</span></code>.</p></li>

  2420. </ul>

  2421. <p>A partial upgrade path from <a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> to <a class="reference internal" href="#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>

  2422. <ul class="simple">

  2423. <li><p>Replace all <a class="reference internal" href="optparse.html#optparse.OptionParser.add_option" title="optparse.OptionParser.add_option"><code class="xref py py-meth docutils literal notranslate"><span class="pre">optparse.OptionParser.add_option()</span></code></a> calls with

  2424. <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ArgumentParser.add_argument()</span></code></a> calls.</p></li>

  2425. <li><p>Replace <code class="docutils literal notranslate"><span class="pre">(options,</span> <span class="pre">args)</span> <span class="pre">=</span> <span class="pre">parser.parse_args()</span></code> with <code class="docutils literal notranslate"><span class="pre">args</span> <span class="pre">=</span>

  2426. <span class="pre">parser.parse_args()</span></code> and add additional <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ArgumentParser.add_argument()</span></code></a>

  2427. calls for the positional arguments. Keep in mind that what was previously

  2428. called <code class="docutils literal notranslate"><span class="pre">options</span></code>, now in the <a class="reference internal" href="#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> context is called <code class="docutils literal notranslate"><span class="pre">args</span></code>.</p></li>

  2429. <li><p>Replace <a class="reference internal" href="optparse.html#optparse.OptionParser.disable_interspersed_args" title="optparse.OptionParser.disable_interspersed_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">optparse.OptionParser.disable_interspersed_args()</span></code></a>

  2430. by using <a class="reference internal" href="#argparse.ArgumentParser.parse_intermixed_args" title="argparse.ArgumentParser.parse_intermixed_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_intermixed_args()</span></code></a> instead of

  2431. <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a>.</p></li>

  2432. <li><p>Replace callback actions and the <code class="docutils literal notranslate"><span class="pre">callback_*</span></code> keyword arguments with

  2433. <code class="docutils literal notranslate"><span class="pre">type</span></code> or <code class="docutils literal notranslate"><span class="pre">action</span></code> arguments.</p></li>

  2434. <li><p>Replace string names for <code class="docutils literal notranslate"><span class="pre">type</span></code> keyword arguments with the corresponding

  2435. type objects (e.g. int, float, complex, etc).</p></li>

  2436. <li><p>Replace <a class="reference internal" href="optparse.html#optparse.Values" title="optparse.Values"><code class="xref py py-class docutils literal notranslate"><span class="pre">optparse.Values</span></code></a> with <a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate"><span class="pre">Namespace</span></code></a> and

  2437. <a class="reference internal" href="optparse.html#optparse.OptionError" title="optparse.OptionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">optparse.OptionError</span></code></a> and <a class="reference internal" href="optparse.html#optparse.OptionValueError" title="optparse.OptionValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">optparse.OptionValueError</span></code></a> with

  2438. <a class="reference internal" href="#argparse.ArgumentError" title="argparse.ArgumentError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ArgumentError</span></code></a>.</p></li>

  2439. <li><p>Replace strings with implicit arguments such as <code class="docutils literal notranslate"><span class="pre">%default</span></code> or <code class="docutils literal notranslate"><span class="pre">%prog</span></code> with

  2440. the standard Python syntax to use dictionaries to format strings, that is,

  2441. <code class="docutils literal notranslate"><span class="pre">%(default)s</span></code> and <code class="docutils literal notranslate"><span class="pre">%(prog)s</span></code>.</p></li>

  2442. <li><p>Replace the OptionParser constructor <code class="docutils literal notranslate"><span class="pre">version</span></code> argument with a call to

  2443. <code class="docutils literal notranslate"><span class="pre">parser.add_argument('--version',</span> <span class="pre">action='version',</span> <span class="pre">version='&lt;the</span> <span class="pre">version&gt;')</span></code>.</p></li>

  2444. </ul>

  2445. </section>

  2446. <section id="exceptions">

  2447. <h2>Exceptions<a class="headerlink" href="#exceptions" title="Link to this heading">¶</a></h2>

  2448. <dl class="py exception">

  2449. <dt class="sig sig-object py" id="argparse.ArgumentError">

  2450. <em class="property"><span class="pre">exception</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">argparse.</span></span><span class="sig-name descname"><span class="pre">ArgumentError</span></span><a class="headerlink" href="#argparse.ArgumentError" title="Link to this definition">¶</a></dt>

  2451. <dd><p>An error from creating or using an argument (optional or positional).</p>

  2452. <p>The string value of this exception is the message, augmented with

  2453. information about the argument that caused it.</p>

  2454. </dd></dl>

  2455. 

  2456. <dl class="py exception">

  2457. <dt class="sig sig-object py" id="argparse.ArgumentTypeError">

  2458. <em class="property"><span class="pre">exception</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">argparse.</span></span><span class="sig-name descname"><span class="pre">ArgumentTypeError</span></span><a class="headerlink" href="#argparse.ArgumentTypeError" title="Link to this definition">¶</a></dt>

  2459. <dd><p>Raised when something goes wrong converting a command line string to a type.</p>

  2460. </dd></dl>

  2461. 

  2462. </section>

  2463. </section>

  2464. 

  2465. 

  2466.             <div class="clearer"></div>

  2467.           </div>

  2468.         </div>

  2469.       </div>

  2470.       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">

  2471.         <div class="sphinxsidebarwrapper">

  2472.   <div>

  2473.     <h3><a href="../contents.html">Table of Contents</a></h3>

  2474.     <ul>

  2475. <li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> — Parser for command-line options, arguments and sub-commands</a><ul>

  2476. <li><a class="reference internal" href="#core-functionality">Core Functionality</a></li>

  2477. <li><a class="reference internal" href="#quick-links-for-add-argument">Quick Links for add_argument()</a></li>

  2478. <li><a class="reference internal" href="#example">Example</a><ul>

  2479. <li><a class="reference internal" href="#creating-a-parser">Creating a parser</a></li>

  2480. <li><a class="reference internal" href="#adding-arguments">Adding arguments</a></li>

  2481. <li><a class="reference internal" href="#parsing-arguments">Parsing arguments</a></li>

  2482. </ul>

  2483. </li>

  2484. <li><a class="reference internal" href="#argumentparser-objects">ArgumentParser objects</a><ul>

  2485. <li><a class="reference internal" href="#prog">prog</a></li>

  2486. <li><a class="reference internal" href="#usage">usage</a></li>

  2487. <li><a class="reference internal" href="#description">description</a></li>

  2488. <li><a class="reference internal" href="#epilog">epilog</a></li>

  2489. <li><a class="reference internal" href="#parents">parents</a></li>

  2490. <li><a class="reference internal" href="#formatter-class">formatter_class</a></li>

  2491. <li><a class="reference internal" href="#prefix-chars">prefix_chars</a></li>

  2492. <li><a class="reference internal" href="#fromfile-prefix-chars">fromfile_prefix_chars</a></li>

  2493. <li><a class="reference internal" href="#argument-default">argument_default</a></li>

  2494. <li><a class="reference internal" href="#allow-abbrev">allow_abbrev</a></li>

  2495. <li><a class="reference internal" href="#conflict-handler">conflict_handler</a></li>

  2496. <li><a class="reference internal" href="#add-help">add_help</a></li>

  2497. <li><a class="reference internal" href="#exit-on-error">exit_on_error</a></li>

  2498. </ul>

  2499. </li>

  2500. <li><a class="reference internal" href="#the-add-argument-method">The add_argument() method</a><ul>

  2501. <li><a class="reference internal" href="#name-or-flags">name or flags</a></li>

  2502. <li><a class="reference internal" href="#action">action</a></li>

  2503. <li><a class="reference internal" href="#nargs">nargs</a></li>

  2504. <li><a class="reference internal" href="#const">const</a></li>

  2505. <li><a class="reference internal" href="#default">default</a></li>

  2506. <li><a class="reference internal" href="#type">type</a></li>

  2507. <li><a class="reference internal" href="#choices">choices</a></li>

  2508. <li><a class="reference internal" href="#required">required</a></li>

  2509. <li><a class="reference internal" href="#help">help</a></li>

  2510. <li><a class="reference internal" href="#metavar">metavar</a></li>

  2511. <li><a class="reference internal" href="#dest">dest</a></li>

  2512. <li><a class="reference internal" href="#action-classes">Action classes</a></li>

  2513. </ul>

  2514. </li>

  2515. <li><a class="reference internal" href="#the-parse-args-method">The parse_args() method</a><ul>

  2516. <li><a class="reference internal" href="#option-value-syntax">Option value syntax</a></li>

  2517. <li><a class="reference internal" href="#invalid-arguments">Invalid arguments</a></li>

  2518. <li><a class="reference internal" href="#arguments-containing">Arguments containing <code class="docutils literal notranslate"><span class="pre">-</span></code></a></li>

  2519. <li><a class="reference internal" href="#argument-abbreviations-prefix-matching">Argument abbreviations (prefix matching)</a></li>

  2520. <li><a class="reference internal" href="#beyond-sys-argv">Beyond <code class="docutils literal notranslate"><span class="pre">sys.argv</span></code></a></li>

  2521. <li><a class="reference internal" href="#the-namespace-object">The Namespace object</a></li>

  2522. </ul>

  2523. </li>

  2524. <li><a class="reference internal" href="#other-utilities">Other utilities</a><ul>

  2525. <li><a class="reference internal" href="#sub-commands">Sub-commands</a></li>

  2526. <li><a class="reference internal" href="#filetype-objects">FileType objects</a></li>

  2527. <li><a class="reference internal" href="#argument-groups">Argument groups</a></li>

  2528. <li><a class="reference internal" href="#mutual-exclusion">Mutual exclusion</a></li>

  2529. <li><a class="reference internal" href="#parser-defaults">Parser defaults</a></li>

  2530. <li><a class="reference internal" href="#printing-help">Printing help</a></li>

  2531. <li><a class="reference internal" href="#partial-parsing">Partial parsing</a></li>

  2532. <li><a class="reference internal" href="#customizing-file-parsing">Customizing file parsing</a></li>

  2533. <li><a class="reference internal" href="#exiting-methods">Exiting methods</a></li>

  2534. <li><a class="reference internal" href="#intermixed-parsing">Intermixed parsing</a></li>

  2535. </ul>

  2536. </li>

  2537. <li><a class="reference internal" href="#upgrading-optparse-code">Upgrading optparse code</a></li>

  2538. <li><a class="reference internal" href="#exceptions">Exceptions</a></li>

  2539. </ul>

  2540. </li>

  2541. </ul>

  2542. 

  2543.   </div>

  2544.   <div>

  2545.     <h4>Previous topic</h4>

  2546.     <p class="topless"><a href="time.html"

  2547.                           title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">time</span></code> — Time access and conversions</a></p>

  2548.   </div>

  2549.   <div>

  2550.     <h4>Next topic</h4>

  2551.     <p class="topless"><a href="getopt.html"

  2552.                           title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">getopt</span></code> — C-style parser for command line options</a></p>

  2553.   </div>

  2554.   <div role="note" aria-label="source link">

  2555.     <h3>This Page</h3>

  2556.     <ul class="this-page-menu">

  2557.       <li><a href="../bugs.html">Report a Bug</a></li>

  2558.       <li>

  2559.         <a href="https://github.com/python/cpython/blob/main/Doc/library/argparse.rst"

  2560.             rel="nofollow">Show Source

  2561.         </a>

  2562.       </li>

  2563.     </ul>

  2564.   </div>

  2565.         </div>

  2566. <div id="sidebarbutton" title="Collapse sidebar">

  2567. <span>«</span>

  2568. </div>

  2569. 

  2570.       </div>

  2571.       <div class="clearer"></div>

  2572.     </div>  

  2573.     <div class="related" role="navigation" aria-label="related navigation">

  2574.       <h3>Navigation</h3>

  2575.       <ul>

  2576.         <li class="right" style="margin-right: 10px">

  2577.           <a href="../genindex.html" title="General Index"

  2578.              >index</a></li>

  2579.         <li class="right" >

  2580.           <a href="../py-modindex.html" title="Python Module Index"

  2581.              >modules</a> |</li>

  2582.         <li class="right" >

  2583.           <a href="getopt.html" title="getopt — C-style parser for command line options"

  2584.              >next</a> |</li>

  2585.         <li class="right" >

  2586.           <a href="time.html" title="time — Time access and conversions"

  2587.              >previous</a> |</li>

  2588. 

  2589.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  2590.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  2591.           <li class="switchers">

  2592.             <div class="language_switcher_placeholder"></div>

  2593.             <div class="version_switcher_placeholder"></div>

  2594.           </li>

  2595.           <li>

  2596.               

  2597.           </li>

  2598.     <li id="cpython-language-and-version">

  2599.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  2600.     </li>

  2601. 

  2602.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  2603.           <li class="nav-item nav-item-2"><a href="allos.html" >Generic Operating System Services</a> &#187;</li>

  2604.         <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> — Parser for command-line options, arguments and sub-commands</a></li>

  2605.                 <li class="right">

  2606.                     

  2607. 

  2608.     <div class="inline-search" role="search">

  2609.         <form class="inline-search" action="../search.html" method="get">

  2610.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  2611.           <input type="submit" value="Go" />

  2612.         </form>

  2613.     </div>

  2614.                      |

  2615.                 </li>

  2616.             <li class="right">

  2617. <label class="theme-selector-label">

  2618.     Theme

  2619.     <select class="theme-selector" oninput="activateTheme(this.value)">

  2620.         <option value="auto" selected>Auto</option>

  2621.         <option value="light">Light</option>

  2622.         <option value="dark">Dark</option>

  2623.     </select>

  2624. </label> |</li>

  2625.             

  2626.       </ul>

  2627.     </div>  

  2628.     <div class="footer">

  2629.     &copy; 

  2630.       <a href="../copyright.html">

  2631.     

  2632.     Copyright

  2633.     

  2634.       </a>

  2635.      2001-2024, Python Software Foundation.

  2636.     <br />

  2637.     This page is licensed under the Python Software Foundation License Version 2.

  2638.     <br />

  2639.     Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.

  2640.     <br />

  2641.     

  2642.       See <a href="/license.html">History and License</a> for more information.<br />

  2643.     

  2644.     

  2645.     <br />

  2646. 

  2647.     The Python Software Foundation is a non-profit corporation.

  2648. <a href="https://www.python.org/psf/donations/">Please donate.</a>

  2649. <br />

  2650.     <br />

  2651.       Last updated on Apr 09, 2024 (13:47 UTC).

  2652.     

  2653.       <a href="/bugs.html">Found a bug</a>?

  2654.     

  2655.     <br />

  2656. 

  2657.     Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.

  2658.     </div>

  2659. 

  2660.   </body>

  2661. </html>
上海开阖软件有限公司 沪ICP备12045867号-1