Spaces:
Sleeping
Sleeping
| <html lang="en" data-content_root="../"> | |
| <head> | |
| <meta charset="utf-8" /> | |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" /> | |
| <meta property="og:title" content="argparse — Parser for command-line options, arguments and subcommands" /> | |
| <meta property="og:type" content="website" /> | |
| <meta property="og:url" content="https://docs.python.org/3/library/argparse.html" /> | |
| <meta property="og:site_name" content="Python documentation" /> | |
| <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..." /> | |
| <meta property="og:image:width" content="1146" /> | |
| <meta property="og:image:height" content="600" /> | |
| <meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_argparse_3f064f33.png" /> | |
| <meta property="og:image:alt" 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..." /> | |
| <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..." /> | |
| <meta name="twitter:card" content="summary_large_image" /> | |
| <meta name="theme-color" content="#3776ab"> | |
| <title>argparse — Parser for command-line options, arguments and subcommands — Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0"> | |
| <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" /> | |
| <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" /> | |
| <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" /> | |
| <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" /> | |
| <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" /> | |
| <script src="../_static/documentation_options.js?v=6b7c9ff5"></script> | |
| <script src="../_static/doctools.js?v=9bcbadda"></script> | |
| <script src="../_static/sphinx_highlight.js?v=dc90522c"></script> | |
| <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script> | |
| <script src="../_static/sidebar.js"></script> | |
| <link rel="search" type="application/opensearchdescription+xml" | |
| title="Search within Python 3.15.0a6 documentation" | |
| href="../_static/opensearch.xml"/> | |
| <link rel="author" title="About these documents" href="../about.html" /> | |
| <link rel="index" title="Index" href="../genindex.html" /> | |
| <link rel="search" title="Search" href="../search.html" /> | |
| <link rel="copyright" title="Copyright" href="../copyright.html" /> | |
| <link rel="next" title="Argparse Tutorial" href="../howto/argparse.html" /> | |
| <link rel="prev" title="Command-line interface libraries" href="cmdlinelibs.html" /> | |
| <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script> | |
| <link rel="canonical" href="https://docs.python.org/3/library/argparse.html"> | |
| <style> | |
| @media only screen { | |
| table.full-width-table { | |
| width: 100%; | |
| } | |
| } | |
| </style> | |
| <link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css"> | |
| <link rel="shortcut icon" type="image/png" href="../_static/py.svg"> | |
| <script type="text/javascript" src="../_static/copybutton.js"></script> | |
| <script type="text/javascript" src="../_static/menu.js"></script> | |
| <script type="text/javascript" src="../_static/search-focus.js"></script> | |
| <script type="text/javascript" src="../_static/themetoggle.js"></script> | |
| <script type="text/javascript" src="../_static/rtd_switcher.js"></script> | |
| <meta name="readthedocs-addons-api-version" content="1"> | |
| </head> | |
| <body> | |
| <div class="mobile-nav"> | |
| <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation" | |
| aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu"> | |
| <nav class="nav-content" role="navigation"> | |
| <label for="menuToggler" class="toggler__label"> | |
| <span></span> | |
| </label> | |
| <span class="nav-items-wrapper"> | |
| <a href="https://www.python.org/" class="nav-logo"> | |
| <img src="../_static/py.svg" alt="Python logo"> | |
| </a> | |
| <span class="version_switcher_placeholder"></span> | |
| <form role="search" class="search" action="../search.html" method="get"> | |
| <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon"> | |
| <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> | |
| </svg> | |
| <input placeholder="Quick search" aria-label="Quick search" type="search" name="q"> | |
| <input type="submit" value="Go"> | |
| </form> | |
| </span> | |
| </nav> | |
| <div class="menu-wrapper"> | |
| <nav class="menu" role="navigation" aria-label="main navigation"> | |
| <div class="language_switcher_placeholder"></div> | |
| <label class="theme-selector-label"> | |
| Theme | |
| <select class="theme-selector" oninput="activateTheme(this.value)"> | |
| <option value="auto" selected>Auto</option> | |
| <option value="light">Light</option> | |
| <option value="dark">Dark</option> | |
| </select> | |
| </label> | |
| <div> | |
| <h3><a href="../contents.html">Table of Contents</a></h3> | |
| <ul> | |
| <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 subcommands</a><ul> | |
| <li><a class="reference internal" href="#argumentparser-objects">ArgumentParser objects</a><ul> | |
| <li><a class="reference internal" href="#prog">prog</a></li> | |
| <li><a class="reference internal" href="#usage">usage</a></li> | |
| <li><a class="reference internal" href="#description">description</a></li> | |
| <li><a class="reference internal" href="#epilog">epilog</a></li> | |
| <li><a class="reference internal" href="#parents">parents</a></li> | |
| <li><a class="reference internal" href="#formatter-class">formatter_class</a></li> | |
| <li><a class="reference internal" href="#prefix-chars">prefix_chars</a></li> | |
| <li><a class="reference internal" href="#fromfile-prefix-chars">fromfile_prefix_chars</a></li> | |
| <li><a class="reference internal" href="#argument-default">argument_default</a></li> | |
| <li><a class="reference internal" href="#allow-abbrev">allow_abbrev</a></li> | |
| <li><a class="reference internal" href="#conflict-handler">conflict_handler</a></li> | |
| <li><a class="reference internal" href="#add-help">add_help</a></li> | |
| <li><a class="reference internal" href="#exit-on-error">exit_on_error</a></li> | |
| <li><a class="reference internal" href="#suggest-on-error">suggest_on_error</a></li> | |
| <li><a class="reference internal" href="#color">color</a></li> | |
| </ul> | |
| </li> | |
| <li><a class="reference internal" href="#the-add-argument-method">The add_argument() method</a><ul> | |
| <li><a class="reference internal" href="#name-or-flags">name or flags</a></li> | |
| <li><a class="reference internal" href="#action">action</a></li> | |
| <li><a class="reference internal" href="#nargs">nargs</a></li> | |
| <li><a class="reference internal" href="#const">const</a></li> | |
| <li><a class="reference internal" href="#default">default</a></li> | |
| <li><a class="reference internal" href="#type">type</a></li> | |
| <li><a class="reference internal" href="#choices">choices</a></li> | |
| <li><a class="reference internal" href="#required">required</a></li> | |
| <li><a class="reference internal" href="#help">help</a></li> | |
| <li><a class="reference internal" href="#metavar">metavar</a></li> | |
| <li><a class="reference internal" href="#dest">dest</a></li> | |
| <li><a class="reference internal" href="#deprecated">deprecated</a></li> | |
| <li><a class="reference internal" href="#action-classes">Action classes</a></li> | |
| </ul> | |
| </li> | |
| <li><a class="reference internal" href="#the-parse-args-method">The parse_args() method</a><ul> | |
| <li><a class="reference internal" href="#option-value-syntax">Option value syntax</a></li> | |
| <li><a class="reference internal" href="#invalid-arguments">Invalid arguments</a></li> | |
| <li><a class="reference internal" href="#arguments-containing">Arguments containing <code class="docutils literal notranslate"><span class="pre">-</span></code></a></li> | |
| <li><a class="reference internal" href="#argument-abbreviations-prefix-matching">Argument abbreviations (prefix matching)</a></li> | |
| <li><a class="reference internal" href="#beyond-sys-argv">Beyond <code class="docutils literal notranslate"><span class="pre">sys.argv</span></code></a></li> | |
| <li><a class="reference internal" href="#the-namespace-object">The Namespace object</a></li> | |
| </ul> | |
| </li> | |
| <li><a class="reference internal" href="#other-utilities">Other utilities</a><ul> | |
| <li><a class="reference internal" href="#subcommands">Subcommands</a></li> | |
| <li><a class="reference internal" href="#filetype-objects">FileType objects</a></li> | |
| <li><a class="reference internal" href="#argument-groups">Argument groups</a></li> | |
| <li><a class="reference internal" href="#mutual-exclusion">Mutual exclusion</a></li> | |
| <li><a class="reference internal" href="#parser-defaults">Parser defaults</a></li> | |
| <li><a class="reference internal" href="#printing-help">Printing help</a></li> | |
| <li><a class="reference internal" href="#partial-parsing">Partial parsing</a></li> | |
| <li><a class="reference internal" href="#customizing-file-parsing">Customizing file parsing</a></li> | |
| <li><a class="reference internal" href="#exiting-methods">Exiting methods</a></li> | |
| <li><a class="reference internal" href="#intermixed-parsing">Intermixed parsing</a></li> | |
| <li><a class="reference internal" href="#registering-custom-types-or-actions">Registering custom types or actions</a></li> | |
| </ul> | |
| </li> | |
| <li><a class="reference internal" href="#exceptions">Exceptions</a></li> | |
| </ul> | |
| </li> | |
| </ul> | |
| </div> | |
| <div> | |
| <h4>Previous topic</h4> | |
| <p class="topless"><a href="cmdlinelibs.html" | |
| title="previous chapter">Command-line interface libraries</a></p> | |
| </div> | |
| <div> | |
| <h4>Next topic</h4> | |
| <p class="topless"><a href="../howto/argparse.html" | |
| title="next chapter">Argparse Tutorial</a></p> | |
| </div> | |
| <script> | |
| document.addEventListener('DOMContentLoaded', () => { | |
| const title = document.querySelector('meta[property="og:title"]').content; | |
| const elements = document.querySelectorAll('.improvepage'); | |
| const pageurl = window.location.href.split('?')[0]; | |
| elements.forEach(element => { | |
| const url = new URL(element.href.split('?')[0].replace("-nojs", "")); | |
| url.searchParams.set('pagetitle', title); | |
| url.searchParams.set('pageurl', pageurl); | |
| url.searchParams.set('pagesource', "library/argparse.rst"); | |
| element.href = url.toString(); | |
| }); | |
| }); | |
| </script> | |
| <div role="note" aria-label="source link"> | |
| <h3>This page</h3> | |
| <ul class="this-page-menu"> | |
| <li><a href="../bugs.html">Report a bug</a></li> | |
| <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li> | |
| <li> | |
| <a href="https://github.com/python/cpython/blob/main/Doc/library/argparse.rst?plain=1" | |
| rel="nofollow">Show source | |
| </a> | |
| </li> | |
| </ul> | |
| </div> | |
| </nav> | |
| </div> | |
| </div> | |
| <div class="related" role="navigation" aria-label="Related"> | |
| <h3>Navigation</h3> | |
| <ul> | |
| <li class="right" style="margin-right: 10px"> | |
| <a href="../genindex.html" title="General Index" | |
| accesskey="I">index</a></li> | |
| <li class="right" > | |
| <a href="../py-modindex.html" title="Python Module Index" | |
| >modules</a> |</li> | |
| <li class="right" > | |
| <a href="../howto/argparse.html" title="Argparse Tutorial" | |
| accesskey="N">next</a> |</li> | |
| <li class="right" > | |
| <a href="cmdlinelibs.html" title="Command-line interface libraries" | |
| accesskey="P">previous</a> |</li> | |
| <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li> | |
| <li><a href="https://www.python.org/">Python</a> »</li> | |
| <li class="switchers"> | |
| <div class="language_switcher_placeholder"></div> | |
| <div class="version_switcher_placeholder"></div> | |
| </li> | |
| <li> | |
| </li> | |
| <li id="cpython-language-and-version"> | |
| <a href="../index.html">3.15.0a6 Documentation</a> » | |
| </li> | |
| <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li> | |
| <li class="nav-item nav-item-2"><a href="cmdlinelibs.html" accesskey="U">Command-line interface libraries</a> »</li> | |
| <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 subcommands</a></li> | |
| <li class="right"> | |
| <div class="inline-search" role="search"> | |
| <form class="inline-search" action="../search.html" method="get"> | |
| <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box"> | |
| <input type="submit" value="Go"> | |
| </form> | |
| </div> | |
| | | |
| </li> | |
| <li class="right"> | |
| <label class="theme-selector-label"> | |
| Theme | |
| <select class="theme-selector" oninput="activateTheme(this.value)"> | |
| <option value="auto" selected>Auto</option> | |
| <option value="light">Light</option> | |
| <option value="dark">Dark</option> | |
| </select> | |
| </label> |</li> | |
| </ul> | |
| </div> | |
| <div class="document"> | |
| <div class="documentwrapper"> | |
| <div class="bodywrapper"> | |
| <div class="body" role="main"> | |
| <section id="module-argparse"> | |
| <span id="argparse-parser-for-command-line-options-arguments-and-subcommands"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> — Parser for command-line options, arguments and subcommands<a class="headerlink" href="#module-argparse" title="Link to this heading">¶</a></h1> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.2.</span></p> | |
| </div> | |
| <p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/argparse.py">Lib/argparse.py</a></p> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>While <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> is the default recommended standard library module | |
| for implementing basic command line applications, authors with more | |
| exacting requirements for exactly how their command line applications | |
| behave may find it doesn’t provide the necessary level of control. | |
| Refer to <a class="reference internal" href="optparse.html#choosing-an-argument-parser"><span class="std std-ref">Choosing an argument parsing library</span></a> for alternatives to | |
| consider when <code class="docutils literal notranslate"><span class="pre">argparse</span></code> doesn’t support behaviors that the application | |
| requires (such as entirely disabling support for interspersed options and | |
| positional arguments, or accepting option parameter values that start | |
| with <code class="docutils literal notranslate"><span class="pre">-</span></code> even when they correspond to another defined option).</p> | |
| </div> | |
| <hr class="docutils" /> | |
| <aside class="sidebar"> | |
| <p class="sidebar-title">Tutorial</p> | |
| <p>This page contains the API reference information. For a more gentle | |
| introduction to Python command-line parsing, have a look at the | |
| <a class="reference internal" href="../howto/argparse.html#argparse-tutorial"><span class="std std-ref">argparse tutorial</span></a>.</p> | |
| </aside> | |
| <p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> module makes it easy to write user-friendly command-line | |
| interfaces. The program defines what arguments it requires, and <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> | |
| 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 <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> | |
| module also automatically generates help and usage messages. The module | |
| will also issue errors when users give the program invalid arguments.</p> | |
| <p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> module’s support for command-line interfaces is built | |
| 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 | |
| argument specifications and has options that apply to the parser as whole:</p> | |
| <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> | |
| <span class="n">prog</span><span class="o">=</span><span class="s1">'ProgramName'</span><span class="p">,</span> | |
| <span class="n">description</span><span class="o">=</span><span class="s1">'What the program does'</span><span class="p">,</span> | |
| <span class="n">epilog</span><span class="o">=</span><span class="s1">'Text at the bottom of help'</span><span class="p">)</span> | |
| </pre></div> | |
| </div> | |
| <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 | |
| specifications to the parser. It supports positional arguments, options that | |
| accept values, and on/off flags:</p> | |
| <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">'filename'</span><span class="p">)</span> <span class="c1"># positional argument</span> | |
| <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-c'</span><span class="p">,</span> <span class="s1">'--count'</span><span class="p">)</span> <span class="c1"># option that takes a value</span> | |
| <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-v'</span><span class="p">,</span> <span class="s1">'--verbose'</span><span class="p">,</span> | |
| <span class="n">action</span><span class="o">=</span><span class="s1">'store_true'</span><span class="p">)</span> <span class="c1"># on/off flag</span> | |
| </pre></div> | |
| </div> | |
| <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 | |
| 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> | |
| <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> | |
| <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> | |
| </pre></div> | |
| </div> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>If you’re looking for a guide about how to upgrade <a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> code | |
| to <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code>, see <a class="reference internal" href="../howto/argparse-optparse.html#upgrading-optparse-code"><span class="std std-ref">Upgrading Optparse Code</span></a>.</p> | |
| </div> | |
| <section id="argumentparser-objects"> | |
| <h2>ArgumentParser objects<a class="headerlink" href="#argumentparser-objects" title="Link to this heading">¶</a></h2> | |
| <dl class="py class"> | |
| <dt class="sig sig-object py" id="argparse.ArgumentParser"> | |
| <em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">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>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">suggest_on_error</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">color</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> | |
| <dd><p>Create a new <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> object. All parameters should be passed | |
| as keyword arguments. Each parameter has its own more detailed description | |
| below, but in short they are:</p> | |
| <ul class="simple"> | |
| <li><p><a class="reference internal" href="#prog">prog</a> - The name of the program (default: generated from the <code class="docutils literal notranslate"><span class="pre">__main__</span></code> | |
| module attributes and <code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code>)</p></li> | |
| <li><p><a class="reference internal" href="#usage">usage</a> - The string describing the program usage (default: generated from | |
| arguments added to parser)</p></li> | |
| <li><p><a class="reference internal" href="#description">description</a> - Text to display before the argument help | |
| (by default, no text)</p></li> | |
| <li><p><a class="reference internal" href="#epilog">epilog</a> - Text to display after the argument help (by default, no text)</p></li> | |
| <li><p><a class="reference internal" href="#parents">parents</a> - A list of <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> objects whose arguments should | |
| also be included</p></li> | |
| <li><p><a class="reference internal" href="#formatter-class">formatter_class</a> - A class for customizing the help output</p></li> | |
| <li><p><a class="reference internal" href="#prefix-chars">prefix_chars</a> - The set of characters that prefix optional arguments | |
| (default: ‘-‘)</p></li> | |
| <li><p><a class="reference internal" href="#fromfile-prefix-chars">fromfile_prefix_chars</a> - The set of characters that prefix files from | |
| which additional arguments should be read (default: <code class="docutils literal notranslate"><span class="pre">None</span></code>)</p></li> | |
| <li><p><a class="reference internal" href="#argument-default">argument_default</a> - The global default value for arguments | |
| (default: <code class="docutils literal notranslate"><span class="pre">None</span></code>)</p></li> | |
| <li><p><a class="reference internal" href="#conflict-handler">conflict_handler</a> - The strategy for resolving conflicting optionals | |
| (usually unnecessary)</p></li> | |
| <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> | |
| <li><p><a class="reference internal" href="#allow-abbrev">allow_abbrev</a> - Allows long options to be abbreviated if the | |
| abbreviation is unambiguous (default: <code class="docutils literal notranslate"><span class="pre">True</span></code>)</p></li> | |
| <li><p><a class="reference internal" href="#exit-on-error">exit_on_error</a> - Determines whether or not <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> exits with | |
| error info when an error occurs. (default: <code class="docutils literal notranslate"><span class="pre">True</span></code>)</p></li> | |
| <li><p><a class="reference internal" href="#suggest-on-error">suggest_on_error</a> - Enables suggestions for mistyped argument choices | |
| and subparser names (default: <code class="docutils literal notranslate"><span class="pre">True</span></code>)</p></li> | |
| <li><p><a class="reference internal" href="#color">color</a> - Allow color output (default: <code class="docutils literal notranslate"><span class="pre">True</span></code>)</p></li> | |
| </ul> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.5: </span><em>allow_abbrev</em> parameter was added.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.8: </span>In previous versions, <em>allow_abbrev</em> also disabled grouping of short | |
| 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> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.9: </span><em>exit_on_error</em> parameter was added.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.14: </span><em>suggest_on_error</em> and <em>color</em> parameters were added.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.15: </span><em>suggest_on_error</em> default changed to <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p> | |
| </div> | |
| </dd></dl> | |
| <p>The following sections describe how each of these are used.</p> | |
| <section id="prog"> | |
| <span id="id1"></span><h3>prog<a class="headerlink" href="#prog" title="Link to this heading">¶</a></h3> | |
| <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 name of the program | |
| to display in help messages depending on the way the Python interpreter was run:</p> | |
| <ul class="simple"> | |
| <li><p>The <a class="reference internal" href="os.path.html#os.path.basename" title="os.path.basename"><code class="xref py py-func docutils literal notranslate"><span class="pre">base</span> <span class="pre">name</span></code></a> of <code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code> if a file was | |
| passed as argument.</p></li> | |
| <li><p>The Python interpreter name followed by <code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code> if a directory or | |
| a zipfile was passed as argument.</p></li> | |
| <li><p>The Python interpreter name followed by <code class="docutils literal notranslate"><span class="pre">-m</span></code> followed by the | |
| module or package name if the <a class="reference internal" href="../using/cmdline.html#cmdoption-m"><code class="xref std std-option docutils literal notranslate"><span class="pre">-m</span></code></a> option was used.</p></li> | |
| </ul> | |
| <p>This default is almost always desirable because it will make the help messages | |
| match the string that was used to invoke the program on the command line. | |
| However, to change this default behavior, another value can be supplied using | |
| the <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> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'myprogram'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span> | |
| <span class="go">usage: myprogram [-h]</span> | |
| <span class="go">options:</span> | |
| <span class="go"> -h, --help show this help message and exit</span> | |
| </pre></div> | |
| </div> | |
| <p>Note that the program name, whether determined from <code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code>, | |
| from the <code class="docutils literal notranslate"><span class="pre">__main__</span></code> module attributes or from the | |
| <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 | |
| specifier.</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'myprogram'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'foo of the </span><span class="si">%(prog)s</span><span class="s1"> program'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span> | |
| <span class="go">usage: myprogram [-h] [--foo FOO]</span> | |
| <span class="go">options:</span> | |
| <span class="go"> -h, --help show this help message and exit</span> | |
| <span class="go"> --foo FOO foo of the myprogram program</span> | |
| </pre></div> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.14: </span>The default <code class="docutils literal notranslate"><span class="pre">prog</span></code> value now reflects how <code class="docutils literal notranslate"><span class="pre">__main__</span></code> was actually executed, | |
| rather than always being <code class="docutils literal notranslate"><span class="pre">os.path.basename(sys.argv[0])</span></code>.</p> | |
| </div> | |
| </section> | |
| <section id="usage"> | |
| <h3>usage<a class="headerlink" href="#usage" title="Link to this heading">¶</a></h3> | |
| <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 | |
| arguments it contains. The default message can be overridden with the | |
| <code class="docutils literal notranslate"><span class="pre">usage=</span></code> keyword argument:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'PROG'</span><span class="p">,</span> <span class="n">usage</span><span class="o">=</span><span class="s1">'</span><span class="si">%(prog)s</span><span class="s1"> [options]'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'?'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'foo help'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'+'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'bar help'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span> | |
| <span class="go">usage: PROG [options]</span> | |
| <span class="go">positional arguments:</span> | |
| <span class="go"> bar bar help</span> | |
| <span class="go">options:</span> | |
| <span class="go"> -h, --help show this help message and exit</span> | |
| <span class="go"> --foo [FOO] foo help</span> | |
| </pre></div> | |
| </div> | |
| <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 | |
| your usage messages.</p> | |
| <p>When a custom usage message is specified for the main parser, you may also want to | |
| consider passing the <code class="docutils literal notranslate"><span class="pre">prog</span></code> argument to <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> | |
| or the <code class="docutils literal notranslate"><span class="pre">prog</span></code> and the <code class="docutils literal notranslate"><span class="pre">usage</span></code> arguments to | |
| <a class="reference internal" href="#argparse._SubParsersAction.add_parser" title="argparse._SubParsersAction.add_parser"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_parser()</span></code></a>, to ensure consistent command prefixes and | |
| usage information across subparsers.</p> | |
| </section> | |
| <section id="description"> | |
| <span id="id2"></span><h3>description<a class="headerlink" href="#description" title="Link to this heading">¶</a></h3> | |
| <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 | |
| <code class="docutils literal notranslate"><span class="pre">description=</span></code> keyword argument. This argument gives a brief description of | |
| what the program does and how it works. In help messages, the description is | |
| displayed between the command-line usage string and the help messages for the | |
| various arguments.</p> | |
| <p>By default, the description will be line-wrapped so that it fits within the | |
| given space. To change this behavior, see the <a class="reference internal" href="#formatter-class">formatter_class</a> argument.</p> | |
| </section> | |
| <section id="epilog"> | |
| <h3>epilog<a class="headerlink" href="#epilog" title="Link to this heading">¶</a></h3> | |
| <p>Some programs like to display additional description of the program after the | |
| description of the arguments. Such text can be specified using the <code class="docutils literal notranslate"><span class="pre">epilog=</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> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">... </span> <span class="n">description</span><span class="o">=</span><span class="s1">'A foo that bars'</span><span class="p">,</span> | |
| <span class="gp">... </span> <span class="n">epilog</span><span class="o">=</span><span class="s2">"And that's how you'd foo a bar"</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span> | |
| <span class="go">usage: argparse.py [-h]</span> | |
| <span class="go">A foo that bars</span> | |
| <span class="go">options:</span> | |
| <span class="go"> -h, --help show this help message and exit</span> | |
| <span class="go">And that's how you'd foo a bar</span> | |
| </pre></div> | |
| </div> | |
| <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 | |
| line-wrapped, but this behavior can be adjusted with the <a class="reference internal" href="#formatter-class">formatter_class</a> | |
| 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> | |
| </section> | |
| <section id="parents"> | |
| <h3>parents<a class="headerlink" href="#parents" title="Link to this heading">¶</a></h3> | |
| <p>Sometimes, several parsers share a common set of arguments. Rather than | |
| repeating the definitions of these arguments, a single parser with all the | |
| 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> | |
| can be used. The <code class="docutils literal notranslate"><span class="pre">parents=</span></code> argument takes a list of <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> | |
| objects, collects all the positional and optional actions from them, and adds | |
| these actions to the <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> object being constructed:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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> | |
| <span class="gp">>>> </span><span class="n">parent_parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--parent'</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="gp">>>> </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> | |
| <span class="gp">>>> </span><span class="n">foo_parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">foo_parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'--parent'</span><span class="p">,</span> <span class="s1">'2'</span><span class="p">,</span> <span class="s1">'XXX'</span><span class="p">])</span> | |
| <span class="go">Namespace(foo='XXX', parent=2)</span> | |
| <span class="gp">>>> </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> | |
| <span class="gp">>>> </span><span class="n">bar_parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--bar'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">bar_parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'--bar'</span><span class="p">,</span> <span class="s1">'YYY'</span><span class="p">])</span> | |
| <span class="go">Namespace(bar='YYY', parent=None)</span> | |
| </pre></div> | |
| </div> | |
| <p>Note that most parent parsers will specify <code class="docutils literal notranslate"><span class="pre">add_help=False</span></code>. Otherwise, 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 see two <code class="docutils literal notranslate"><span class="pre">-h/--help</span></code> options (one in the parent | |
| and one in the child) and raise an error.</p> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>You must fully initialize the parsers before passing them via <code class="docutils literal notranslate"><span class="pre">parents=</span></code>. | |
| If you change the parent parsers after the child parser, those changes will | |
| not be reflected in the child.</p> | |
| </div> | |
| </section> | |
| <section id="formatter-class"> | |
| <span id="id3"></span><h3>formatter_class<a class="headerlink" href="#formatter-class" title="Link to this heading">¶</a></h3> | |
| <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 | |
| specifying an alternate formatting class. Currently, there are four such | |
| classes:</p> | |
| <dl class="py class"> | |
| <dt class="sig sig-object py" id="argparse.RawDescriptionHelpFormatter"> | |
| <em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">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> | |
| <dt class="sig sig-object py" id="argparse.RawTextHelpFormatter"> | |
| <em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">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> | |
| <dt class="sig sig-object py" id="argparse.ArgumentDefaultsHelpFormatter"> | |
| <em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">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> | |
| <dt class="sig sig-object py" id="argparse.MetavarTypeHelpFormatter"> | |
| <em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">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> | |
| <dd></dd></dl> | |
| <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 | |
| more control over how textual descriptions are displayed. | |
| 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 | |
| <a class="reference internal" href="#epilog">epilog</a> texts in command-line help messages:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">... </span> <span class="n">prog</span><span class="o">=</span><span class="s1">'PROG'</span><span class="p">,</span> | |
| <span class="gp">... </span> <span class="n">description</span><span class="o">=</span><span class="s1">'''this description</span> | |
| <span class="gp">... </span><span class="s1"> was indented weird</span> | |
| <span class="gp">... </span><span class="s1"> but that is okay'''</span><span class="p">,</span> | |
| <span class="gp">... </span> <span class="n">epilog</span><span class="o">=</span><span class="s1">'''</span> | |
| <span class="gp">... </span><span class="s1"> likewise for this epilog whose whitespace will</span> | |
| <span class="gp">... </span><span class="s1"> be cleaned up and whose words will be wrapped</span> | |
| <span class="gp">... </span><span class="s1"> across a couple lines'''</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span> | |
| <span class="go">usage: PROG [-h]</span> | |
| <span class="go">this description was indented weird but that is okay</span> | |
| <span class="go">options:</span> | |
| <span class="go"> -h, --help show this help message and exit</span> | |
| <span class="go">likewise for this epilog whose whitespace will be cleaned up and whose words</span> | |
| <span class="go">will be wrapped across a couple lines</span> | |
| </pre></div> | |
| </div> | |
| <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> | |
| indicates that <a class="reference internal" href="#description">description</a> and <a class="reference internal" href="#epilog">epilog</a> are already correctly formatted and | |
| should not be line-wrapped:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">... </span> <span class="n">prog</span><span class="o">=</span><span class="s1">'PROG'</span><span class="p">,</span> | |
| <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> | |
| <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">'''</span><span class="se">\</span> | |
| <span class="gp">... </span><span class="s1"> Please do not mess up this text!</span> | |
| <span class="gp">... </span><span class="s1"> --------------------------------</span> | |
| <span class="gp">... </span><span class="s1"> I have indented it</span> | |
| <span class="gp">... </span><span class="s1"> exactly the way</span> | |
| <span class="gp">... </span><span class="s1"> I want it</span> | |
| <span class="gp">... </span><span class="s1"> '''</span><span class="p">))</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span> | |
| <span class="go">usage: PROG [-h]</span> | |
| <span class="go">Please do not mess up this text!</span> | |
| <span class="go">--------------------------------</span> | |
| <span class="go"> I have indented it</span> | |
| <span class="go"> exactly the way</span> | |
| <span class="go"> I want it</span> | |
| <span class="go">options:</span> | |
| <span class="go"> -h, --help show this help message and exit</span> | |
| </pre></div> | |
| </div> | |
| <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, | |
| including argument descriptions. However, multiple newlines are replaced with | |
| one. If you wish to preserve multiple blank lines, add spaces between the | |
| newlines.</p> | |
| <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 | |
| default values to each of the argument help messages:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">... </span> <span class="n">prog</span><span class="o">=</span><span class="s1">'PROG'</span><span class="p">,</span> | |
| <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> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</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">'FOO!'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'*'</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">'BAR!'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span> | |
| <span class="go">usage: PROG [-h] [--foo FOO] [bar ...]</span> | |
| <span class="go">positional arguments:</span> | |
| <span class="go"> bar BAR! (default: [1, 2, 3])</span> | |
| <span class="go">options:</span> | |
| <span class="go"> -h, --help show this help message and exit</span> | |
| <span class="go"> --foo FOO FOO! (default: 42)</span> | |
| </pre></div> | |
| </div> | |
| <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 | |
| argument as the display name for its values (rather than using the <a class="reference internal" href="#dest">dest</a> | |
| as the regular formatter does):</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">... </span> <span class="n">prog</span><span class="o">=</span><span class="s1">'PROG'</span><span class="p">,</span> | |
| <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> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">float</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span> | |
| <span class="go">usage: PROG [-h] [--foo int] float</span> | |
| <span class="go">positional arguments:</span> | |
| <span class="go"> float</span> | |
| <span class="go">options:</span> | |
| <span class="go"> -h, --help show this help message and exit</span> | |
| <span class="go"> --foo int</span> | |
| </pre></div> | |
| </div> | |
| </section> | |
| <section id="prefix-chars"> | |
| <h3>prefix_chars<a class="headerlink" href="#prefix-chars" title="Link to this heading">¶</a></h3> | |
| <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>. | |
| Parsers that need to support different or additional prefix | |
| characters, e.g. for options | |
| 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 | |
| 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:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'PROG'</span><span class="p">,</span> <span class="n">prefix_chars</span><span class="o">=</span><span class="s1">'-+'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'+f'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'++bar'</span><span class="p">)</span> | |
| <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">'+f X ++bar Y'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span> | |
| <span class="go">Namespace(bar='Y', f='X')</span> | |
| </pre></div> | |
| </div> | |
| <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 | |
| 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 | |
| disallowed.</p> | |
| </section> | |
| <section id="fromfile-prefix-chars"> | |
| <h3>fromfile_prefix_chars<a class="headerlink" href="#fromfile-prefix-chars" title="Link to this heading">¶</a></h3> | |
| <p>Sometimes, when dealing with a particularly long argument list, it | |
| may make sense to keep the list of arguments in a file rather than typing it out | |
| at the command line. If the <code class="docutils literal notranslate"><span class="pre">fromfile_prefix_chars=</span></code> argument is given 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, then arguments that start with any of the | |
| specified characters will be treated as files, and will be replaced by the | |
| arguments they contain. For example:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'args.txt'</span><span class="p">,</span> <span class="s1">'w'</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> | |
| <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">'-f</span><span class="se">\n</span><span class="s1">bar'</span><span class="p">)</span> | |
| <span class="gp">...</span> | |
| <span class="gp">>>> </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">'@'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-f'</span><span class="p">)</span> | |
| <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">'-f'</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">,</span> <span class="s1">'@args.txt'</span><span class="p">])</span> | |
| <span class="go">Namespace(f='bar')</span> | |
| </pre></div> | |
| </div> | |
| <p>Arguments read from a file must be one per line by default (but see also | |
| <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 | |
| were in the same place as the original file referencing argument on the command | |
| 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">'@args.txt']</span></code> | |
| 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> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>Empty lines are treated as empty strings (<code class="docutils literal notranslate"><span class="pre">''</span></code>), which are allowed as values but | |
| not as arguments. Empty lines that are read as arguments will result in an | |
| “unrecognized arguments” error.</p> | |
| </div> | |
| <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> | |
| to read the file containing arguments.</p> | |
| <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 | |
| arguments will never be treated as file references.</p> | |
| <div class="versionchanged"> | |
| <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 | |
| 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 <code class="docutils literal notranslate"><span class="pre">"strict"</span></code>) to the <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>. | |
| Arguments file should be encoded in UTF-8 instead of ANSI Codepage on Windows.</p> | |
| </div> | |
| </section> | |
| <section id="argument-default"> | |
| <h3>argument_default<a class="headerlink" href="#argument-default" title="Link to this heading">¶</a></h3> | |
| <p>Generally, argument defaults are specified either by passing a default 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> or by calling the | |
| <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 | |
| pairs. Sometimes however, it may be useful to specify a single parser-wide | |
| default for arguments. This can be accomplished by passing the | |
| <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, | |
| 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> | |
| calls, we supply <code class="docutils literal notranslate"><span class="pre">argument_default=SUPPRESS</span></code>:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'?'</span><span class="p">)</span> | |
| <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">'--foo'</span><span class="p">,</span> <span class="s1">'1'</span><span class="p">,</span> <span class="s1">'BAR'</span><span class="p">])</span> | |
| <span class="go">Namespace(bar='BAR', foo='1')</span> | |
| <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="go">Namespace()</span> | |
| </pre></div> | |
| </div> | |
| </section> | |
| <section id="allow-abbrev"> | |
| <span id="id4"></span><h3>allow_abbrev<a class="headerlink" href="#allow-abbrev" title="Link to this heading">¶</a></h3> | |
| <p>Normally, when you pass an 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> 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 <a class="reference internal" href="#prefix-matching"><span class="std std-ref">recognizes abbreviations</span></a> of long options.</p> | |
| <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> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'PROG'</span><span class="p">,</span> <span class="n">allow_abbrev</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foobar'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_true'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foonley'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_false'</span><span class="p">)</span> | |
| <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">'--foon'</span><span class="p">])</span> | |
| <span class="go">usage: PROG [-h] [--foobar] [--foonley]</span> | |
| <span class="go">PROG: error: unrecognized arguments: --foon</span> | |
| </pre></div> | |
| </div> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.5.</span></p> | |
| </div> | |
| </section> | |
| <section id="conflict-handler"> | |
| <h3>conflict_handler<a class="headerlink" href="#conflict-handler" title="Link to this heading">¶</a></h3> | |
| <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 | |
| string. By default, <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> objects raise an exception if an | |
| attempt is made to create an argument with an option string that is already in | |
| use:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'PROG'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-f'</span><span class="p">,</span> <span class="s1">'--foo'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'old foo help'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'new foo help'</span><span class="p">)</span> | |
| <span class="gt">Traceback (most recent call last):</span> | |
| <span class="gr"> ..</span> | |
| <span class="gr">ArgumentError</span>: <span class="n">argument --foo: conflicting option string(s): --foo</span> | |
| </pre></div> | |
| </div> | |
| <p>Sometimes (e.g. when using <a class="reference internal" href="#parents">parents</a>) it may be useful to simply override any | |
| older arguments with the same option string. To get this behavior, the value | |
| <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 | |
| <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> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'PROG'</span><span class="p">,</span> <span class="n">conflict_handler</span><span class="o">=</span><span class="s1">'resolve'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-f'</span><span class="p">,</span> <span class="s1">'--foo'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'old foo help'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'new foo help'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span> | |
| <span class="go">usage: PROG [-h] [-f FOO] [--foo FOO]</span> | |
| <span class="go">options:</span> | |
| <span class="go"> -h, --help show this help message and exit</span> | |
| <span class="go"> -f FOO old foo help</span> | |
| <span class="go"> --foo FOO new foo help</span> | |
| </pre></div> | |
| </div> | |
| <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 | |
| option strings are overridden. So, in the example above, the old <code class="docutils literal notranslate"><span class="pre">-f/--foo</span></code> | |
| 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 | |
| string was overridden.</p> | |
| </section> | |
| <section id="add-help"> | |
| <h3>add_help<a class="headerlink" href="#add-help" title="Link to this heading">¶</a></h3> | |
| <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 add an option which simply displays | |
| the parser’s help message. 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 <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> help will be printed.</p> | |
| <p>Occasionally, it may be useful to disable the addition of this help option. | |
| 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 | |
| <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> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'PROG'</span><span class="p">,</span> <span class="n">add_help</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'foo help'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span> | |
| <span class="go">usage: PROG [--foo FOO]</span> | |
| <span class="go">options:</span> | |
| <span class="go"> --foo FOO foo help</span> | |
| </pre></div> | |
| </div> | |
| <p>The help option is typically <code class="docutils literal notranslate"><span class="pre">-h/--help</span></code>. The exception to this is | |
| 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 | |
| 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 | |
| this case, the first character in <code class="docutils literal notranslate"><span class="pre">prefix_chars</span></code> is used to prefix | |
| the help options:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'PROG'</span><span class="p">,</span> <span class="n">prefix_chars</span><span class="o">=</span><span class="s1">'+/'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span> | |
| <span class="go">usage: PROG [+h]</span> | |
| <span class="go">options:</span> | |
| <span class="go"> +h, ++help show this help message and exit</span> | |
| </pre></div> | |
| </div> | |
| </section> | |
| <section id="exit-on-error"> | |
| <h3>exit_on_error<a class="headerlink" href="#exit-on-error" title="Link to this heading">¶</a></h3> | |
| <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> | |
| 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 print a <em>message</em> to <a class="reference internal" href="sys.html#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stderr</span></code></a> and exit with a status | |
| code of 2.</p> | |
| <p>If the user would like to catch errors manually, the feature can be enabled by setting | |
| <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> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--integers'</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="go">_StoreAction(option_strings=['--integers'], dest='integers', nargs=None, const=None, default=None, type=<class 'int'>, choices=None, help=None, metavar=None)</span> | |
| <span class="gp">>>> </span><span class="k">try</span><span class="p">:</span> | |
| <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">'--integers a'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span> | |
| <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> | |
| <span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s1">'Catching an argumentError'</span><span class="p">)</span> | |
| <span class="gp">...</span> | |
| <span class="go">Catching an argumentError</span> | |
| </pre></div> | |
| </div> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.9.</span></p> | |
| </div> | |
| </section> | |
| <section id="suggest-on-error"> | |
| <h3>suggest_on_error<a class="headerlink" href="#suggest-on-error" title="Link to this heading">¶</a></h3> | |
| <p>By default, when a user passes an invalid argument choice or subparser name, | |
| <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 exit with error info and provide suggestions for | |
| mistyped arguments. The error message will list the permissible argument | |
| choices (if specified) or subparser names, along with a “maybe you meant” | |
| suggestion if a close match is found. Note that this only applies for arguments | |
| when the choices specified are strings:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">suggest_on_error</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--action'</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="p">[</span><span class="s1">'debug'</span><span class="p">,</span> <span class="s1">'dryrun'</span><span class="p">])</span> | |
| <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">'--action'</span><span class="p">,</span> <span class="s1">'debugg'</span><span class="p">])</span> | |
| <span class="go">usage: tester.py [-h] [--action {debug,dryrun}]</span> | |
| <span class="go">tester.py: error: argument --action: invalid choice: 'debugg', maybe you meant 'debug'? (choose from debug, dryrun)</span> | |
| </pre></div> | |
| </div> | |
| <p>You can disable suggestions by setting <code class="docutils literal notranslate"><span class="pre">suggest_on_error</span></code> to <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.14.</span></p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.15: </span>Changed default value of <code class="docutils literal notranslate"><span class="pre">suggest_on_error</span></code> from <code class="docutils literal notranslate"><span class="pre">False</span></code> to <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p> | |
| </div> | |
| </section> | |
| <section id="color"> | |
| <h3>color<a class="headerlink" href="#color" title="Link to this heading">¶</a></h3> | |
| <p>By default, the help message is printed in color using <a class="reference external" href="https://en.wikipedia.org/wiki/ANSI_escape_code">ANSI escape sequences</a>. | |
| If you want plain text help messages, you can disable this <a class="reference internal" href="../using/cmdline.html#using-on-controlling-color"><span class="std std-ref">in your local | |
| environment</span></a>, or in the argument parser itself | |
| by setting <code class="docutils literal notranslate"><span class="pre">color</span></code> to <code class="docutils literal notranslate"><span class="pre">False</span></code>:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'Process some integers.'</span><span class="p">,</span> | |
| <span class="gp">... </span> <span class="n">color</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--action'</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="p">[</span><span class="s1">'sum'</span><span class="p">,</span> <span class="s1">'max'</span><span class="p">])</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'integers'</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">'N'</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">'+'</span><span class="p">,</span> | |
| <span class="gp">... </span> <span class="n">help</span><span class="o">=</span><span class="s1">'an integer for the accumulator'</span><span class="p">)</span> | |
| <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">'--help'</span><span class="p">])</span> | |
| </pre></div> | |
| </div> | |
| <p>Note that when <code class="docutils literal notranslate"><span class="pre">color=True</span></code>, colored output depends on both environment | |
| variables and terminal capabilities. However, if <code class="docutils literal notranslate"><span class="pre">color=False</span></code>, colored | |
| output is always disabled, even if environment variables like <code class="docutils literal notranslate"><span class="pre">FORCE_COLOR</span></code> | |
| are set.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.14.</span></p> | |
| </div> | |
| <p>To highlight inline code in your description or epilog text, you can use | |
| backticks:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="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> | |
| <span class="gp">... </span> <span class="n">epilog</span><span class="o">=</span><span class="s1">'''Examples:</span> | |
| <span class="gp">... </span><span class="s1"> `python -m myapp --verbose`</span> | |
| <span class="gp">... </span><span class="s1"> `python -m myapp --config settings.json`</span> | |
| <span class="gp">... </span><span class="s1">'''</span><span class="p">)</span> | |
| </pre></div> | |
| </div> | |
| <p>When colors are enabled, the text inside backticks will be displayed in a | |
| distinct color to help examples stand out. When colors are disabled, backticks | |
| are preserved as-is, which is readable in plain text.</p> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>Backtick markup only applies to description and epilog text. It does not | |
| apply to individual argument <code class="docutils literal notranslate"><span class="pre">help</span></code> strings.</p> | |
| </div> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.15.</span></p> | |
| </div> | |
| </section> | |
| </section> | |
| <section id="the-add-argument-method"> | |
| <h2>The add_argument() method<a class="headerlink" href="#the-add-argument-method" title="Link to this heading">¶</a></h2> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="argparse.ArgumentParser.add_argument"> | |
| <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>, <em class="sig-param"><span class="n"><span class="pre">*</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="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">deprecated</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> | |
| <dd><p>Define how a single command-line argument should be parsed. Each parameter | |
| has its own more detailed description below, but in short they are:</p> | |
| <ul class="simple"> | |
| <li><p><a class="reference internal" href="#name-or-flags">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> | |
| or <code class="docutils literal notranslate"><span class="pre">'-f',</span> <span class="pre">'--foo'</span></code>.</p></li> | |
| <li><p><a class="reference internal" href="#action">action</a> - The basic type of action to be taken when this argument is | |
| encountered at the command line.</p></li> | |
| <li><p><a class="reference internal" href="#nargs">nargs</a> - The number of command-line arguments that should be consumed.</p></li> | |
| <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> | |
| <li><p><a class="reference internal" href="#default">default</a> - The value produced if the argument is absent from the | |
| command line and if it is absent from the namespace object.</p></li> | |
| <li><p><a class="reference internal" href="#type">type</a> - The type to which the command-line argument should be converted.</p></li> | |
| <li><p><a class="reference internal" href="#choices">choices</a> - A sequence of the allowable values for the argument.</p></li> | |
| <li><p><a class="reference internal" href="#required">required</a> - Whether or not the command-line option may be omitted | |
| (optionals only).</p></li> | |
| <li><p><a class="reference internal" href="#help">help</a> - A brief description of what the argument does.</p></li> | |
| <li><p><a class="reference internal" href="#metavar">metavar</a> - A name for the argument in usage messages.</p></li> | |
| <li><p><a class="reference internal" href="#dest">dest</a> - The name of the attribute to be added to 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>.</p></li> | |
| <li><p><a class="reference internal" href="#deprecated">deprecated</a> - Whether or not use of the argument is deprecated.</p></li> | |
| </ul> | |
| <p>The method returns an <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> object representing the argument.</p> | |
| </dd></dl> | |
| <p>The following sections describe how each of these are used.</p> | |
| <section id="name-or-flags"> | |
| <span id="id5"></span><h3>name or flags<a class="headerlink" href="#name-or-flags" title="Link to this heading">¶</a></h3> | |
| <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 | |
| 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 | |
| filenames, is expected. The first arguments passed to | |
| <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code> must therefore be either a series of | |
| flags, or a simple argument name.</p> | |
| <p>For example, an optional argument could be created like:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-f'</span><span class="p">,</span> <span class="s1">'--foo'</span><span class="p">)</span> | |
| </pre></div> | |
| </div> | |
| <p>while a positional argument could be created like:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">)</span> | |
| </pre></div> | |
| </div> | |
| <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 | |
| identified by the <code class="docutils literal notranslate"><span class="pre">-</span></code> prefix, and the remaining arguments will be assumed to | |
| be positional:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'PROG'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-f'</span><span class="p">,</span> <span class="s1">'--foo'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">)</span> | |
| <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">'BAR'</span><span class="p">])</span> | |
| <span class="go">Namespace(bar='BAR', foo=None)</span> | |
| <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">'BAR'</span><span class="p">,</span> <span class="s1">'--foo'</span><span class="p">,</span> <span class="s1">'FOO'</span><span class="p">])</span> | |
| <span class="go">Namespace(bar='BAR', foo='FOO')</span> | |
| <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">'--foo'</span><span class="p">,</span> <span class="s1">'FOO'</span><span class="p">])</span> | |
| <span class="go">usage: PROG [-h] [-f FOO] bar</span> | |
| <span class="go">PROG: error: the following arguments are required: bar</span> | |
| </pre></div> | |
| </div> | |
| <p>By default, <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> automatically handles the internal naming and | |
| display names of arguments, simplifying the process without requiring | |
| additional configuration. | |
| As such, you do not need to specify the <a class="reference internal" href="#dest">dest</a> and <a class="reference internal" href="#metavar">metavar</a> parameters. | |
| For optional arguments, the <a class="reference internal" href="#dest">dest</a> parameter defaults to the argument name, with | |
| underscores <code class="docutils literal notranslate"><span class="pre">_</span></code> replacing hyphens <code class="docutils literal notranslate"><span class="pre">-</span></code>. The <a class="reference internal" href="#metavar">metavar</a> parameter defaults to | |
| the upper-cased name. For example:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'PROG'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo-bar'</span><span class="p">)</span> | |
| <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">'--foo-bar'</span><span class="p">,</span> <span class="s1">'FOO-BAR'</span><span class="p">])</span> | |
| <span class="go">Namespace(foo_bar='FOO-BAR')</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span> | |
| <span class="go">usage: [-h] [--foo-bar FOO-BAR]</span> | |
| <span class="go">optional arguments:</span> | |
| <span class="go"> -h, --help show this help message and exit</span> | |
| <span class="go"> --foo-bar FOO-BAR</span> | |
| </pre></div> | |
| </div> | |
| </section> | |
| <section id="action"> | |
| <span id="id6"></span><h3>action<a class="headerlink" href="#action" title="Link to this heading">¶</a></h3> | |
| <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 | |
| actions can do just about anything with the command-line arguments associated with | |
| them, though most actions simply add an attribute to 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>. The <code class="docutils literal notranslate"><span class="pre">action</span></code> keyword argument specifies | |
| how the command-line arguments should be handled. The supplied actions are:</p> | |
| <ul> | |
| <li><p><code class="docutils literal notranslate"><span class="pre">'store'</span></code> - This just stores the argument’s value. This is the default | |
| action.</p></li> | |
| <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 | |
| 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 | |
| <code class="docutils literal notranslate"><span class="pre">'store_const'</span></code> action is most commonly used with optional arguments that | |
| specify some sort of flag. For example:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_const'</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="mi">42</span><span class="p">)</span> | |
| <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">'--foo'</span><span class="p">])</span> | |
| <span class="go">Namespace(foo=42)</span> | |
| </pre></div> | |
| </div> | |
| </li> | |
| <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 | |
| <code class="docutils literal notranslate"><span class="pre">'store_const'</span></code> that respectively store 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> | |
| with default values of <code class="docutils literal notranslate"><span class="pre">False</span></code> and | |
| <code class="docutils literal notranslate"><span class="pre">True</span></code>:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_true'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--bar'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_false'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--baz'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_false'</span><span class="p">)</span> | |
| <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">'--foo --bar'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span> | |
| <span class="go">Namespace(foo=True, bar=False, baz=True)</span> | |
| </pre></div> | |
| </div> | |
| </li> | |
| <li><p><code class="docutils literal notranslate"><span class="pre">'append'</span></code> - This appends each argument value to a list. | |
| It is useful for allowing an option to be specified multiple times. | |
| If the default value is a non-empty list, the parsed value will start | |
| with the default list’s elements and any values from the command line | |
| will be appended after those default values. Example usage:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'append'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="p">[</span><span class="s1">'0'</span><span class="p">])</span> | |
| <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">'--foo 1 --foo 2'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span> | |
| <span class="go">Namespace(foo=['0', '1', '2'])</span> | |
| </pre></div> | |
| </div> | |
| </li> | |
| <li><p><code class="docutils literal notranslate"><span class="pre">'append_const'</span></code> - This appends the value specified by | |
| the <a class="reference internal" href="#const">const</a> keyword argument to a list; 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 <code class="docutils literal notranslate"><span class="pre">'append_const'</span></code> action is typically | |
| useful when multiple arguments need to store constants to the same list. For | |
| example:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--str'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">'types'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'append_const'</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="nb">str</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--int'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">'types'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'append_const'</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span> | |
| <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">'--str --int'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span> | |
| <span class="go">Namespace(types=[<class 'str'>, <class 'int'>])</span> | |
| </pre></div> | |
| </div> | |
| </li> | |
| <li><p><code class="docutils literal notranslate"><span class="pre">'extend'</span></code> - This appends each item from a multi-value | |
| argument to a list. | |
| The <code class="docutils literal notranslate"><span class="pre">'extend'</span></code> action is typically used with the <a class="reference internal" href="#nargs">nargs</a> keyword argument | |
| value <code class="docutils literal notranslate"><span class="pre">'+'</span></code> or <code class="docutils literal notranslate"><span class="pre">'*'</span></code>. | |
| Note that when <a class="reference internal" href="#nargs">nargs</a> is <code class="docutils literal notranslate"><span class="pre">None</span></code> (the default) or <code class="docutils literal notranslate"><span class="pre">'?'</span></code>, each | |
| character of the argument string will be appended to the list. | |
| Example usage:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s2">"--foo"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"extend"</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s2">"+"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">str</span><span class="p">)</span> | |
| <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="s2">"--foo"</span><span class="p">,</span> <span class="s2">"f1"</span><span class="p">,</span> <span class="s2">"--foo"</span><span class="p">,</span> <span class="s2">"f2"</span><span class="p">,</span> <span class="s2">"f3"</span><span class="p">,</span> <span class="s2">"f4"</span><span class="p">])</span> | |
| <span class="go">Namespace(foo=['f1', 'f2', 'f3', 'f4'])</span> | |
| </pre></div> | |
| </div> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.8.</span></p> | |
| </div> | |
| </li> | |
| <li><p><code class="docutils literal notranslate"><span class="pre">'count'</span></code> - This counts the number of times an argument occurs. For | |
| example, this is useful for increasing verbosity levels:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--verbose'</span><span class="p">,</span> <span class="s1">'-v'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'count'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span> | |
| <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">'-vvv'</span><span class="p">])</span> | |
| <span class="go">Namespace(verbose=3)</span> | |
| </pre></div> | |
| </div> | |
| <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> | |
| </li> | |
| <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 | |
| current parser and then exits. By default a help action is automatically | |
| 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 | |
| output is created.</p></li> | |
| <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 | |
| <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 | |
| and exits when invoked:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">argparse</span> | |
| <span class="gp">>>> </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">'PROG'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--version'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'version'</span><span class="p">,</span> <span class="n">version</span><span class="o">=</span><span class="s1">'</span><span class="si">%(prog)s</span><span class="s1"> 2.0'</span><span class="p">)</span> | |
| <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">'--version'</span><span class="p">])</span> | |
| <span class="go">PROG 2.0</span> | |
| </pre></div> | |
| </div> | |
| </li> | |
| </ul> | |
| <p>You may also specify an arbitrary action by passing an <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> subclass | |
| (e.g. <a class="reference internal" href="#argparse.BooleanOptionalAction" title="argparse.BooleanOptionalAction"><code class="xref py py-class docutils literal notranslate"><span class="pre">BooleanOptionalAction</span></code></a>) or other object that implements the same | |
| interface. Only actions that consume command-line arguments (e.g. <code class="docutils literal notranslate"><span class="pre">'store'</span></code>, | |
| <code class="docutils literal notranslate"><span class="pre">'append'</span></code>, <code class="docutils literal notranslate"><span class="pre">'extend'</span></code>, or custom actions with non-zero <code class="docutils literal notranslate"><span class="pre">nargs</span></code>) can be used | |
| with positional arguments.</p> | |
| <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>, | |
| overriding the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__call__()</span></code> method and optionally the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> and | |
| <code class="xref py py-meth docutils literal notranslate"><span class="pre">format_usage()</span></code> methods. You can also register custom actions using the | |
| <a class="reference internal" href="#argparse.ArgumentParser.register" title="argparse.ArgumentParser.register"><code class="xref py py-meth docutils literal notranslate"><span class="pre">register()</span></code></a> method and reference them by their registered name.</p> | |
| <p>An example of a custom action:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">class</span><span class="w"> </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> | |
| <span class="gp">... </span> <span class="k">def</span><span class="w"> </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> | |
| <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> | |
| <span class="gp">... </span> <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">"nargs not allowed"</span><span class="p">)</span> | |
| <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> | |
| <span class="gp">... </span> <span class="k">def</span><span class="w"> </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> | |
| <span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s1">'</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">'</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> | |
| <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> | |
| <span class="gp">...</span> | |
| <span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="n">FooAction</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="n">FooAction</span><span class="p">)</span> | |
| <span class="gp">>>> </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">'1 --foo 2'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span> | |
| <span class="go">Namespace(bar=None, foo=None) '1' None</span> | |
| <span class="go">Namespace(bar='1', foo=None) '2' '--foo'</span> | |
| <span class="gp">>>> </span><span class="n">args</span> | |
| <span class="go">Namespace(bar='1', foo='2')</span> | |
| </pre></div> | |
| </div> | |
| <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> | |
| </section> | |
| <section id="nargs"> | |
| <span id="id7"></span><h3>nargs<a class="headerlink" href="#nargs" title="Link to this heading">¶</a></h3> | |
| <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 usually associate a single command-line argument with a | |
| single action to be taken. The <code class="docutils literal notranslate"><span class="pre">nargs</span></code> keyword argument associates a | |
| different number of command-line arguments with a single action. | |
| 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> | |
| <ul> | |
| <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 | |
| together into a list. For example:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span> | |
| <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">'c --foo a b'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span> | |
| <span class="go">Namespace(bar=['c'], foo=['a', 'b'])</span> | |
| </pre></div> | |
| </div> | |
| <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 | |
| the default, in which the item is produced by itself.</p> | |
| </li> | |
| </ul> | |
| <ul id="index-0"> | |
| <li><p><code class="docutils literal notranslate"><span class="pre">'?'</span></code>. One argument will be consumed from the command line if possible, and | |
| produced as a single item. If no command-line argument is present, the value from | |
| <a class="reference internal" href="#default">default</a> will be produced. Note that for optional arguments, there is an | |
| additional case - the option string is present but not followed by a | |
| command-line argument. In this case the value from <a class="reference internal" href="#const">const</a> will be produced. Some | |
| examples to illustrate this:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'?'</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s1">'c'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">'d'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'?'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">'d'</span><span class="p">)</span> | |
| <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">'XX'</span><span class="p">,</span> <span class="s1">'--foo'</span><span class="p">,</span> <span class="s1">'YY'</span><span class="p">])</span> | |
| <span class="go">Namespace(bar='XX', foo='YY')</span> | |
| <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">'XX'</span><span class="p">,</span> <span class="s1">'--foo'</span><span class="p">])</span> | |
| <span class="go">Namespace(bar='XX', foo='c')</span> | |
| <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="go">Namespace(bar='d', foo='d')</span> | |
| </pre></div> | |
| </div> | |
| <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 | |
| output files:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'infile'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'?'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'outfile'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'?'</span><span class="p">)</span> | |
| <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">'input.txt'</span><span class="p">,</span> <span class="s1">'output.txt'</span><span class="p">])</span> | |
| <span class="go">Namespace(infile='input.txt', outfile='output.txt')</span> | |
| <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">'input.txt'</span><span class="p">])</span> | |
| <span class="go">Namespace(infile='input.txt', outfile=None)</span> | |
| <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="go">Namespace(infile=None, outfile=None)</span> | |
| </pre></div> | |
| </div> | |
| </li> | |
| </ul> | |
| <ul id="index-1"> | |
| <li><p><code class="docutils literal notranslate"><span class="pre">'*'</span></code>. All command-line arguments present are gathered into a list. Note that | |
| it generally doesn’t make much sense to have more than one positional argument | |
| 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 | |
| possible. For example:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'*'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'*'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'baz'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'*'</span><span class="p">)</span> | |
| <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">'a b --foo x y --bar 1 2'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span> | |
| <span class="go">Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])</span> | |
| </pre></div> | |
| </div> | |
| </li> | |
| </ul> | |
| <ul id="index-2"> | |
| <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 arguments present are gathered into a | |
| list. Additionally, an error message will be generated if there wasn’t at | |
| least one command-line argument present. For example:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'PROG'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'+'</span><span class="p">)</span> | |
| <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">'a'</span><span class="p">,</span> <span class="s1">'b'</span><span class="p">])</span> | |
| <span class="go">Namespace(foo=['a', 'b'])</span> | |
| <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="go">usage: PROG [-h] foo [foo ...]</span> | |
| <span class="go">PROG: error: the following arguments are required: foo</span> | |
| </pre></div> | |
| </div> | |
| </li> | |
| </ul> | |
| <p>If the <code class="docutils literal notranslate"><span class="pre">nargs</span></code> keyword argument is not provided, the number of arguments consumed | |
| is determined by the <a class="reference internal" href="#action">action</a>. Generally this means a single command-line argument | |
| will be consumed and a single item (not a list) will be produced. | |
| Actions that do not consume command-line arguments (e.g. | |
| <code class="docutils literal notranslate"><span class="pre">'store_const'</span></code>) set <code class="docutils literal notranslate"><span class="pre">nargs=0</span></code>.</p> | |
| </section> | |
| <section id="const"> | |
| <span id="id8"></span><h3>const<a class="headerlink" href="#const" title="Link to this heading">¶</a></h3> | |
| <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 | |
| constant values that are not read from the command line but are required for | |
| 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> | |
| <ul class="simple"> | |
| <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 | |
| <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 | |
| <code class="docutils literal notranslate"><span class="pre">const</span></code> value to one of 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>. See the <a class="reference internal" href="#action">action</a> description for examples. | |
| If <code class="docutils literal notranslate"><span class="pre">const</span></code> is not provided to <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code>, it will | |
| receive a default value of <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li> | |
| <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 | |
| (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 | |
| argument that can be followed by zero or one command-line arguments. | |
| When parsing the command line, if the option string is encountered with no | |
| command-line argument following it, the value from <code class="docutils literal notranslate"><span class="pre">const</span></code> will be used. | |
| See the <a class="reference internal" href="#nargs">nargs</a> description for examples.</p></li> | |
| </ul> | |
| <div class="versionchanged"> | |
| <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 | |
| <code class="docutils literal notranslate"><span class="pre">action='store_const'</span></code>.</p> | |
| </div> | |
| </section> | |
| <section id="default"> | |
| <span id="id9"></span><h3>default<a class="headerlink" href="#default" title="Link to this heading">¶</a></h3> | |
| <p>All optional arguments and some positional arguments may be omitted at the | |
| command line. The <code class="docutils literal notranslate"><span class="pre">default</span></code> keyword 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>, whose value defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>, | |
| specifies what value should be used if the command-line argument is not present. | |
| For optional arguments, the <code class="docutils literal notranslate"><span class="pre">default</span></code> value is used when the option string | |
| was not present at the command line:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="s1">'2'</span><span class="p">])</span> | |
| <span class="go">Namespace(foo='2')</span> | |
| <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="go">Namespace(foo=42)</span> | |
| </pre></div> | |
| </div> | |
| <p>If the target namespace already has an attribute set, the action <em>default</em> | |
| will not overwrite it:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</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="gp">>>> </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> | |
| <span class="go">Namespace(foo=101)</span> | |
| </pre></div> | |
| </div> | |
| <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 | |
| were a command-line argument. In particular, the parser applies any <a class="reference internal" href="#type">type</a> | |
| conversion argument, if provided, before setting the attribute on 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> return value. Otherwise, the parser uses the value as is:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--length'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">'10'</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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--width'</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> | |
| <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="go">Namespace(length=10, width=10.5)</span> | |
| </pre></div> | |
| </div> | |
| <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 | |
| is used when no command-line argument was present:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'?'</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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'a'</span><span class="p">])</span> | |
| <span class="go">Namespace(foo='a')</span> | |
| <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="go">Namespace(foo=42)</span> | |
| </pre></div> | |
| </div> | |
| <p>For <a class="reference internal" href="#required">required</a> arguments, the <code class="docutils literal notranslate"><span class="pre">default</span></code> value is ignored. For example, this | |
| applies to positional arguments with <a class="reference internal" href="#nargs">nargs</a> values other than <code class="docutils literal notranslate"><span class="pre">?</span></code> or <code class="docutils literal notranslate"><span class="pre">*</span></code>, | |
| or optional arguments marked as <code class="docutils literal notranslate"><span class="pre">required=True</span></code>.</p> | |
| <p>Providing <code class="docutils literal notranslate"><span class="pre">default=argparse.SUPPRESS</span></code> causes no attribute to be added if the | |
| command-line argument was not present:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</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> | |
| <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="go">Namespace()</span> | |
| <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">'--foo'</span><span class="p">,</span> <span class="s1">'1'</span><span class="p">])</span> | |
| <span class="go">Namespace(foo='1')</span> | |
| </pre></div> | |
| </div> | |
| </section> | |
| <section id="type"> | |
| <span id="argparse-type"></span><h3>type<a class="headerlink" href="#type" title="Link to this heading">¶</a></h3> | |
| <p>By default, the parser reads command-line arguments in as simple | |
| strings. However, quite often the command-line string should instead be | |
| 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 | |
| <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 | |
| necessary type-checking and type conversions to be performed.</p> | |
| <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 | |
| is only applied if the default is a string.</p> | |
| <p>The argument to <code class="docutils literal notranslate"><span class="pre">type</span></code> can be a callable that accepts a single string or | |
| the name of a registered type (see <a class="reference internal" href="#argparse.ArgumentParser.register" title="argparse.ArgumentParser.register"><code class="xref py py-meth docutils literal notranslate"><span class="pre">register()</span></code></a>) | |
| 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 | |
| <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 | |
| message is displayed. Other exception types are not handled.</p> | |
| <p>Common built-in types and functions can be used as type converters:</p> | |
| <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">argparse</span> | |
| <span class="kn">import</span><span class="w"> </span><span class="nn">pathlib</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">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'count'</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">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'distance'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">float</span><span class="p">)</span> | |
| <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'street'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="n">ascii</span><span class="p">)</span> | |
| <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'code_point'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">ord</span><span class="p">)</span> | |
| <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'datapath'</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> | |
| </pre></div> | |
| </div> | |
| <p>User defined functions can be used as well:</p> | |
| <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">def</span><span class="w"> </span><span class="nf">hyphenated</span><span class="p">(</span><span class="n">string</span><span class="p">):</span> | |
| <span class="gp">... </span> <span class="k">return</span> <span class="s1">'-'</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> | |
| <span class="gp">...</span> | |
| <span class="gp">>>> </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="gp">>>> </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">'short_title'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="n">hyphenated</span><span class="p">)</span> | |
| <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">'"The Tale of Two Cities"'</span><span class="p">])</span> | |
| <span class="go">Namespace(short_title='"the-tale-of-two-citi')</span> | |
| </pre></div> | |
| </div> | |
| <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 | |
| 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>. | |
| This is usually not what is desired.</p> | |
| <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 | |
| simple conversions that can only raise one of the three supported exceptions. | |
| Anything with more interesting error-handling or resource management should be | |
| done downstream after the arguments are parsed.</p> | |
| <p>For example, JSON or YAML conversions have complex error cases that require | |
| better reporting than can be given by the <code class="docutils literal notranslate"><span class="pre">type</span></code> keyword. A | |
| <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 | |
| <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> | |
| <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> | |
| keyword. If one argument uses <code class="xref py py-class docutils literal notranslate"><span class="pre">FileType</span></code> and then a | |
| subsequent argument fails, an error is reported but the file is not | |
| automatically closed. In this case, it would be better to wait until after | |
| the parser has run and then use the <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> | |
| <p>For type checkers that simply check against a fixed set of values, consider | |
| using the <a class="reference internal" href="#choices">choices</a> keyword instead.</p> | |
| </section> | |
| <section id="choices"> | |
| <span id="id10"></span><h3>choices<a class="headerlink" href="#choices" title="Link to this heading">¶</a></h3> | |
| <p>Some command-line arguments should be selected from a restricted set of values. | |
| These can be handled by passing a sequence object as the <em>choices</em> 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>. When the command line is | |
| parsed, argument values will be checked, and an error message will be displayed | |
| if the argument was not one of the acceptable values:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'game.py'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'move'</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="p">[</span><span class="s1">'rock'</span><span class="p">,</span> <span class="s1">'paper'</span><span class="p">,</span> <span class="s1">'scissors'</span><span class="p">])</span> | |
| <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">'rock'</span><span class="p">])</span> | |
| <span class="go">Namespace(move='rock')</span> | |
| <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">'fire'</span><span class="p">])</span> | |
| <span class="go">usage: game.py [-h] {rock,paper,scissors}</span> | |
| <span class="go">game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',</span> | |
| <span class="go">'paper', 'scissors')</span> | |
| </pre></div> | |
| </div> | |
| <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, | |
| <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> | |
| <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 | |
| control its appearance in usage, help, and error messages.</p> | |
| <p>Note that <em>choices</em> are checked after any <a class="reference internal" href="#type">type</a> | |
| conversions have been performed, so objects in <em>choices</em> | |
| should match the <a class="reference internal" href="#type">type</a> specified. This can make <em>choices</em> | |
| appear unfamiliar in usage, help, or error messages.</p> | |
| <p>To keep <em>choices</em> user-friendly, consider a custom type wrapper that | |
| converts and formats values, or omit <a class="reference internal" href="#type">type</a> and handle conversion in | |
| your application code.</p> | |
| <p>Formatted choices override the default <em>metavar</em> which is normally derived | |
| from <em>dest</em>. This is usually what you want because the user never sees the | |
| <em>dest</em> parameter. If this display isn’t desirable (perhaps because there are | |
| many choices), just specify an explicit <a class="reference internal" href="#metavar">metavar</a>.</p> | |
| </section> | |
| <section id="required"> | |
| <span id="id11"></span><h3>required<a class="headerlink" href="#required" title="Link to this heading">¶</a></h3> | |
| <p>In general, the <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> 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> | |
| indicate <em>optional</em> arguments, which can always be omitted at the command line. | |
| 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> | |
| 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> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">required</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span> | |
| <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">'--foo'</span><span class="p">,</span> <span class="s1">'BAR'</span><span class="p">])</span> | |
| <span class="go">Namespace(foo='BAR')</span> | |
| <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="go">usage: [-h] --foo FOO</span> | |
| <span class="go">: error: the following arguments are required: --foo</span> | |
| </pre></div> | |
| </div> | |
| <p>As the example shows, if an option is marked as <code class="docutils literal notranslate"><span class="pre">required</span></code>, | |
| <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 | |
| present at the command line.</p> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>Required options are generally considered bad form because users expect | |
| <em>options</em> to be <em>optional</em>, and thus they should be avoided when possible.</p> | |
| </div> | |
| </section> | |
| <section id="help"> | |
| <span id="id12"></span><h3>help<a class="headerlink" href="#help" title="Link to this heading">¶</a></h3> | |
| <p>The <code class="docutils literal notranslate"><span class="pre">help</span></code> value is a string containing a brief description of the argument. | |
| 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 | |
| command line), these <code class="docutils literal notranslate"><span class="pre">help</span></code> descriptions will be displayed with each | |
| argument.</p> | |
| <p>The <code class="docutils literal notranslate"><span class="pre">help</span></code> strings can include various format specifiers to avoid repetition | |
| of things like the program name or the argument <a class="reference internal" href="#default">default</a>. The available | |
| specifiers include the program name, <code class="docutils literal notranslate"><span class="pre">%(prog)s</span></code> and most keyword arguments 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>, 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> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'frobble'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'?'</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="gp">... </span> <span class="n">help</span><span class="o">=</span><span class="s1">'the bar to </span><span class="si">%(prog)s</span><span class="s1"> (default: </span><span class="si">%(default)s</span><span class="s1">)'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span> | |
| <span class="go">usage: frobble [-h] [bar]</span> | |
| <span class="go">positional arguments:</span> | |
| <span class="go"> bar the bar to frobble (default: 42)</span> | |
| <span class="go">options:</span> | |
| <span class="go"> -h, --help show this help message and exit</span> | |
| </pre></div> | |
| </div> | |
| <p>As the help string supports %-formatting, if you want a literal <code class="docutils literal notranslate"><span class="pre">%</span></code> to appear | |
| in the help string, you must escape it as <code class="docutils literal notranslate"><span class="pre">%%</span></code>.</p> | |
| <p><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> supports silencing the help entry for certain options, by | |
| 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> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'frobble'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</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> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span> | |
| <span class="go">usage: frobble [-h]</span> | |
| <span class="go">options:</span> | |
| <span class="go"> -h, --help show this help message and exit</span> | |
| </pre></div> | |
| </div> | |
| </section> | |
| <section id="metavar"> | |
| <span id="id13"></span><h3>metavar<a class="headerlink" href="#metavar" title="Link to this heading">¶</a></h3> | |
| <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 | |
| to each expected argument. By default, <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> objects use the <a class="reference internal" href="#dest">dest</a> | |
| value as the “name” of each object. By default, for positional argument | |
| actions, the <a class="reference internal" href="#dest">dest</a> value is used directly, and for optional argument actions, | |
| the <a class="reference internal" href="#dest">dest</a> value is uppercased. So, a single positional argument with | |
| <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 | |
| optional argument <code class="docutils literal notranslate"><span class="pre">--foo</span></code> that should be followed by a single command-line argument | |
| will be referred to as <code class="docutils literal notranslate"><span class="pre">FOO</span></code>. An example:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">)</span> | |
| <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">'X --foo Y'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span> | |
| <span class="go">Namespace(bar='X', foo='Y')</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span> | |
| <span class="go">usage: [-h] [--foo FOO] bar</span> | |
| <span class="go">positional arguments:</span> | |
| <span class="go"> bar</span> | |
| <span class="go">options:</span> | |
| <span class="go"> -h, --help show this help message and exit</span> | |
| <span class="go"> --foo FOO</span> | |
| </pre></div> | |
| </div> | |
| <p>An alternative name can be specified with <code class="docutils literal notranslate"><span class="pre">metavar</span></code>:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">'YYY'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">'XXX'</span><span class="p">)</span> | |
| <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">'X --foo Y'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span> | |
| <span class="go">Namespace(bar='X', foo='Y')</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span> | |
| <span class="go">usage: [-h] [--foo YYY] XXX</span> | |
| <span class="go">positional arguments:</span> | |
| <span class="go"> XXX</span> | |
| <span class="go">options:</span> | |
| <span class="go"> -h, --help show this help message and exit</span> | |
| <span class="go"> --foo YYY</span> | |
| </pre></div> | |
| </div> | |
| <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 | |
| 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 | |
| by the <a class="reference internal" href="#dest">dest</a> value.</p> | |
| <p>Different values of <code class="docutils literal notranslate"><span class="pre">nargs</span></code> may cause the metavar to be used multiple times. | |
| Providing a tuple to <code class="docutils literal notranslate"><span class="pre">metavar</span></code> specifies a different display for each of the | |
| arguments:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'PROG'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-x'</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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</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">'bar'</span><span class="p">,</span> <span class="s1">'baz'</span><span class="p">))</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span> | |
| <span class="go">usage: PROG [-h] [-x X X] [--foo bar baz]</span> | |
| <span class="go">options:</span> | |
| <span class="go"> -h, --help show this help message and exit</span> | |
| <span class="go"> -x X X</span> | |
| <span class="go"> --foo bar baz</span> | |
| </pre></div> | |
| </div> | |
| </section> | |
| <section id="dest"> | |
| <span id="id14"></span><h3>dest<a class="headerlink" href="#dest" title="Link to this heading">¶</a></h3> | |
| <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 | |
| 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 | |
| attribute is determined by the <code class="docutils literal notranslate"><span class="pre">dest</span></code> keyword 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>. For positional argument actions, | |
| <code class="docutils literal notranslate"><span class="pre">dest</span></code> is normally supplied as the first argument to | |
| <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code>:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">)</span> | |
| <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">'XXX'</span><span class="p">])</span> | |
| <span class="go">Namespace(bar='XXX')</span> | |
| </pre></div> | |
| </div> | |
| <p>For optional argument actions, the value of <code class="docutils literal notranslate"><span class="pre">dest</span></code> is normally inferred from | |
| 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 | |
| taking the first double-dash long option string and stripping away the initial | |
| <code class="docutils literal notranslate"><span class="pre">-</span></code> characters. | |
| If no double-dash long option strings were supplied, <code class="docutils literal notranslate"><span class="pre">dest</span></code> will be derived | |
| from the first single-dash long option string by stripping the initial <code class="docutils literal notranslate"><span class="pre">-</span></code> | |
| character. | |
| If no long option strings were supplied, <code class="docutils literal notranslate"><span class="pre">dest</span></code> will be derived from | |
| the first short option string by stripping the initial <code class="docutils literal notranslate"><span class="pre">-</span></code> character. Any | |
| 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 | |
| the string is a valid attribute name. The examples below illustrate this | |
| behavior:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-f'</span><span class="p">,</span> <span class="s1">'--foo-bar'</span><span class="p">,</span> <span class="s1">'--foo'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-q'</span><span class="p">,</span> <span class="s1">'-quz'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-x'</span><span class="p">,</span> <span class="s1">'-y'</span><span class="p">)</span> | |
| <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">'-f 1 -q 2 -x 3'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span> | |
| <span class="go">Namespace(foo_bar='1', quz='2', x='3')</span> | |
| <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">'--foo 1 -quz 2 -y 3'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span> | |
| <span class="go">Namespace(foo_bar='1', quz='2', x='2')</span> | |
| </pre></div> | |
| </div> | |
| <p><code class="docutils literal notranslate"><span class="pre">dest</span></code> allows a custom attribute name to be provided:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">'bar'</span><span class="p">)</span> | |
| <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">'--foo XXX'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span> | |
| <span class="go">Namespace(bar='XXX')</span> | |
| </pre></div> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.15: </span>Single-dash long option now takes precedence over short options.</p> | |
| </div> | |
| </section> | |
| <section id="deprecated"> | |
| <span id="id15"></span><h3>deprecated<a class="headerlink" href="#deprecated" title="Link to this heading">¶</a></h3> | |
| <p>During a project’s lifetime, some arguments may need to be removed from the | |
| command line. Before removing them, you should inform | |
| your users that the arguments are deprecated and will be removed. | |
| The <code class="docutils literal notranslate"><span class="pre">deprecated</span></code> keyword 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>, which defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>, | |
| specifies if the argument is deprecated and will be removed | |
| in the future. | |
| For arguments, if <code class="docutils literal notranslate"><span class="pre">deprecated</span></code> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, then a warning will be | |
| printed to <a class="reference internal" href="sys.html#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stderr</span></code></a> when the argument is used:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">argparse</span> | |
| <span class="gp">>>> </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">'snake.py'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--legs'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">0</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">deprecated</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span> | |
| <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="go">Namespace(legs=0)</span> | |
| <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">'--legs'</span><span class="p">,</span> <span class="s1">'4'</span><span class="p">])</span> | |
| <span class="go">snake.py: warning: option '--legs' is deprecated</span> | |
| <span class="go">Namespace(legs=4)</span> | |
| </pre></div> | |
| </div> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.13.</span></p> | |
| </div> | |
| </section> | |
| <section id="action-classes"> | |
| <h3>Action classes<a class="headerlink" href="#action-classes" title="Link to this heading">¶</a></h3> | |
| <p><code class="xref py py-class docutils literal notranslate"><span class="pre">Action</span></code> classes implement the Action API, a callable which returns a callable | |
| which processes arguments from the command-line. Any object which follows | |
| this API may be passed as the <code class="docutils literal notranslate"><span class="pre">action</span></code> parameter 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> | |
| <dl class="py class"> | |
| <dt class="sig sig-object py" id="argparse.Action"> | |
| <em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">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> | |
| <dd><p><code class="xref py py-class docutils literal notranslate"><span class="pre">Action</span></code> objects are used by 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> to represent the information | |
| needed to parse a single argument from one or more strings from the | |
| command line. The <code class="xref py py-class docutils literal notranslate"><span class="pre">Action</span></code> class must accept the two positional arguments | |
| 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> | |
| except for the <code class="docutils literal notranslate"><span class="pre">action</span></code> itself.</p> | |
| <p>Instances of <code class="xref py py-class docutils literal notranslate"><span class="pre">Action</span></code> (or return value of any callable to the | |
| <code class="docutils literal notranslate"><span class="pre">action</span></code> parameter) should have attributes <code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code>, | |
| <code class="xref py py-attr docutils literal notranslate"><span class="pre">option_strings</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">default</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">required</span></code>, | |
| <code class="xref py py-attr docutils literal notranslate"><span class="pre">help</span></code>, etc. defined. The easiest way to ensure these attributes | |
| are defined is to call <code class="xref py py-meth docutils literal notranslate"><span class="pre">Action.__init__()</span></code>.</p> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="argparse.Action.__call__"> | |
| <span class="sig-name descname"><span class="pre">__call__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">parser</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">namespace</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">values</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">option_string</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.__call__" title="Link to this definition">¶</a></dt> | |
| <dd><p><code class="xref py py-class docutils literal notranslate"><span class="pre">Action</span></code> instances should be callable, so subclasses must override the | |
| <code class="xref py py-meth docutils literal notranslate"><span class="pre">__call__()</span></code> method, which should accept four parameters:</p> | |
| <ul class="simple"> | |
| <li><p><em>parser</em> - 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 which contains this action.</p></li> | |
| <li><p><em>namespace</em> - 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 | |
| <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 | |
| 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> | |
| <li><p><em>values</em> - The associated command-line arguments, with any type conversions | |
| applied. Type conversions are specified with the <a class="reference internal" href="#type">type</a> 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></li> | |
| <li><p><em>option_string</em> - The option string that was used to invoke this action. | |
| The <code class="docutils literal notranslate"><span class="pre">option_string</span></code> argument is optional, and will be absent if the action | |
| is associated with a positional argument.</p></li> | |
| </ul> | |
| <p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">__call__()</span></code> method may perform arbitrary actions, but will typically set | |
| 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> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="argparse.Action.format_usage"> | |
| <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.Action.format_usage" title="Link to this definition">¶</a></dt> | |
| <dd><p><code class="xref py py-class docutils literal notranslate"><span class="pre">Action</span></code> subclasses can define a <code class="xref py py-meth docutils literal notranslate"><span class="pre">format_usage()</span></code> method that takes no argument | |
| and return a string which will be used when printing the usage of the program. | |
| If such method is not provided, a sensible default will be used.</p> | |
| </dd></dl> | |
| </dd></dl> | |
| <dl class="py class"> | |
| <dt class="sig sig-object py" id="argparse.BooleanOptionalAction"> | |
| <em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">argparse.</span></span><span class="sig-name descname"><span class="pre">BooleanOptionalAction</span></span><a class="headerlink" href="#argparse.BooleanOptionalAction" title="Link to this definition">¶</a></dt> | |
| <dd><p>A subclass of <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> for handling boolean flags with positive | |
| and negative options. Adding a single argument such as <code class="docutils literal notranslate"><span class="pre">--foo</span></code> automatically | |
| creates both <code class="docutils literal notranslate"><span class="pre">--foo</span></code> and <code class="docutils literal notranslate"><span class="pre">--no-foo</span></code> options, storing <code class="docutils literal notranslate"><span class="pre">True</span></code> and <code class="docutils literal notranslate"><span class="pre">False</span></code> | |
| respectively:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">argparse</span> | |
| <span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</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> | |
| <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">'--no-foo'</span><span class="p">])</span> | |
| <span class="go">Namespace(foo=False)</span> | |
| </pre></div> | |
| </div> | |
| <p>Single-dash long options are also supported. | |
| For example, negative option <code class="docutils literal notranslate"><span class="pre">-nofoo</span></code> is automatically added for | |
| positive option <code class="docutils literal notranslate"><span class="pre">-foo</span></code>. | |
| But no additional options are added for short options such as <code class="docutils literal notranslate"><span class="pre">-f</span></code>.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.9.</span></p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.15: </span>Added support for single-dash options.</p> | |
| <p>Added support for alternate <a class="reference internal" href="#prefix-chars">prefix_chars</a>.</p> | |
| </div> | |
| </dd></dl> | |
| </section> | |
| </section> | |
| <section id="the-parse-args-method"> | |
| <h2>The parse_args() method<a class="headerlink" href="#the-parse-args-method" title="Link to this heading">¶</a></h2> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="argparse.ArgumentParser.parse_args"> | |
| <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> | |
| <dd><p>Convert argument strings to objects and assign them as attributes of the | |
| namespace. Return the populated namespace.</p> | |
| <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 | |
| created and how they are assigned. See the documentation for | |
| <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code> for details.</p> | |
| <ul class="simple"> | |
| <li><p><a class="reference internal" href="#args">args</a> - List of strings to parse. The default is taken 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></li> | |
| <li><p><a class="reference internal" href="#namespace">namespace</a> - An object to take the attributes. The default is a new empty | |
| <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> | |
| </ul> | |
| </dd></dl> | |
| <section id="option-value-syntax"> | |
| <h3>Option value syntax<a class="headerlink" href="#option-value-syntax" title="Link to this heading">¶</a></h3> | |
| <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 | |
| specifying the value of an option (if it takes one). In the simplest case, the | |
| option and its value are passed as two separate arguments:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'PROG'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-x'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">)</span> | |
| <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">'-x'</span><span class="p">,</span> <span class="s1">'X'</span><span class="p">])</span> | |
| <span class="go">Namespace(foo=None, x='X')</span> | |
| <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">'--foo'</span><span class="p">,</span> <span class="s1">'FOO'</span><span class="p">])</span> | |
| <span class="go">Namespace(foo='FOO', x=None)</span> | |
| </pre></div> | |
| </div> | |
| <p>For long options (options with names longer than a single character), the option | |
| and value can also be passed as a single command-line argument, using <code class="docutils literal notranslate"><span class="pre">=</span></code> to | |
| separate them:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><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">'--foo=FOO'</span><span class="p">])</span> | |
| <span class="go">Namespace(foo='FOO', x=None)</span> | |
| </pre></div> | |
| </div> | |
| <p>For short options (options only one character long), the option and its value | |
| can be concatenated:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><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">'-xX'</span><span class="p">])</span> | |
| <span class="go">Namespace(foo=None, x='X')</span> | |
| </pre></div> | |
| </div> | |
| <p>Several short options can be joined together, using only a single <code class="docutils literal notranslate"><span class="pre">-</span></code> prefix, | |
| as long as only the last option (or none of them) requires a value:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'PROG'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-x'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_true'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-y'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_true'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-z'</span><span class="p">)</span> | |
| <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">'-xyzZ'</span><span class="p">])</span> | |
| <span class="go">Namespace(x=True, y=True, z='Z')</span> | |
| </pre></div> | |
| </div> | |
| </section> | |
| <section id="invalid-arguments"> | |
| <h3>Invalid arguments<a class="headerlink" href="#invalid-arguments" title="Link to this heading">¶</a></h3> | |
| <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 | |
| variety of errors, including ambiguous options, invalid types, invalid options, | |
| wrong number of positional arguments, etc. When it encounters such an error, | |
| it exits and prints the error along with a usage message:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'PROG'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'?'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="c1"># invalid type</span> | |
| <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">'--foo'</span><span class="p">,</span> <span class="s1">'spam'</span><span class="p">])</span> | |
| <span class="go">usage: PROG [-h] [--foo FOO] [bar]</span> | |
| <span class="go">PROG: error: argument --foo: invalid int value: 'spam'</span> | |
| <span class="gp">>>> </span><span class="c1"># invalid option</span> | |
| <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">'--bar'</span><span class="p">])</span> | |
| <span class="go">usage: PROG [-h] [--foo FOO] [bar]</span> | |
| <span class="go">PROG: error: no such option: --bar</span> | |
| <span class="gp">>>> </span><span class="c1"># wrong number of arguments</span> | |
| <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">'spam'</span><span class="p">,</span> <span class="s1">'badger'</span><span class="p">])</span> | |
| <span class="go">usage: PROG [-h] [--foo FOO] [bar]</span> | |
| <span class="go">PROG: error: extra arguments found: badger</span> | |
| </pre></div> | |
| </div> | |
| </section> | |
| <section id="arguments-containing"> | |
| <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> | |
| <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 | |
| the user has clearly made a mistake, but some situations are inherently | |
| ambiguous. For example, the command-line argument <code class="docutils literal notranslate"><span class="pre">-1</span></code> could either be an | |
| attempt to specify an option or an attempt to provide a positional argument. | |
| The <code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code> method is cautious here: positional | |
| arguments may only begin with <code class="docutils literal notranslate"><span class="pre">-</span></code> if they look like negative numbers and | |
| there are no options in the parser that look like negative numbers:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'PROG'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-x'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'?'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="c1"># no negative number options, so -1 is a positional argument</span> | |
| <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">'-x'</span><span class="p">,</span> <span class="s1">'-1'</span><span class="p">])</span> | |
| <span class="go">Namespace(foo=None, x='-1')</span> | |
| <span class="gp">>>> </span><span class="c1"># no negative number options, so -1 and -5 are positional arguments</span> | |
| <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">'-x'</span><span class="p">,</span> <span class="s1">'-1'</span><span class="p">,</span> <span class="s1">'-5'</span><span class="p">])</span> | |
| <span class="go">Namespace(foo='-5', x='-1')</span> | |
| <span class="gp">>>> </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">'PROG'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-1'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">'one'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'?'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="c1"># negative number options present, so -1 is an option</span> | |
| <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">'-1'</span><span class="p">,</span> <span class="s1">'X'</span><span class="p">])</span> | |
| <span class="go">Namespace(foo=None, one='X')</span> | |
| <span class="gp">>>> </span><span class="c1"># negative number options present, so -2 is an option</span> | |
| <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">'-2'</span><span class="p">])</span> | |
| <span class="go">usage: PROG [-h] [-1 ONE] [foo]</span> | |
| <span class="go">PROG: error: no such option: -2</span> | |
| <span class="gp">>>> </span><span class="c1"># negative number options present, so both -1s are options</span> | |
| <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">'-1'</span><span class="p">,</span> <span class="s1">'-1'</span><span class="p">])</span> | |
| <span class="go">usage: PROG [-h] [-1 ONE] [foo]</span> | |
| <span class="go">PROG: error: argument -1: expected one argument</span> | |
| </pre></div> | |
| </div> | |
| <p>If you have positional arguments that must begin with <code class="docutils literal notranslate"><span class="pre">-</span></code> and don’t look | |
| like negative numbers, you can insert the pseudo-argument <code class="docutils literal notranslate"><span class="pre">'--'</span></code> which tells | |
| <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 | |
| argument:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><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">'--'</span><span class="p">,</span> <span class="s1">'-f'</span><span class="p">])</span> | |
| <span class="go">Namespace(foo='-f', one=None)</span> | |
| </pre></div> | |
| </div> | |
| <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> | |
| for more details.</p> | |
| </section> | |
| <section id="argument-abbreviations-prefix-matching"> | |
| <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> | |
| <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> | |
| allows long options to be abbreviated to a prefix, if the abbreviation is | |
| unambiguous (the prefix matches a unique option):</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'PROG'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-bacon'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-badger'</span><span class="p">)</span> | |
| <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">'-bac MMM'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span> | |
| <span class="go">Namespace(bacon='MMM', badger=None)</span> | |
| <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">'-bad WOOD'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span> | |
| <span class="go">Namespace(bacon=None, badger='WOOD')</span> | |
| <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">'-ba BA'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span> | |
| <span class="go">usage: PROG [-h] [-bacon BACON] [-badger BADGER]</span> | |
| <span class="go">PROG: error: ambiguous option: -ba could match -badger, -bacon</span> | |
| </pre></div> | |
| </div> | |
| <p>An error is produced for arguments that could produce more than one options. | |
| 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> | |
| </section> | |
| <section id="beyond-sys-argv"> | |
| <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> | |
| <p>Sometimes it may 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> parse arguments other than those | |
| 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 | |
| <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 | |
| interactive prompt:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span> | |
| <span class="gp">... </span> <span class="s1">'integers'</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">'int'</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> | |
| <span class="gp">... </span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'+'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'an integer in the range 0..9'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span> | |
| <span class="gp">... </span> <span class="s1">'--sum'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">'accumulate'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_const'</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="nb">sum</span><span class="p">,</span> | |
| <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">'sum the integers (default: find the max)'</span><span class="p">)</span> | |
| <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">'1'</span><span class="p">,</span> <span class="s1">'2'</span><span class="p">,</span> <span class="s1">'3'</span><span class="p">,</span> <span class="s1">'4'</span><span class="p">])</span> | |
| <span class="go">Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])</span> | |
| <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">'1'</span><span class="p">,</span> <span class="s1">'2'</span><span class="p">,</span> <span class="s1">'3'</span><span class="p">,</span> <span class="s1">'4'</span><span class="p">,</span> <span class="s1">'--sum'</span><span class="p">])</span> | |
| <span class="go">Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])</span> | |
| </pre></div> | |
| </div> | |
| </section> | |
| <section id="the-namespace-object"> | |
| <span id="namespace"></span><h3>The Namespace object<a class="headerlink" href="#the-namespace-object" title="Link to this heading">¶</a></h3> | |
| <dl class="py class"> | |
| <dt class="sig sig-object py" id="argparse.Namespace"> | |
| <em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">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> | |
| <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 | |
| an object holding attributes and return it.</p> | |
| <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 | |
| readable string representation. If you prefer to have dict-like view of the | |
| 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> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">)</span> | |
| <span class="gp">>>> </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">'--foo'</span><span class="p">,</span> <span class="s1">'BAR'</span><span class="p">])</span> | |
| <span class="gp">>>> </span><span class="nb">vars</span><span class="p">(</span><span class="n">args</span><span class="p">)</span> | |
| <span class="go">{'foo': 'BAR'}</span> | |
| </pre></div> | |
| </div> | |
| <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 | |
| already existing object, rather than a new <code class="xref py py-class docutils literal notranslate"><span class="pre">Namespace</span></code> object. This can | |
| be achieved by specifying the <code class="docutils literal notranslate"><span class="pre">namespace=</span></code> keyword argument:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span> | |
| <span class="gp">... </span> <span class="k">pass</span> | |
| <span class="gp">...</span> | |
| <span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">C</span><span class="p">()</span> | |
| <span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">)</span> | |
| <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="n">args</span><span class="o">=</span><span class="p">[</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="s1">'BAR'</span><span class="p">],</span> <span class="n">namespace</span><span class="o">=</span><span class="n">c</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">c</span><span class="o">.</span><span class="n">foo</span> | |
| <span class="go">'BAR'</span> | |
| </pre></div> | |
| </div> | |
| </dd></dl> | |
| </section> | |
| </section> | |
| <section id="other-utilities"> | |
| <h2>Other utilities<a class="headerlink" href="#other-utilities" title="Link to this heading">¶</a></h2> | |
| <section id="subcommands"> | |
| <h3>Subcommands<a class="headerlink" href="#subcommands" title="Link to this heading">¶</a></h3> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="argparse.ArgumentParser.add_subparsers"> | |
| <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><em class="sig-param"><span class="n"><span class="pre">*</span></span></em><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">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> | |
| <dd><p>Many programs split up their functionality into a number of subcommands, | |
| for example, the <code class="docutils literal notranslate"><span class="pre">svn</span></code> program can invoke subcommands like <code class="docutils literal notranslate"><span class="pre">svn</span> | |
| <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 | |
| this way can be a particularly good idea when a program performs several | |
| different functions which require different kinds of command-line arguments. | |
| <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 subcommands with the | |
| <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_subparsers()</span></code> method. The <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_subparsers()</span></code> method is normally | |
| called with no arguments and returns a special action object. This object | |
| has a single method, <a class="reference internal" href="#argparse._SubParsersAction.add_parser" title="argparse._SubParsersAction.add_parser"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_parser()</span></code></a>, which takes a | |
| command name and any <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> constructor arguments, and | |
| returns an <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> object that can be modified as usual.</p> | |
| <p>Description of parameters:</p> | |
| <ul class="simple"> | |
| <li><p><em>title</em> - title for the sub-parser group in help output; by default | |
| “subcommands” if description is provided, otherwise uses title for | |
| positional arguments</p></li> | |
| <li><p><em>description</em> - description for the sub-parser group in help output, by | |
| default <code class="docutils literal notranslate"><span class="pre">None</span></code></p></li> | |
| <li><p><em>prog</em> - usage information that will be displayed with subcommand help, | |
| by default the name of the program and any positional arguments before the | |
| subparser argument</p></li> | |
| <li><p><em>parser_class</em> - class which will be used to create sub-parser instances, by | |
| default the class of the current parser (e.g. <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></li> | |
| <li><p><a class="reference internal" href="#action">action</a> - the basic type of action to be taken when this argument is | |
| encountered at the command line</p></li> | |
| <li><p><a class="reference internal" href="#dest">dest</a> - name of the attribute under which subcommand name will be | |
| stored; by default <code class="docutils literal notranslate"><span class="pre">None</span></code> and no value is stored</p></li> | |
| <li><p><a class="reference internal" href="#required">required</a> - Whether or not a subcommand must be provided, by default | |
| <code class="docutils literal notranslate"><span class="pre">False</span></code> (added in 3.7)</p></li> | |
| <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> | |
| <li><p><a class="reference internal" href="#metavar">metavar</a> - string presenting available subcommands in help; by default it | |
| is <code class="docutils literal notranslate"><span class="pre">None</span></code> and presents subcommands in form {cmd1, cmd2, ..}</p></li> | |
| </ul> | |
| <p>Some example usage:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="c1"># create the top-level parser</span> | |
| <span class="gp">>>> </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">'PROG'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_true'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'foo help'</span><span class="p">)</span> | |
| <span class="gp">>>> </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">'subcommand help'</span><span class="p">)</span> | |
| <span class="gp">>>></span> | |
| <span class="gp">>>> </span><span class="c1"># create the parser for the "a" command</span> | |
| <span class="gp">>>> </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">'a'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'a help'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser_a</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</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">'bar help'</span><span class="p">)</span> | |
| <span class="gp">>>></span> | |
| <span class="gp">>>> </span><span class="c1"># create the parser for the "b" command</span> | |
| <span class="gp">>>> </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">'b'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'b help'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser_b</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--baz'</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="p">(</span><span class="s1">'X'</span><span class="p">,</span> <span class="s1">'Y'</span><span class="p">,</span> <span class="s1">'Z'</span><span class="p">),</span> <span class="n">help</span><span class="o">=</span><span class="s1">'baz help'</span><span class="p">)</span> | |
| <span class="gp">>>></span> | |
| <span class="gp">>>> </span><span class="c1"># parse some argument lists</span> | |
| <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">'a'</span><span class="p">,</span> <span class="s1">'12'</span><span class="p">])</span> | |
| <span class="go">Namespace(bar=12, foo=False)</span> | |
| <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">'--foo'</span><span class="p">,</span> <span class="s1">'b'</span><span class="p">,</span> <span class="s1">'--baz'</span><span class="p">,</span> <span class="s1">'Z'</span><span class="p">])</span> | |
| <span class="go">Namespace(baz='Z', foo=True)</span> | |
| </pre></div> | |
| </div> | |
| <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 | |
| attributes for the main parser and the subparser that was selected by the | |
| command line (and not any other subparsers). So in the example above, when | |
| 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 | |
| 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 | |
| <code class="docutils literal notranslate"><span class="pre">baz</span></code> attributes are present.</p> | |
| <p>Similarly, when a help message is requested from a subparser, only the help | |
| for that particular parser will be printed. The help message will not | |
| include parent parser or sibling parser messages. (A help message for each | |
| subparser command, however, can be given by supplying the <code class="docutils literal notranslate"><span class="pre">help=</span></code> argument | |
| to <a class="reference internal" href="#argparse._SubParsersAction.add_parser" title="argparse._SubParsersAction.add_parser"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_parser()</span></code></a> as above.)</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><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">'--help'</span><span class="p">])</span> | |
| <span class="go">usage: PROG [-h] [--foo] {a,b} ...</span> | |
| <span class="go">positional arguments:</span> | |
| <span class="go"> {a,b} subcommand help</span> | |
| <span class="go"> a a help</span> | |
| <span class="go"> b b help</span> | |
| <span class="go">options:</span> | |
| <span class="go"> -h, --help show this help message and exit</span> | |
| <span class="go"> --foo foo help</span> | |
| <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">'a'</span><span class="p">,</span> <span class="s1">'--help'</span><span class="p">])</span> | |
| <span class="go">usage: PROG a [-h] bar</span> | |
| <span class="go">positional arguments:</span> | |
| <span class="go"> bar bar help</span> | |
| <span class="go">options:</span> | |
| <span class="go"> -h, --help show this help message and exit</span> | |
| <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">'b'</span><span class="p">,</span> <span class="s1">'--help'</span><span class="p">])</span> | |
| <span class="go">usage: PROG b [-h] [--baz {X,Y,Z}]</span> | |
| <span class="go">options:</span> | |
| <span class="go"> -h, --help show this help message and exit</span> | |
| <span class="go"> --baz {X,Y,Z} baz help</span> | |
| </pre></div> | |
| </div> | |
| <p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_subparsers()</span></code> 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> | |
| keyword arguments. When either is present, the subparser’s commands will | |
| appear in their own group in the help output. For example:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </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">'subcommands'</span><span class="p">,</span> | |
| <span class="gp">... </span> <span class="n">description</span><span class="o">=</span><span class="s1">'valid subcommands'</span><span class="p">,</span> | |
| <span class="gp">... </span> <span class="n">help</span><span class="o">=</span><span class="s1">'additional help'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">)</span> | |
| <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">'-h'</span><span class="p">])</span> | |
| <span class="go">usage: [-h] {foo,bar} ...</span> | |
| <span class="go">options:</span> | |
| <span class="go"> -h, --help show this help message and exit</span> | |
| <span class="go">subcommands:</span> | |
| <span class="go"> valid subcommands</span> | |
| <span class="go"> {foo,bar} additional help</span> | |
| </pre></div> | |
| </div> | |
| <p>One particularly effective way of handling subcommands is to combine the use | |
| of the <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_subparsers()</span></code> 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 | |
| that each subparser knows which Python function it should execute. For | |
| example:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="c1"># subcommand functions</span> | |
| <span class="gp">>>> </span><span class="k">def</span><span class="w"> </span><span class="nf">foo</span><span class="p">(</span><span class="n">args</span><span class="p">):</span> | |
| <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> | |
| <span class="gp">...</span> | |
| <span class="gp">>>> </span><span class="k">def</span><span class="w"> </span><span class="nf">bar</span><span class="p">(</span><span class="n">args</span><span class="p">):</span> | |
| <span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s1">'((</span><span class="si">%s</span><span class="s1">))'</span> <span class="o">%</span> <span class="n">args</span><span class="o">.</span><span class="n">z</span><span class="p">)</span> | |
| <span class="gp">...</span> | |
| <span class="gp">>>> </span><span class="c1"># create the top-level parser</span> | |
| <span class="gp">>>> </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="gp">>>> </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> | |
| <span class="gp">>>></span> | |
| <span class="gp">>>> </span><span class="c1"># create the parser for the "foo" command</span> | |
| <span class="gp">>>> </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">'foo'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser_foo</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-x'</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> | |
| <span class="gp">>>> </span><span class="n">parser_foo</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'y'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">float</span><span class="p">)</span> | |
| <span class="gp">>>> </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> | |
| <span class="gp">>>></span> | |
| <span class="gp">>>> </span><span class="c1"># create the parser for the "bar" command</span> | |
| <span class="gp">>>> </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">'bar'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser_bar</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'z'</span><span class="p">)</span> | |
| <span class="gp">>>> </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> | |
| <span class="gp">>>></span> | |
| <span class="gp">>>> </span><span class="c1"># parse the args and call whatever function was selected</span> | |
| <span class="gp">>>> </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">'foo 1 -x 2'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span> | |
| <span class="gp">>>> </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> | |
| <span class="go">2.0</span> | |
| <span class="gp">>>></span> | |
| <span class="gp">>>> </span><span class="c1"># parse the args and call whatever function was selected</span> | |
| <span class="gp">>>> </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">'bar XYZYX'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span> | |
| <span class="gp">>>> </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> | |
| <span class="go">((XYZYX))</span> | |
| </pre></div> | |
| </div> | |
| <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 | |
| appropriate function after argument parsing is complete. Associating | |
| functions with actions like this is typically the easiest way to handle the | |
| different actions for each of your subparsers. However, if it is necessary | |
| to check the name of the subparser that was invoked, the <code class="docutils literal notranslate"><span class="pre">dest</span></code> keyword | |
| argument to the <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_subparsers()</span></code> call will work:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </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">'subparser_name'</span><span class="p">)</span> | |
| <span class="gp">>>> </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">'1'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">subparser1</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-x'</span><span class="p">)</span> | |
| <span class="gp">>>> </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">'2'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">subparser2</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'y'</span><span class="p">)</span> | |
| <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">'2'</span><span class="p">,</span> <span class="s1">'frobble'</span><span class="p">])</span> | |
| <span class="go">Namespace(subparser_name='2', y='frobble')</span> | |
| </pre></div> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.7: </span>New <em>required</em> keyword-only parameter.</p> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.14: </span>Subparser’s <em>prog</em> is no longer affected by a custom usage message in | |
| the main parser.</p> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="argparse._SubParsersAction.add_parser"> | |
| <span class="sig-prename descclassname"><span class="pre">_SubParsersAction.</span></span><span class="sig-name descname"><span class="pre">add_parser</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></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">aliases</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">deprecated</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="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._SubParsersAction.add_parser" title="Link to this definition">¶</a></dt> | |
| <dd><p>Create and return 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 for the | |
| subcommand <em>name</em>.</p> | |
| <p>The <em>name</em> argument is the name of the sub-command.</p> | |
| <p>The <em>help</em> argument provides a short description for this sub-command.</p> | |
| <p>The <em>aliases</em> argument allows providing alternative names for this | |
| sub-command. For example:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </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="gp">>>> </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">'checkout'</span><span class="p">,</span> <span class="n">aliases</span><span class="o">=</span><span class="p">[</span><span class="s1">'co'</span><span class="p">])</span> | |
| <span class="gp">>>> </span><span class="n">checkout</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">)</span> | |
| <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">'co'</span><span class="p">,</span> <span class="s1">'bar'</span><span class="p">])</span> | |
| <span class="go">Namespace(foo='bar')</span> | |
| </pre></div> | |
| </div> | |
| <p>The <em>deprecated</em> argument, if <code class="docutils literal notranslate"><span class="pre">True</span></code>, marks the sub-command as | |
| deprecated and will issue a warning when used. For example:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'chicken.py'</span><span class="p">)</span> | |
| <span class="gp">>>> </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="gp">>>> </span><span class="n">fly</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">'fly'</span><span class="p">,</span> <span class="n">deprecated</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span> | |
| <span class="gp">>>> </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">'fly'</span><span class="p">])</span> | |
| <span class="go">chicken.py: warning: command 'fly' is deprecated</span> | |
| <span class="go">Namespace()</span> | |
| </pre></div> | |
| </div> | |
| <p>All other keyword arguments are passed directly to the | |
| <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> constructor.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.13: </span>Added the <em>deprecated</em> parameter.</p> | |
| </div> | |
| </dd></dl> | |
| </section> | |
| <section id="filetype-objects"> | |
| <h3>FileType objects<a class="headerlink" href="#filetype-objects" title="Link to this heading">¶</a></h3> | |
| <dl class="py class"> | |
| <dt class="sig sig-object py" id="argparse.FileType"> | |
| <em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">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> | |
| <dd><p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">FileType</span></code> factory creates objects that can be passed to the type | |
| 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 | |
| <code class="xref py py-class docutils literal notranslate"><span class="pre">FileType</span></code> objects as their type will open command-line arguments as | |
| files with the requested modes, buffer sizes, encodings and error handling | |
| (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> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--raw'</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">'wb'</span><span class="p">,</span> <span class="mi">0</span><span class="p">))</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'out'</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">'w'</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s1">'UTF-8'</span><span class="p">))</span> | |
| <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">'--raw'</span><span class="p">,</span> <span class="s1">'raw.dat'</span><span class="p">,</span> <span class="s1">'file.txt'</span><span class="p">])</span> | |
| <span class="go">Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)</span> | |
| </pre></div> | |
| </div> | |
| <p>FileType objects understand the pseudo-argument <code class="docutils literal notranslate"><span class="pre">'-'</span></code> and automatically | |
| 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 <code class="xref py py-class docutils literal notranslate"><span class="pre">FileType</span></code> objects and | |
| <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 <code class="xref py py-class docutils literal notranslate"><span class="pre">FileType</span></code> objects:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'infile'</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">'r'</span><span class="p">))</span> | |
| <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">'-'</span><span class="p">])</span> | |
| <span class="go">Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)</span> | |
| </pre></div> | |
| </div> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>If one argument uses <em>FileType</em> and then a subsequent argument fails, | |
| an error is reported but the file is not automatically closed. | |
| This can also clobber the output files. | |
| In this case, it would be better to wait until after the parser has | |
| run and then use the <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> | |
| </div> | |
| <div class="versionchanged"> | |
| <p><span class="versionmodified changed">Changed in version 3.4: </span>Added the <em>encodings</em> and <em>errors</em> parameters.</p> | |
| </div> | |
| <div class="deprecated"> | |
| <p><span class="versionmodified deprecated">Deprecated since version 3.14.</span></p> | |
| </div> | |
| </dd></dl> | |
| </section> | |
| <section id="argument-groups"> | |
| <h3>Argument groups<a class="headerlink" href="#argument-groups" title="Link to this heading">¶</a></h3> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="argparse.ArgumentParser.add_argument_group"> | |
| <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=None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">description=None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">*</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">argument_default</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">conflict_handler</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.add_argument_group" title="Link to this definition">¶</a></dt> | |
| <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 | |
| “positional arguments” and “options” when displaying help | |
| messages. When there is a better conceptual grouping of arguments than this | |
| default one, appropriate groups can be created using the | |
| <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument_group()</span></code> method:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'PROG'</span><span class="p">,</span> <span class="n">add_help</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span> | |
| <span class="gp">>>> </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">'group'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'foo help'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'bar help'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span> | |
| <span class="go">usage: PROG [--foo FOO] bar</span> | |
| <span class="go">group:</span> | |
| <span class="go"> bar bar help</span> | |
| <span class="go"> --foo FOO foo help</span> | |
| </pre></div> | |
| </div> | |
| <p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument_group()</span></code> method returns an argument group object which | |
| 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 | |
| <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 | |
| treats it just like a normal argument, but displays the argument in a | |
| separate group for help messages. The <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument_group()</span></code> method | |
| accepts <em>title</em> and <em>description</em> arguments which can be used to | |
| customize this display:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'PROG'</span><span class="p">,</span> <span class="n">add_help</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span> | |
| <span class="gp">>>> </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">'group1'</span><span class="p">,</span> <span class="s1">'group1 description'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">group1</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'foo help'</span><span class="p">)</span> | |
| <span class="gp">>>> </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">'group2'</span><span class="p">,</span> <span class="s1">'group2 description'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">group2</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--bar'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'bar help'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span> | |
| <span class="go">usage: PROG [--bar BAR] foo</span> | |
| <span class="go">group1:</span> | |
| <span class="go"> group1 description</span> | |
| <span class="go"> foo foo help</span> | |
| <span class="go">group2:</span> | |
| <span class="go"> group2 description</span> | |
| <span class="go"> --bar BAR bar help</span> | |
| </pre></div> | |
| </div> | |
| <p>The optional, keyword-only parameters <a class="reference internal" href="#argument-default">argument_default</a> and <a class="reference internal" href="#conflict-handler">conflict_handler</a> | |
| allow for finer-grained control of the behavior of the argument group. These | |
| parameters have the same meaning as in 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, | |
| but apply specifically to the argument group rather than the entire parser.</p> | |
| <p>Note that any arguments not in your user-defined groups will end up back | |
| in the usual “positional arguments” and “optional arguments” sections.</p> | |
| <div class="deprecated-removed"> | |
| <p><span class="versionmodified removed">Deprecated since version 3.11, removed in version 3.14: </span>Calling <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument_group()</span></code> on an argument group now raises an | |
| exception. This nesting was never supported, often failed to work | |
| correctly, and was unintentionally exposed through inheritance.</p> | |
| </div> | |
| <div class="deprecated"> | |
| <p><span class="versionmodified deprecated">Deprecated since version 3.14: </span>Passing <a class="reference internal" href="#prefix-chars">prefix_chars</a> to <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument_group()</span></code> | |
| is now deprecated.</p> | |
| </div> | |
| </dd></dl> | |
| </section> | |
| <section id="mutual-exclusion"> | |
| <h3>Mutual exclusion<a class="headerlink" href="#mutual-exclusion" title="Link to this heading">¶</a></h3> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="argparse.ArgumentParser.add_mutually_exclusive_group"> | |
| <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> | |
| <dd><p>Create a mutually exclusive group. <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> will make sure that only | |
| one of the arguments in the mutually exclusive group was present on the | |
| command line:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'PROG'</span><span class="p">)</span> | |
| <span class="gp">>>> </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="gp">>>> </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_true'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--bar'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_false'</span><span class="p">)</span> | |
| <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">'--foo'</span><span class="p">])</span> | |
| <span class="go">Namespace(bar=True, foo=True)</span> | |
| <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">'--bar'</span><span class="p">])</span> | |
| <span class="go">Namespace(bar=False, foo=False)</span> | |
| <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">'--foo'</span><span class="p">,</span> <span class="s1">'--bar'</span><span class="p">])</span> | |
| <span class="go">usage: PROG [-h] [--foo | --bar]</span> | |
| <span class="go">PROG: error: argument --bar: not allowed with argument --foo</span> | |
| </pre></div> | |
| </div> | |
| <p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_mutually_exclusive_group()</span></code> method also accepts a <em>required</em> | |
| argument, to indicate that at least one of the mutually exclusive arguments | |
| is required:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'PROG'</span><span class="p">)</span> | |
| <span class="gp">>>> </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> | |
| <span class="gp">>>> </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_true'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--bar'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_false'</span><span class="p">)</span> | |
| <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="go">usage: PROG [-h] (--foo | --bar)</span> | |
| <span class="go">PROG: error: one of the arguments --foo --bar is required</span> | |
| </pre></div> | |
| </div> | |
| <p>Note that currently mutually exclusive argument groups do not support the | |
| <em>title</em> and <em>description</em> arguments of | |
| <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 | |
| group can be added to an argument group that has a title and description. | |
| For example:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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">'PROG'</span><span class="p">)</span> | |
| <span class="gp">>>> </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">'Group title'</span><span class="p">,</span> <span class="s1">'Group description'</span><span class="p">)</span> | |
| <span class="gp">>>> </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> | |
| <span class="gp">>>> </span><span class="n">exclusive_group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'foo help'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">exclusive_group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--bar'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'bar help'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span> | |
| <span class="go">usage: PROG [-h] (--foo FOO | --bar BAR)</span> | |
| <span class="go">options:</span> | |
| <span class="go"> -h, --help show this help message and exit</span> | |
| <span class="go">Group title:</span> | |
| <span class="go"> Group description</span> | |
| <span class="go"> --foo FOO foo help</span> | |
| <span class="go"> --bar BAR bar help</span> | |
| </pre></div> | |
| </div> | |
| <div class="deprecated-removed"> | |
| <p><span class="versionmodified removed">Deprecated since version 3.11, removed in version 3.14: </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 <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_mutually_exclusive_group()</span></code> | |
| on a mutually exclusive group now raises an exception. This nesting was | |
| never supported, often failed to work correctly, and was unintentionally | |
| exposed through inheritance.</p> | |
| </div> | |
| </dd></dl> | |
| </section> | |
| <section id="parser-defaults"> | |
| <h3>Parser defaults<a class="headerlink" href="#parser-defaults" title="Link to this heading">¶</a></h3> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="argparse.ArgumentParser.set_defaults"> | |
| <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> | |
| <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> | |
| will be fully determined by inspecting the command-line arguments and the argument | |
| actions. <code class="xref py py-meth docutils literal notranslate"><span class="pre">set_defaults()</span></code> allows some additional | |
| attributes that are determined without any inspection of the command line to | |
| be added:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'foo'</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="gp">>>> </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">'badger'</span><span class="p">)</span> | |
| <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">'736'</span><span class="p">])</span> | |
| <span class="go">Namespace(bar=42, baz='badger', foo=736)</span> | |
| </pre></div> | |
| </div> | |
| <p>Note that defaults can be set at both the parser level using <code class="xref py py-meth docutils literal notranslate"><span class="pre">set_defaults()</span></code> | |
| and at the argument level using <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>. If both are called for the | |
| same argument, the last default set for an argument is used:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">'bar'</span><span class="p">)</span> | |
| <span class="gp">>>> </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">'spam'</span><span class="p">)</span> | |
| <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="go">Namespace(foo='spam')</span> | |
| </pre></div> | |
| </div> | |
| <p>Parser-level defaults can be particularly useful when working with multiple | |
| 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 | |
| example of this type.</p> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="argparse.ArgumentParser.get_default"> | |
| <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> | |
| <dd><p>Get the default value for a namespace attribute, as set by either | |
| <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 | |
| <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> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">'badger'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">get_default</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">)</span> | |
| <span class="go">'badger'</span> | |
| </pre></div> | |
| </div> | |
| </dd></dl> | |
| </section> | |
| <section id="printing-help"> | |
| <h3>Printing help<a class="headerlink" href="#printing-help" title="Link to this heading">¶</a></h3> | |
| <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 | |
| care of formatting and printing any usage or error messages. However, several | |
| formatting methods are available:</p> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="argparse.ArgumentParser.print_usage"> | |
| <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> | |
| <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 | |
| 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 | |
| assumed.</p> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="argparse.ArgumentParser.print_help"> | |
| <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> | |
| <dd><p>Print a help message, including the program usage and 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>. 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 assumed.</p> | |
| </dd></dl> | |
| <p>There are also variants of these methods that simply return a string instead of | |
| printing it:</p> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="argparse.ArgumentParser.format_usage"> | |
| <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> | |
| <dd><p>Return a string containing 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 invoked on the command line.</p> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="argparse.ArgumentParser.format_help"> | |
| <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> | |
| <dd><p>Return a string containing a help message, including the program usage and | |
| 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> | |
| </dd></dl> | |
| </section> | |
| <section id="partial-parsing"> | |
| <h3>Partial parsing<a class="headerlink" href="#partial-parsing" title="Link to this heading">¶</a></h3> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="argparse.ArgumentParser.parse_known_args"> | |
| <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> | |
| <dd><p>Sometimes a script only needs to handle a specific set of command-line | |
| arguments, leaving any unrecognized arguments for another script or program. | |
| In these cases, the <code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_known_args()</span></code> method can be | |
| useful.</p> | |
| <p>This method works similarly to <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>, but it does | |
| not raise an error for extra, unrecognized arguments. Instead, it parses the | |
| known arguments and returns a two item tuple that contains the populated | |
| namespace and the list of any unrecognized arguments.</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_true'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_known_args</span><span class="p">([</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="s1">'--badger'</span><span class="p">,</span> <span class="s1">'BAR'</span><span class="p">,</span> <span class="s1">'spam'</span><span class="p">])</span> | |
| <span class="go">(Namespace(bar='BAR', foo=True), ['--badger', 'spam'])</span> | |
| </pre></div> | |
| </div> | |
| </dd></dl> | |
| <div class="admonition warning"> | |
| <p class="admonition-title">Warning</p> | |
| <p><a class="reference internal" href="#prefix-matching"><span class="std std-ref">Prefix matching</span></a> rules apply to | |
| <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 | |
| a prefix of one of its known options, instead of leaving it in the remaining | |
| arguments list.</p> | |
| </div> | |
| </section> | |
| <section id="customizing-file-parsing"> | |
| <h3>Customizing file parsing<a class="headerlink" href="#customizing-file-parsing" title="Link to this heading">¶</a></h3> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="argparse.ArgumentParser.convert_arg_line_to_args"> | |
| <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> | |
| <dd><p>Arguments that are read from a file (see the <em>fromfile_prefix_chars</em> | |
| 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 | |
| argument per line. <code class="xref py py-meth docutils literal notranslate"><span class="pre">convert_arg_line_to_args()</span></code> can be overridden for | |
| fancier reading.</p> | |
| <p>This method takes a single argument <em>arg_line</em> which is a string read from | |
| the argument file. It returns a list of arguments parsed from this string. | |
| The method is called once per line read from the argument file, in order.</p> | |
| <p>A useful override of this method is one that treats each space-separated word | |
| as an argument. The following example demonstrates how to do this:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </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> | |
| <span class="k">def</span><span class="w"> </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> | |
| <span class="k">return</span> <span class="n">arg_line</span><span class="o">.</span><span class="n">split</span><span class="p">()</span> | |
| </pre></div> | |
| </div> | |
| </dd></dl> | |
| </section> | |
| <section id="exiting-methods"> | |
| <h3>Exiting methods<a class="headerlink" href="#exiting-methods" title="Link to this heading">¶</a></h3> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="argparse.ArgumentParser.exit"> | |
| <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> | |
| <dd><p>This method terminates the program, exiting with the specified <em>status</em> | |
| and, if given, it prints a <em>message</em> to <a class="reference internal" href="sys.html#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stderr</span></code></a> before that. | |
| The user can override this method to handle these steps differently:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </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> | |
| <span class="k">def</span><span class="w"> </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> | |
| <span class="k">if</span> <span class="n">status</span><span class="p">:</span> | |
| <span class="k">raise</span> <span class="ne">Exception</span><span class="p">(</span><span class="sa">f</span><span class="s1">'Exiting because of an error: </span><span class="si">{</span><span class="n">message</span><span class="si">}</span><span class="s1">'</span><span class="p">)</span> | |
| <span class="n">exit</span><span class="p">(</span><span class="n">status</span><span class="p">)</span> | |
| </pre></div> | |
| </div> | |
| </dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="argparse.ArgumentParser.error"> | |
| <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> | |
| <dd><p>This method prints a usage message, including the <em>message</em>, to | |
| <a class="reference internal" href="sys.html#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stderr</span></code></a> and terminates the program with a status code of 2.</p> | |
| </dd></dl> | |
| </section> | |
| <section id="intermixed-parsing"> | |
| <h3>Intermixed parsing<a class="headerlink" href="#intermixed-parsing" title="Link to this heading">¶</a></h3> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="argparse.ArgumentParser.parse_intermixed_args"> | |
| <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> | |
| <dd></dd></dl> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="argparse.ArgumentParser.parse_known_intermixed_args"> | |
| <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> | |
| <dd><p>A number of Unix commands allow the user to intermix optional arguments with | |
| 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> | |
| and <code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_known_intermixed_args()</span></code> methods | |
| support this parsing style.</p> | |
| <p>These parsers do not support all the <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> features, and will raise | |
| exceptions if unsupported features are used. In particular, subparsers, | |
| and mutually exclusive groups that include both | |
| optionals and positionals are not supported.</p> | |
| <p>The following example shows the difference between | |
| <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 | |
| <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> | |
| <span class="pre">'3']</span></code> as unparsed arguments, while the latter collects all the positionals | |
| into <code class="docutils literal notranslate"><span class="pre">rest</span></code>.</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'cmd'</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'rest'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'*'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_known_args</span><span class="p">(</span><span class="s1">'doit 1 --foo bar 2 3'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span> | |
| <span class="go">(Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_intermixed_args</span><span class="p">(</span><span class="s1">'doit 1 --foo bar 2 3'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span> | |
| <span class="go">Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])</span> | |
| </pre></div> | |
| </div> | |
| <p><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_known_intermixed_args()</span></code> returns a two item tuple | |
| containing the populated namespace and the list of remaining argument strings. | |
| <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 | |
| remaining unparsed argument strings.</p> | |
| <div class="versionadded"> | |
| <p><span class="versionmodified added">Added in version 3.7.</span></p> | |
| </div> | |
| </dd></dl> | |
| </section> | |
| <section id="registering-custom-types-or-actions"> | |
| <h3>Registering custom types or actions<a class="headerlink" href="#registering-custom-types-or-actions" title="Link to this heading">¶</a></h3> | |
| <dl class="py method"> | |
| <dt class="sig sig-object py" id="argparse.ArgumentParser.register"> | |
| <span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">register</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">registry_name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">object</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.register" title="Link to this definition">¶</a></dt> | |
| <dd><p>Sometimes it’s desirable to use a custom string in error messages to provide | |
| more user-friendly output. In these cases, <code class="xref py py-meth docutils literal notranslate"><span class="pre">register()</span></code> can be used to | |
| register custom actions or types with a parser and allow you to reference the | |
| type by their registered name instead of their callable name.</p> | |
| <p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">register()</span></code> method accepts three arguments - a <em>registry_name</em>, | |
| specifying the internal registry where the object will be stored (e.g., | |
| <code class="docutils literal notranslate"><span class="pre">action</span></code>, <code class="docutils literal notranslate"><span class="pre">type</span></code>), <em>value</em>, which is the key under which the object will | |
| be registered, and object, the callable to be registered.</p> | |
| <p>The following example shows how to register a custom type with a parser:</p> | |
| <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">argparse</span> | |
| <span class="gp">>>> </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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="s1">'type'</span><span class="p">,</span> <span class="s1">'hexadecimal integer'</span><span class="p">,</span> <span class="k">lambda</span> <span class="n">s</span><span class="p">:</span> <span class="nb">int</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="mi">16</span><span class="p">))</span> | |
| <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s1">'hexadecimal integer'</span><span class="p">)</span> | |
| <span class="go">_StoreAction(option_strings=['--foo'], dest='foo', nargs=None, const=None, default=None, type='hexadecimal integer', choices=None, required=False, help=None, metavar=None, deprecated=False)</span> | |
| <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">'--foo'</span><span class="p">,</span> <span class="s1">'0xFA'</span><span class="p">])</span> | |
| <span class="go">Namespace(foo=250)</span> | |
| <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">'--foo'</span><span class="p">,</span> <span class="s1">'1.2'</span><span class="p">])</span> | |
| <span class="go">usage: PROG [-h] [--foo FOO]</span> | |
| <span class="go">PROG: error: argument --foo: invalid 'hexadecimal integer' value: '1.2'</span> | |
| </pre></div> | |
| </div> | |
| </dd></dl> | |
| </section> | |
| </section> | |
| <section id="exceptions"> | |
| <h2>Exceptions<a class="headerlink" href="#exceptions" title="Link to this heading">¶</a></h2> | |
| <dl class="py exception"> | |
| <dt class="sig sig-object py" id="argparse.ArgumentError"> | |
| <em class="property"><span class="k"><span class="pre">exception</span></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> | |
| <dd><p>An error from creating or using an argument (optional or positional).</p> | |
| <p>The string value of this exception is the message, augmented with | |
| information about the argument that caused it.</p> | |
| </dd></dl> | |
| <dl class="py exception"> | |
| <dt class="sig sig-object py" id="argparse.ArgumentTypeError"> | |
| <em class="property"><span class="k"><span class="pre">exception</span></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> | |
| <dd><p>Raised when something goes wrong converting a command line string to a type.</p> | |
| </dd></dl> | |
| <p class="rubric">Guides and Tutorials</p> | |
| <div class="toctree-wrapper compound"> | |
| <ul> | |
| <li class="toctree-l1"><a class="reference internal" href="../howto/argparse.html">Argparse Tutorial</a></li> | |
| <li class="toctree-l1"><a class="reference internal" href="../howto/argparse-optparse.html">Migrating <code class="docutils literal notranslate"><span class="pre">optparse</span></code> code to <code class="docutils literal notranslate"><span class="pre">argparse</span></code></a></li> | |
| </ul> | |
| </div> | |
| </section> | |
| </section> | |
| <div class="clearer"></div> | |
| </div> | |
| </div> | |
| </div> | |
| <div class="sphinxsidebar" role="navigation" aria-label="Main"> | |
| <div class="sphinxsidebarwrapper"> | |
| <div> | |
| <h3><a href="../contents.html">Table of Contents</a></h3> | |
| <ul> | |
| <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 subcommands</a><ul> | |
| <li><a class="reference internal" href="#argumentparser-objects">ArgumentParser objects</a><ul> | |
| <li><a class="reference internal" href="#prog">prog</a></li> | |
| <li><a class="reference internal" href="#usage">usage</a></li> | |
| <li><a class="reference internal" href="#description">description</a></li> | |
| <li><a class="reference internal" href="#epilog">epilog</a></li> | |
| <li><a class="reference internal" href="#parents">parents</a></li> | |
| <li><a class="reference internal" href="#formatter-class">formatter_class</a></li> | |
| <li><a class="reference internal" href="#prefix-chars">prefix_chars</a></li> | |
| <li><a class="reference internal" href="#fromfile-prefix-chars">fromfile_prefix_chars</a></li> | |
| <li><a class="reference internal" href="#argument-default">argument_default</a></li> | |
| <li><a class="reference internal" href="#allow-abbrev">allow_abbrev</a></li> | |
| <li><a class="reference internal" href="#conflict-handler">conflict_handler</a></li> | |
| <li><a class="reference internal" href="#add-help">add_help</a></li> | |
| <li><a class="reference internal" href="#exit-on-error">exit_on_error</a></li> | |
| <li><a class="reference internal" href="#suggest-on-error">suggest_on_error</a></li> | |
| <li><a class="reference internal" href="#color">color</a></li> | |
| </ul> | |
| </li> | |
| <li><a class="reference internal" href="#the-add-argument-method">The add_argument() method</a><ul> | |
| <li><a class="reference internal" href="#name-or-flags">name or flags</a></li> | |
| <li><a class="reference internal" href="#action">action</a></li> | |
| <li><a class="reference internal" href="#nargs">nargs</a></li> | |
| <li><a class="reference internal" href="#const">const</a></li> | |
| <li><a class="reference internal" href="#default">default</a></li> | |
| <li><a class="reference internal" href="#type">type</a></li> | |
| <li><a class="reference internal" href="#choices">choices</a></li> | |
| <li><a class="reference internal" href="#required">required</a></li> | |
| <li><a class="reference internal" href="#help">help</a></li> | |
| <li><a class="reference internal" href="#metavar">metavar</a></li> | |
| <li><a class="reference internal" href="#dest">dest</a></li> | |
| <li><a class="reference internal" href="#deprecated">deprecated</a></li> | |
| <li><a class="reference internal" href="#action-classes">Action classes</a></li> | |
| </ul> | |
| </li> | |
| <li><a class="reference internal" href="#the-parse-args-method">The parse_args() method</a><ul> | |
| <li><a class="reference internal" href="#option-value-syntax">Option value syntax</a></li> | |
| <li><a class="reference internal" href="#invalid-arguments">Invalid arguments</a></li> | |
| <li><a class="reference internal" href="#arguments-containing">Arguments containing <code class="docutils literal notranslate"><span class="pre">-</span></code></a></li> | |
| <li><a class="reference internal" href="#argument-abbreviations-prefix-matching">Argument abbreviations (prefix matching)</a></li> | |
| <li><a class="reference internal" href="#beyond-sys-argv">Beyond <code class="docutils literal notranslate"><span class="pre">sys.argv</span></code></a></li> | |
| <li><a class="reference internal" href="#the-namespace-object">The Namespace object</a></li> | |
| </ul> | |
| </li> | |
| <li><a class="reference internal" href="#other-utilities">Other utilities</a><ul> | |
| <li><a class="reference internal" href="#subcommands">Subcommands</a></li> | |
| <li><a class="reference internal" href="#filetype-objects">FileType objects</a></li> | |
| <li><a class="reference internal" href="#argument-groups">Argument groups</a></li> | |
| <li><a class="reference internal" href="#mutual-exclusion">Mutual exclusion</a></li> | |
| <li><a class="reference internal" href="#parser-defaults">Parser defaults</a></li> | |
| <li><a class="reference internal" href="#printing-help">Printing help</a></li> | |
| <li><a class="reference internal" href="#partial-parsing">Partial parsing</a></li> | |
| <li><a class="reference internal" href="#customizing-file-parsing">Customizing file parsing</a></li> | |
| <li><a class="reference internal" href="#exiting-methods">Exiting methods</a></li> | |
| <li><a class="reference internal" href="#intermixed-parsing">Intermixed parsing</a></li> | |
| <li><a class="reference internal" href="#registering-custom-types-or-actions">Registering custom types or actions</a></li> | |
| </ul> | |
| </li> | |
| <li><a class="reference internal" href="#exceptions">Exceptions</a></li> | |
| </ul> | |
| </li> | |
| </ul> | |
| </div> | |
| <div> | |
| <h4>Previous topic</h4> | |
| <p class="topless"><a href="cmdlinelibs.html" | |
| title="previous chapter">Command-line interface libraries</a></p> | |
| </div> | |
| <div> | |
| <h4>Next topic</h4> | |
| <p class="topless"><a href="../howto/argparse.html" | |
| title="next chapter">Argparse Tutorial</a></p> | |
| </div> | |
| <script> | |
| document.addEventListener('DOMContentLoaded', () => { | |
| const title = document.querySelector('meta[property="og:title"]').content; | |
| const elements = document.querySelectorAll('.improvepage'); | |
| const pageurl = window.location.href.split('?')[0]; | |
| elements.forEach(element => { | |
| const url = new URL(element.href.split('?')[0].replace("-nojs", "")); | |
| url.searchParams.set('pagetitle', title); | |
| url.searchParams.set('pageurl', pageurl); | |
| url.searchParams.set('pagesource', "library/argparse.rst"); | |
| element.href = url.toString(); | |
| }); | |
| }); | |
| </script> | |
| <div role="note" aria-label="source link"> | |
| <h3>This page</h3> | |
| <ul class="this-page-menu"> | |
| <li><a href="../bugs.html">Report a bug</a></li> | |
| <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li> | |
| <li> | |
| <a href="https://github.com/python/cpython/blob/main/Doc/library/argparse.rst?plain=1" | |
| rel="nofollow">Show source | |
| </a> | |
| </li> | |
| </ul> | |
| </div> | |
| </div> | |
| <div id="sidebarbutton" title="Collapse sidebar"> | |
| <span>«</span> | |
| </div> | |
| </div> | |
| <div class="clearer"></div> | |
| </div> | |
| <div class="related" role="navigation" aria-label="Related"> | |
| <h3>Navigation</h3> | |
| <ul> | |
| <li class="right" style="margin-right: 10px"> | |
| <a href="../genindex.html" title="General Index" | |
| >index</a></li> | |
| <li class="right" > | |
| <a href="../py-modindex.html" title="Python Module Index" | |
| >modules</a> |</li> | |
| <li class="right" > | |
| <a href="../howto/argparse.html" title="Argparse Tutorial" | |
| >next</a> |</li> | |
| <li class="right" > | |
| <a href="cmdlinelibs.html" title="Command-line interface libraries" | |
| >previous</a> |</li> | |
| <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li> | |
| <li><a href="https://www.python.org/">Python</a> »</li> | |
| <li class="switchers"> | |
| <div class="language_switcher_placeholder"></div> | |
| <div class="version_switcher_placeholder"></div> | |
| </li> | |
| <li> | |
| </li> | |
| <li id="cpython-language-and-version"> | |
| <a href="../index.html">3.15.0a6 Documentation</a> » | |
| </li> | |
| <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li> | |
| <li class="nav-item nav-item-2"><a href="cmdlinelibs.html" >Command-line interface libraries</a> »</li> | |
| <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 subcommands</a></li> | |
| <li class="right"> | |
| <div class="inline-search" role="search"> | |
| <form class="inline-search" action="../search.html" method="get"> | |
| <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box"> | |
| <input type="submit" value="Go"> | |
| </form> | |
| </div> | |
| | | |
| </li> | |
| <li class="right"> | |
| <label class="theme-selector-label"> | |
| Theme | |
| <select class="theme-selector" oninput="activateTheme(this.value)"> | |
| <option value="auto" selected>Auto</option> | |
| <option value="light">Light</option> | |
| <option value="dark">Dark</option> | |
| </select> | |
| </label> |</li> | |
| </ul> | |
| </div> | |
| <div class="footer"> | |
| © <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation. | |
| <br> | |
| This page is licensed under the Python Software Foundation License Version 2. | |
| <br> | |
| Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License. | |
| <br> | |
| See <a href="/license.html">History and License</a> for more information.<br> | |
| <br> | |
| The Python Software Foundation is a non-profit corporation. | |
| <a href="https://www.python.org/psf/donations/">Please donate.</a> | |
| <br> | |
| <br> | |
| Last updated on Mar 10, 2026 (08:58 UTC). | |
| <a href="/bugs.html">Found a bug</a>? | |
| <br> | |
| Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3. | |
| </div> | |
| </body> | |
| </html> |