mirror of
https://github.com/bunny-lab-io/Borealis.git
synced 2025-11-03 19:41:57 -07:00
2498 lines
304 KiB
HTML
2498 lines
304 KiB
HTML
<!DOCTYPE html>
|
||
|
||
<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" content="https://docs.python.org/3/_static/og-image.png" />
|
||
<meta property="og:image:alt" content="Python documentation" />
|
||
<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 property="og:image:width" content="200">
|
||
<meta property="og:image:height" content="200">
|
||
<meta name="theme-color" content="#3776ab">
|
||
|
||
<title>argparse — Parser for command-line options, arguments and subcommands — Python 3.13.3 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/pydoctheme.css?v=23252803" />
|
||
<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=5d57ca2d"></script>
|
||
<script src="../_static/doctools.js?v=9bcbadda"></script>
|
||
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
|
||
|
||
<script src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.13.3 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" />
|
||
|
||
<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>
|
||
</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="#sub-commands">Sub-commands</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>
|
||
<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 href="https://github.com/python/cpython/blob/main/Doc/library/argparse.rst"
|
||
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.13.3 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/3.13/Lib/argparse.py">Lib/argparse.py</a></p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>While <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code></a> is 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><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Create a new <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> object. All parameters should be passed
|
||
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:
|
||
<code class="docutils literal notranslate"><span class="pre">os.path.basename(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 <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> objects whose arguments should
|
||
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>
|
||
</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>
|
||
</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> 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>
|
||
</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>
|
||
</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 <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, collects all the positional and optional actions from them, and adds
|
||
these actions to the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> object being constructed:</p>
|
||
<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 by default be one per line (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>
|
||
<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, <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> objects raise an exception if an
|
||
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>
|
||
<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>
|
||
</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
|
||
<a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> must therefore be either a series of
|
||
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>
|
||
</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> used for storing the values <code class="docutils literal notranslate"><span class="pre">True</span></code> and <code class="docutils literal notranslate"><span class="pre">False</span></code>
|
||
respectively. In addition, they create 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> respectively:</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 stores a list, and appends each argument value to the
|
||
list. It is useful to allow an option to be specified multiple times.
|
||
If the default value is non-empty, the default elements will be present
|
||
in the parsed value for the option, with any values from the
|
||
command line appended after those default values. 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="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=['1', '2'])</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'append_const'</span></code> - This stores a list, and appends the value specified by
|
||
the <a class="reference internal" href="#const">const</a> keyword argument to the list; note that the <a class="reference internal" href="#const">const</a> keyword
|
||
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 stores a list and appends each item from the multi-value
|
||
argument list to it.
|
||
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 a keyword 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>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> or <code class="docutils literal notranslate"><span class="pre">'extend'</span></code>) can be used with positional arguments.</p>
|
||
<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>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 or
|
||
other object that implements the same interface. The <code class="xref py py-class docutils literal notranslate"><span class="pre">BooleanOptionalAction</span></code>
|
||
is available in <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> and adds support for boolean actions such as
|
||
<code class="docutils literal notranslate"><span class="pre">--foo</span></code> and <code class="docutils literal notranslate"><span class="pre">--no-foo</span></code>:</p>
|
||
<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>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.9.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<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="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">default</span><span class="o">=</span><span class="n">sys</span><span class="o">.</span><span class="n">stdin</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="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="gp">... </span> <span class="n">default</span><span class="o">=</span><span class="n">sys</span><span class="o">.</span><span class="n">stdout</span><span class="p">)</span>
|
||
<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=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,</span>
|
||
<span class="go"> outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>)</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=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>,</span>
|
||
<span class="go"> outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)</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 args 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 <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a>, it will
|
||
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 of <code class="docutils literal notranslate"><span class="pre">const</span></code> will be assumed to
|
||
be <code class="docutils literal notranslate"><span class="pre">None</span></code> instead. See the <a class="reference internal" href="#nargs">nargs</a> description for examples.</p></li>
|
||
</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">'dest_file'</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">'latin-1'</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 <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> 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>Note that inclusion in the <em>choices</em> sequence is checked after any <a class="reference internal" href="#type">type</a>
|
||
conversions have been performed, so the type of the objects in the <em>choices</em>
|
||
sequence should match the <a class="reference internal" href="#type">type</a> specified.</p>
|
||
<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>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
|
||
<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">'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 long option string and stripping away the initial <code class="docutils literal notranslate"><span class="pre">--</span></code>
|
||
string. 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">'-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 -x 2'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
|
||
<span class="go">Namespace(foo_bar='1', x='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="s1">'--foo 1 -y 2'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
|
||
<span class="go">Namespace(foo_bar='1', 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>
|
||
</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>
|
||
|
||
</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 <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> method is cautious here: positional
|
||
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 <a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate"><span class="pre">Namespace</span></code></a> object. This can
|
||
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="sub-commands">
|
||
<h3>Sub-commands<a class="headerlink" href="#sub-commands" 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, <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_parser()</span></code>, 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 sub-command 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 sub-command 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 <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_parser()</span></code> 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 <a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_subparsers()</span></code></a> method also supports <code class="docutils literal notranslate"><span class="pre">title</span></code> and <code class="docutils literal notranslate"><span class="pre">description</span></code>
|
||
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>Furthermore, <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_parser()</span></code> supports an additional
|
||
<em>aliases</em> argument,
|
||
which allows multiple strings to refer to the same subparser. This example,
|
||
like <code class="docutils literal notranslate"><span class="pre">svn</span></code>, aliases <code class="docutils literal notranslate"><span class="pre">co</span></code> as a shorthand for <code class="docutils literal notranslate"><span class="pre">checkout</span></code>:</p>
|
||
<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><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_parser()</span></code> supports also an additional
|
||
<em>deprecated</em> argument, which allows to deprecate the subparser.</p>
|
||
<div class="doctest highlight-default 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">'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">run</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">'run'</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">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>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.13.</span></p>
|
||
</div>
|
||
<p>One particularly effective way of handling subcommands is to combine the use
|
||
of the <a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_subparsers()</span></code></a> method with calls to <a class="reference internal" href="#argparse.ArgumentParser.set_defaults" title="argparse.ArgumentParser.set_defaults"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_defaults()</span></code></a> so
|
||
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 <a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_subparsers()</span></code></a> call will work:</p>
|
||
<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>
|
||
</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 <a class="reference internal" href="#argparse.FileType" title="argparse.FileType"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileType</span></code></a> factory creates objects that can be passed to the type
|
||
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
|
||
<a class="reference internal" href="#argparse.FileType" title="argparse.FileType"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileType</span></code></a> objects as their type will open command-line arguments as
|
||
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 <a class="reference internal" href="#argparse.FileType" title="argparse.FileType"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileType</span></code></a> objects and
|
||
<a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdout</span></code></a> for writable <a class="reference internal" href="#argparse.FileType" title="argparse.FileType"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileType</span></code></a> objects:</p>
|
||
<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="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.4: </span>Added the <em>encodings</em> and <em>errors</em> parameters.</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 <a class="reference internal" href="#argparse.ArgumentParser.add_argument_group" title="argparse.ArgumentParser.add_argument_group"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument_group()</span></code></a> method returns an argument group object which
|
||
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="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.11: </span>Calling <a class="reference internal" href="#argparse.ArgumentParser.add_argument_group" title="argparse.ArgumentParser.add_argument_group"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument_group()</span></code></a> on an argument group is deprecated.
|
||
This feature was never supported and does not always work correctly.
|
||
The function exists on the API by accident through inheritance and
|
||
will be removed in the future.</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 <a class="reference internal" href="#argparse.ArgumentParser.add_mutually_exclusive_group" title="argparse.ArgumentParser.add_mutually_exclusive_group"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_mutually_exclusive_group()</span></code></a> method also accepts a <em>required</em>
|
||
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="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.11: </span>Calling <a class="reference internal" href="#argparse.ArgumentParser.add_argument_group" title="argparse.ArgumentParser.add_argument_group"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument_group()</span></code></a> or <a class="reference internal" href="#argparse.ArgumentParser.add_mutually_exclusive_group" title="argparse.ArgumentParser.add_mutually_exclusive_group"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_mutually_exclusive_group()</span></code></a>
|
||
on a mutually exclusive group is deprecated. These features were never
|
||
supported and do not always work correctly. The functions exist on the
|
||
API by accident through inheritance and will be removed in the future.</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. <a class="reference internal" href="#argparse.ArgumentParser.set_defaults" title="argparse.ArgumentParser.set_defaults"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_defaults()</span></code></a> allows some additional
|
||
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 parser-level defaults always override argument-level defaults:</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 may only parse a few of the command-line arguments, passing
|
||
the remaining arguments on to another script or program. In these cases, the
|
||
<a class="reference internal" href="#argparse.ArgumentParser.parse_known_args" title="argparse.ArgumentParser.parse_known_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_known_args()</span></code></a> method can be useful. It works much like
|
||
<a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> except that it does not produce an error when
|
||
extra arguments are present. Instead, it returns a two item tuple containing
|
||
the populated namespace and the list of remaining argument 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="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. <a class="reference internal" href="#argparse.ArgumentParser.convert_arg_line_to_args" title="argparse.ArgumentParser.convert_arg_line_to_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">convert_arg_line_to_args()</span></code></a> can be overridden for
|
||
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 <a class="reference internal" href="#argparse.ArgumentParser.parse_known_intermixed_args" title="argparse.ArgumentParser.parse_known_intermixed_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_known_intermixed_args()</span></code></a> methods
|
||
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><a class="reference internal" href="#argparse.ArgumentParser.parse_known_intermixed_args" title="argparse.ArgumentParser.parse_known_intermixed_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_known_intermixed_args()</span></code></a> returns a two item tuple
|
||
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>
|
||
</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="#sub-commands">Sub-commands</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>
|
||
<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 href="https://github.com/python/cpython/blob/main/Doc/library/argparse.rst"
|
||
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.13.3 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-2025, 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 Apr 08, 2025 (14:33 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> |