2240 lines
274 KiB
HTML
2240 lines
274 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>argparse — Parser for command-line options, arguments and sub-commands — Python 3.7.4 documentation</title>
|
||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script type="text/javascript" src="../_static/jquery.js"></script>
|
||
<script type="text/javascript" src="../_static/underscore.js"></script>
|
||
<script type="text/javascript" src="../_static/doctools.js"></script>
|
||
<script type="text/javascript" src="../_static/language_data.js"></script>
|
||
|
||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.7.4 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="getopt — C-style parser for command line options" href="getopt.html" />
|
||
<link rel="prev" title="time — Time access and conversions" href="time.html" />
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/argparse.html" />
|
||
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
|
||
|
||
</head><body>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<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="getopt.html" title="getopt — C-style parser for command line options"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="time.html" title="time — Time access and conversions"
|
||
accesskey="P">previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">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="allos.html" accesskey="U">Generic Operating System Services</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<div class="section" id="module-argparse">
|
||
<span id="argparse-parser-for-command-line-options-arguments-and-sub-commands"></span><h1><a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code></a> — Parser for command-line options, arguments and sub-commands<a class="headerlink" href="#module-argparse" title="Permalink to this headline">¶</a></h1>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.7/Lib/argparse.py">Lib/argparse.py</a></p>
|
||
<hr class="docutils" />
|
||
<div 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#id1"><span class="std std-ref">argparse tutorial</span></a>.</p>
|
||
</div>
|
||
<p>The <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code></a> module makes it easy to write user-friendly command-line
|
||
interfaces. The program defines what arguments it requires, and <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code></a>
|
||
will figure out how to parse those out of <a class="reference internal" href="sys.html#sys.argv" title="sys.argv"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.argv</span></code></a>. The <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code></a>
|
||
module also automatically generates help and usage messages and issues errors
|
||
when users give the program invalid arguments.</p>
|
||
<div class="section" id="example">
|
||
<h2>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2>
|
||
<p>The following code is a Python program that takes a list of integers and
|
||
produces either the sum or the max:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">argparse</span>
|
||
|
||
<span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">description</span><span class="o">=</span><span class="s1">'Process some integers.'</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'integers'</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">'N'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'+'</span><span class="p">,</span>
|
||
<span class="n">help</span><span class="o">=</span><span class="s1">'an integer for the accumulator'</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">'--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="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="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">accumulate</span><span class="p">(</span><span class="n">args</span><span class="o">.</span><span class="n">integers</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Assuming the Python code above is saved into a file called <code class="docutils literal notranslate"><span class="pre">prog.py</span></code>, it can
|
||
be run at the command line and provides useful help messages:</p>
|
||
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> python prog.py -h
|
||
<span class="go">usage: prog.py [-h] [--sum] N [N ...]</span>
|
||
|
||
<span class="go">Process some integers.</span>
|
||
|
||
<span class="go">positional arguments:</span>
|
||
<span class="go"> N an integer for the accumulator</span>
|
||
|
||
<span class="go">optional arguments:</span>
|
||
<span class="go"> -h, --help show this help message and exit</span>
|
||
<span class="go"> --sum sum the integers (default: find the max)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>When run with the appropriate arguments, it prints either the sum or the max of
|
||
the command-line integers:</p>
|
||
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> python prog.py <span class="m">1</span> <span class="m">2</span> <span class="m">3</span> <span class="m">4</span>
|
||
<span class="go">4</span>
|
||
|
||
<span class="gp">$</span> python prog.py <span class="m">1</span> <span class="m">2</span> <span class="m">3</span> <span class="m">4</span> --sum
|
||
<span class="go">10</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>If invalid arguments are passed in, it will issue an error:</p>
|
||
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> python prog.py a b c
|
||
<span class="go">usage: prog.py [-h] [--sum] N [N ...]</span>
|
||
<span class="go">prog.py: error: argument N: invalid int value: 'a'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The following sections walk you through this example.</p>
|
||
<div class="section" id="creating-a-parser">
|
||
<h3>Creating a parser<a class="headerlink" href="#creating-a-parser" title="Permalink to this headline">¶</a></h3>
|
||
<p>The first step in using the <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code></a> is creating an
|
||
<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> object:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">description</span><span class="o">=</span><span class="s1">'Process some integers.'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> object will hold all the information necessary to
|
||
parse the command line into Python data types.</p>
|
||
</div>
|
||
<div class="section" id="adding-arguments">
|
||
<h3>Adding arguments<a class="headerlink" href="#adding-arguments" title="Permalink to this headline">¶</a></h3>
|
||
<p>Filling an <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> with information about program arguments is
|
||
done by making calls to the <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> method.
|
||
Generally, these calls tell the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> how to take the strings
|
||
on the command line and turn them into objects. This information is stored and
|
||
used when <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> is called. For example:</p>
|
||
<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">'integers'</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">'N'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'+'</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="n">help</span><span class="o">=</span><span class="s1">'an integer for the accumulator'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</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="gp">... </span> <span class="n">const</span><span class="o">=</span><span class="nb">sum</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="nb">max</span><span class="p">,</span>
|
||
<span class="gp">... </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>
|
||
</pre></div>
|
||
</div>
|
||
<p>Later, calling <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> will return an object with
|
||
two attributes, <code class="docutils literal notranslate"><span class="pre">integers</span></code> and <code class="docutils literal notranslate"><span class="pre">accumulate</span></code>. The <code class="docutils literal notranslate"><span class="pre">integers</span></code> attribute
|
||
will be a list of one or more ints, and the <code class="docutils literal notranslate"><span class="pre">accumulate</span></code> attribute will be
|
||
either the <a class="reference internal" href="functions.html#sum" title="sum"><code class="xref py py-func docutils literal notranslate"><span class="pre">sum()</span></code></a> function, if <code class="docutils literal notranslate"><span class="pre">--sum</span></code> was specified at the command line,
|
||
or the <a class="reference internal" href="functions.html#max" title="max"><code class="xref py py-func docutils literal notranslate"><span class="pre">max()</span></code></a> function if it was not.</p>
|
||
</div>
|
||
<div class="section" id="parsing-arguments">
|
||
<h3>Parsing arguments<a class="headerlink" href="#parsing-arguments" title="Permalink to this headline">¶</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> parses arguments through 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. This will inspect the command line,
|
||
convert each argument to the appropriate type and then invoke the appropriate action.
|
||
In most cases, this means a simple <a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate"><span class="pre">Namespace</span></code></a> object will be built up from
|
||
attributes parsed out of 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">parse_args</span><span class="p">([</span><span class="s1">'--sum'</span><span class="p">,</span> <span class="s1">'7'</span><span class="p">,</span> <span class="s1">'-1'</span><span class="p">,</span> <span class="s1">'42'</span><span class="p">])</span>
|
||
<span class="go">Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>In a script, <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> will typically be called with no
|
||
arguments, and the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> will automatically determine the
|
||
command-line arguments from <a class="reference internal" href="sys.html#sys.argv" title="sys.argv"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.argv</span></code></a>.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="argumentparser-objects">
|
||
<h2>ArgumentParser objects<a class="headerlink" href="#argumentparser-objects" title="Permalink to this headline">¶</a></h2>
|
||
<dl class="class">
|
||
<dt id="argparse.ArgumentParser">
|
||
<em class="property">class </em><code class="descclassname">argparse.</code><code class="descname">ArgumentParser</code><span class="sig-paren">(</span><em>prog=None</em>, <em>usage=None</em>, <em>description=None</em>, <em>epilog=None</em>, <em>parents=[]</em>, <em>formatter_class=argparse.HelpFormatter</em>, <em>prefix_chars='-'</em>, <em>fromfile_prefix_chars=None</em>, <em>argument_default=None</em>, <em>conflict_handler='error'</em>, <em>add_help=True</em>, <em>allow_abbrev=True</em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser" title="Permalink 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">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 (default: none)</p></li>
|
||
<li><p><a class="reference internal" href="#epilog">epilog</a> - Text to display after the argument help (default: none)</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>
|
||
</ul>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span><em>allow_abbrev</em> parameter was added.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<p>The following sections describe how each of these are used.</p>
|
||
<div class="section" id="prog">
|
||
<h3>prog<a class="headerlink" href="#prog" title="Permalink to this headline">¶</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 use <code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code> to determine
|
||
how to display the name of the program in help messages. This default is almost
|
||
always desirable because it will make the help messages match how the program was
|
||
invoked on the command line. For example, consider a file named
|
||
<code class="docutils literal notranslate"><span class="pre">myprogram.py</span></code> with the following code:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">argparse</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">'--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="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>
|
||
</pre></div>
|
||
</div>
|
||
<p>The help for this program will display <code class="docutils literal notranslate"><span class="pre">myprogram.py</span></code> as the program name
|
||
(regardless of where the program was invoked from):</p>
|
||
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> python myprogram.py --help
|
||
<span class="go">usage: myprogram.py [-h] [--foo FOO]</span>
|
||
|
||
<span class="go">optional arguments:</span>
|
||
<span class="go"> -h, --help show this help message and exit</span>
|
||
<span class="go"> --foo FOO foo help</span>
|
||
<span class="gp">$</span> <span class="nb">cd</span> ..
|
||
<span class="gp">$</span> python subdir/myprogram.py --help
|
||
<span class="go">usage: myprogram.py [-h] [--foo FOO]</span>
|
||
|
||
<span class="go">optional arguments:</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>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">optional arguments:</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">optional arguments:</span>
|
||
<span class="go"> -h, --help show this help message and exit</span>
|
||
<span class="go"> --foo FOO foo of the myprogram program</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="usage">
|
||
<h3>usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</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:</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="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 [-h] [--foo [FOO]] bar [bar ...]</span>
|
||
|
||
<span class="go">positional arguments:</span>
|
||
<span class="go"> bar bar help</span>
|
||
|
||
<span class="go">optional arguments:</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 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">optional arguments:</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>
|
||
</div>
|
||
<div class="section" id="description">
|
||
<h3>description<a class="headerlink" href="#description" title="Permalink to this headline">¶</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>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">description</span><span class="o">=</span><span class="s1">'A foo that bars'</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">optional arguments:</span>
|
||
<span class="go"> -h, --help show this help message and exit</span>
|
||
</pre></div>
|
||
</div>
|
||
<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>
|
||
</div>
|
||
<div class="section" id="epilog">
|
||
<h3>epilog<a class="headerlink" href="#epilog" title="Permalink to this headline">¶</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">optional arguments:</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>
|
||
</div>
|
||
<div class="section" id="parents">
|
||
<h3>parents<a class="headerlink" href="#parents" title="Permalink to this headline">¶</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>
|
||
</div>
|
||
<div class="section" id="formatter-class">
|
||
<h3>formatter_class<a class="headerlink" href="#formatter-class" title="Permalink to this headline">¶</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="class">
|
||
<dt id="argparse.RawDescriptionHelpFormatter">
|
||
<em class="property">class </em><code class="descclassname">argparse.</code><code class="descname">RawDescriptionHelpFormatter</code><a class="headerlink" href="#argparse.RawDescriptionHelpFormatter" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="argparse.RawTextHelpFormatter">
|
||
<em class="property">class </em><code class="descclassname">argparse.</code><code class="descname">RawTextHelpFormatter</code><a class="headerlink" href="#argparse.RawTextHelpFormatter" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="argparse.ArgumentDefaultsHelpFormatter">
|
||
<em class="property">class </em><code class="descclassname">argparse.</code><code class="descname">ArgumentDefaultsHelpFormatter</code><a class="headerlink" href="#argparse.ArgumentDefaultsHelpFormatter" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="argparse.MetavarTypeHelpFormatter">
|
||
<em class="property">class </em><code class="descclassname">argparse.</code><code class="descname">MetavarTypeHelpFormatter</code><a class="headerlink" href="#argparse.MetavarTypeHelpFormatter" title="Permalink 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">optional arguments:</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">optional arguments:</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 new lines 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 [bar ...]]</span>
|
||
|
||
<span class="go">positional arguments:</span>
|
||
<span class="go"> bar BAR! (default: [1, 2, 3])</span>
|
||
|
||
<span class="go">optional arguments:</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">optional arguments:</span>
|
||
<span class="go"> -h, --help show this help message and exit</span>
|
||
<span class="go"> --foo int</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="prefix-chars">
|
||
<h3>prefix_chars<a class="headerlink" href="#prefix-chars" title="Permalink to this headline">¶</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 ArgumentParser 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>
|
||
</div>
|
||
<div class="section" id="fromfile-prefix-chars">
|
||
<h3>fromfile_prefix_chars<a class="headerlink" href="#fromfile-prefix-chars" title="Permalink to this headline">¶</a></h3>
|
||
<p>Sometimes, for example when dealing with a particularly long argument lists, 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="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="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>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>
|
||
<div class="section" id="argument-default">
|
||
<h3>argument_default<a class="headerlink" href="#argument-default" title="Permalink to this headline">¶</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>
|
||
</div>
|
||
<div class="section" id="allow-abbrev">
|
||
<span id="id1"></span><h3>allow_abbrev<a class="headerlink" href="#allow-abbrev" title="Permalink to this headline">¶</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">New in version 3.5.</span></p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="conflict-handler">
|
||
<h3>conflict_handler<a class="headerlink" href="#conflict-handler" title="Permalink to this headline">¶</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">optional arguments:</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>
|
||
</div>
|
||
<div class="section" id="add-help">
|
||
<h3>add_help<a class="headerlink" href="#add-help" title="Permalink to this headline">¶</a></h3>
|
||
<p>By default, ArgumentParser objects add an option which simply displays
|
||
the parser’s help message. For example, consider a file named
|
||
<code class="docutils literal notranslate"><span class="pre">myprogram.py</span></code> containing the following code:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">argparse</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">'--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="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>
|
||
</pre></div>
|
||
</div>
|
||
<p>If <code class="docutils literal notranslate"><span class="pre">-h</span></code> or <code class="docutils literal notranslate"><span class="pre">--help</span></code> is supplied at the command line, the ArgumentParser
|
||
help will be printed:</p>
|
||
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> python myprogram.py --help
|
||
<span class="go">usage: myprogram.py [-h] [--foo FOO]</span>
|
||
|
||
<span class="go">optional arguments:</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>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">optional arguments:</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">optional arguments:</span>
|
||
<span class="go"> +h, ++help show this help message and exit</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="the-add-argument-method">
|
||
<h2>The add_argument() method<a class="headerlink" href="#the-add-argument-method" title="Permalink to this headline">¶</a></h2>
|
||
<dl class="method">
|
||
<dt id="argparse.ArgumentParser.add_argument">
|
||
<code class="descclassname">ArgumentParser.</code><code class="descname">add_argument</code><span class="sig-paren">(</span><em>name or flags...</em><span class="optional">[</span>, <em>action</em><span class="optional">]</span><span class="optional">[</span>, <em>nargs</em><span class="optional">]</span><span class="optional">[</span>, <em>const</em><span class="optional">]</span><span class="optional">[</span>, <em>default</em><span class="optional">]</span><span class="optional">[</span>, <em>type</em><span class="optional">]</span><span class="optional">[</span>, <em>choices</em><span class="optional">]</span><span class="optional">[</span>, <em>required</em><span class="optional">]</span><span class="optional">[</span>, <em>help</em><span class="optional">]</span><span class="optional">[</span>, <em>metavar</em><span class="optional">]</span><span class="optional">[</span>, <em>dest</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.add_argument" title="Permalink 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.</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 container 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>
|
||
</ul>
|
||
</dd></dl>
|
||
|
||
<p>The following sections describe how each of these are used.</p>
|
||
<div class="section" id="name-or-flags">
|
||
<h3>name or flags<a class="headerlink" href="#name-or-flags" title="Permalink to this headline">¶</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. 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>
|
||
</div>
|
||
<div class="section" id="action">
|
||
<h3>action<a class="headerlink" href="#action" title="Permalink to this headline">¶</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. 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="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'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
|
||
<span class="go">Namespace(foo='1')</span>
|
||
</pre></div>
|
||
</div>
|
||
</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. 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. 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_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. This is useful to allow an option to be specified multiple times.
|
||
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">'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="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>
|
||
</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="nn">argparse</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">prog</span><span class="o">=</span><span class="s1">'PROG'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--version'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'version'</span><span class="p">,</span> <span class="n">version</span><span class="o">=</span><span class="s1">'</span><span class="si">%(prog)s</span><span class="s1"> 2.0'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'--version'</span><span class="p">])</span>
|
||
<span class="go">PROG 2.0</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<p>You may also specify an arbitrary action by passing an Action subclass or
|
||
other object that implements the same interface. The recommended way to do
|
||
this 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="docutils literal notranslate"><span class="pre">__call__</span></code> method
|
||
and optionally the <code class="docutils literal notranslate"><span class="pre">__init__</span></code> method.</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="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="nf">__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="n">FooAction</span><span class="p">,</span> <span class="bp">self</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="nf">__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>
|
||
</div>
|
||
<div class="section" id="nargs">
|
||
<h3>nargs<a class="headerlink" href="#nargs" title="Permalink to this headline">¶</a></h3>
|
||
<p>ArgumentParser 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. 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>
|
||
<ul id="argparse-remainder">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">argparse.REMAINDER</span></code>. All the remaining command-line arguments are gathered
|
||
into a list. This is commonly useful for command line utilities that dispatch
|
||
to other command line utilities:</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="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'command'</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">'args'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">REMAINDER</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">'--foo B cmd --arg1 XX ZZ'</span><span class="o">.</span><span class="n">split</span><span class="p">()))</span>
|
||
<span class="go">Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')</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.</p>
|
||
</div>
|
||
<div class="section" id="const">
|
||
<h3>const<a class="headerlink" href="#const" title="Permalink to this headline">¶</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.</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 instead.
|
||
See the <a class="reference internal" href="#nargs">nargs</a> description for examples.</p></li>
|
||
</ul>
|
||
<p>With the <code class="docutils literal notranslate"><span class="pre">'store_const'</span></code> and <code class="docutils literal notranslate"><span class="pre">'append_const'</span></code> actions, the <code class="docutils literal notranslate"><span class="pre">const</span></code>
|
||
keyword argument must be given. For other actions, it defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
</div>
|
||
<div class="section" id="default">
|
||
<h3>default<a class="headerlink" href="#default" title="Permalink to this headline">¶</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 <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>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>
|
||
</div>
|
||
<div class="section" id="type">
|
||
<h3>type<a class="headerlink" href="#type" title="Permalink to this headline">¶</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 read command-line arguments in as simple
|
||
strings. However, quite often the command-line string should instead be
|
||
interpreted as another type, like 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 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> allows any
|
||
necessary type-checking and type conversions to be performed. Common built-in
|
||
types and functions can be used directly as the value of the <code class="docutils literal notranslate"><span class="pre">type</span></code> 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="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">open</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 temp.txt'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
|
||
<span class="go">Namespace(bar=<_io.TextIOWrapper name='temp.txt' encoding='UTF-8'>, foo=2)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>See the section on the <a class="reference internal" href="#default">default</a> keyword argument for information on when the
|
||
<code class="docutils literal notranslate"><span class="pre">type</span></code> argument is applied to default arguments.</p>
|
||
<p>To ease the use of various types of files, the argparse module provides the
|
||
factory FileType which takes the <code class="docutils literal notranslate"><span class="pre">mode=</span></code>, <code class="docutils literal notranslate"><span class="pre">bufsize=</span></code>, <code class="docutils literal notranslate"><span class="pre">encoding=</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">errors=</span></code> arguments of 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 example,
|
||
<code class="docutils literal notranslate"><span class="pre">FileType('w')</span></code> can be used to create a writable file:</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="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">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'out.txt'</span><span class="p">])</span>
|
||
<span class="go">Namespace(bar=<_io.TextIOWrapper name='out.txt' encoding='UTF-8'>)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><code class="docutils literal notranslate"><span class="pre">type=</span></code> can take any callable that takes a single string argument and returns
|
||
the converted value:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">def</span> <span class="nf">perfect_square</span><span class="p">(</span><span class="n">string</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="n">value</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">string</span><span class="p">)</span>
|
||
<span class="gp">... </span> <span class="n">sqrt</span> <span class="o">=</span> <span class="n">math</span><span class="o">.</span><span class="n">sqrt</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
|
||
<span class="gp">... </span> <span class="k">if</span> <span class="n">sqrt</span> <span class="o">!=</span> <span class="nb">int</span><span class="p">(</span><span class="n">sqrt</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="n">msg</span> <span class="o">=</span> <span class="s2">"</span><span class="si">%r</span><span class="s2"> is not a perfect square"</span> <span class="o">%</span> <span class="n">string</span>
|
||
<span class="gp">... </span> <span class="k">raise</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentTypeError</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span>
|
||
<span class="gp">... </span> <span class="k">return</span> <span class="n">value</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">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="n">perfect_square</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">'9'</span><span class="p">])</span>
|
||
<span class="go">Namespace(foo=9)</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">'7'</span><span class="p">])</span>
|
||
<span class="go">usage: PROG [-h] foo</span>
|
||
<span class="go">PROG: error: argument foo: '7' is not a perfect square</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The <a class="reference internal" href="#choices">choices</a> keyword argument may be more convenient for type checkers that
|
||
simply check against a range of 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">'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="n">choices</span><span class="o">=</span><span class="nb">range</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">10</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">'7'</span><span class="p">])</span>
|
||
<span class="go">Namespace(foo=7)</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">'11'</span><span class="p">])</span>
|
||
<span class="go">usage: PROG [-h] {5,6,7,8,9}</span>
|
||
<span class="go">PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>See the <a class="reference internal" href="#choices">choices</a> section for more details.</p>
|
||
</div>
|
||
<div class="section" id="choices">
|
||
<h3>choices<a class="headerlink" href="#choices" title="Permalink to this headline">¶</a></h3>
|
||
<p>Some command-line arguments should be selected from a restricted set of values.
|
||
These can be handled by passing a container 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> container 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>
|
||
container should match the <a class="reference internal" href="#type">type</a> specified:</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">'doors.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">'door'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="nb">range</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">4</span><span class="p">))</span>
|
||
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'3'</span><span class="p">]))</span>
|
||
<span class="go">Namespace(door=3)</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'4'</span><span class="p">])</span>
|
||
<span class="go">usage: doors.py [-h] {1,2,3}</span>
|
||
<span class="go">doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Any object that supports the <code class="docutils literal notranslate"><span class="pre">in</span></code> operator can be passed as the <em>choices</em>
|
||
value, so <a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a> objects, <a class="reference internal" href="stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a> objects, custom containers,
|
||
etc. are all supported.</p>
|
||
</div>
|
||
<div class="section" id="required">
|
||
<h3>required<a class="headerlink" href="#required" title="Permalink to this headline">¶</a></h3>
|
||
<p>In general, the <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code></a> module assumes that flags like <code class="docutils literal notranslate"><span class="pre">-f</span></code> and <code class="docutils literal notranslate"><span class="pre">--bar</span></code>
|
||
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: argparse.py [-h] [--foo FOO]</span>
|
||
<span class="go">argparse.py: error: option --foo is required</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>
|
||
</div>
|
||
<div class="section" id="help">
|
||
<h3>help<a class="headerlink" href="#help" title="Permalink to this headline">¶</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>
|
||
<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">action</span><span class="o">=</span><span class="s1">'store_true'</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="n">help</span><span class="o">=</span><span class="s1">'foo the bars before frobbling'</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">help</span><span class="o">=</span><span class="s1">'one of the bars to be frobbled'</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: frobble [-h] [--foo] bar [bar ...]</span>
|
||
|
||
<span class="go">positional arguments:</span>
|
||
<span class="go"> bar one of the bars to be frobbled</span>
|
||
|
||
<span class="go">optional arguments:</span>
|
||
<span class="go"> -h, --help show this help message and exit</span>
|
||
<span class="go"> --foo foo the bars before frobbling</span>
|
||
</pre></div>
|
||
</div>
|
||
<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">optional arguments:</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><a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code></a> supports silencing the help entry for certain options, by
|
||
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">optional arguments:</span>
|
||
<span class="go"> -h, --help show this help message and exit</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="metavar">
|
||
<h3>metavar<a class="headerlink" href="#metavar" title="Permalink to this headline">¶</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, ArgumentParser 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">optional arguments:</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">optional arguments:</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">optional arguments:</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>
|
||
</div>
|
||
<div class="section" id="dest">
|
||
<h3>dest<a class="headerlink" href="#dest" title="Permalink to this headline">¶</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>
|
||
</div>
|
||
<div class="section" id="action-classes">
|
||
<h3>Action classes<a class="headerlink" href="#action-classes" title="Permalink to this headline">¶</a></h3>
|
||
<p>Action 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
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code>.</p>
|
||
<dl class="class">
|
||
<dt id="argparse.Action">
|
||
<em class="property">class </em><code class="descclassname">argparse.</code><code class="descname">Action</code><span class="sig-paren">(</span><em>option_strings</em>, <em>dest</em>, <em>nargs=None</em>, <em>const=None</em>, <em>default=None</em>, <em>type=None</em>, <em>choices=None</em>, <em>required=False</em>, <em>help=None</em>, <em>metavar=None</em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.Action" title="Permalink to this definition">¶</a></dt>
|
||
<dd></dd></dl>
|
||
|
||
<p>Action objects are used by an ArgumentParser to represent the information
|
||
needed to parse a single argument from one or more strings from the
|
||
command line. The Action 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 Action (or return value of any callable to the <code class="docutils literal notranslate"><span class="pre">action</span></code>
|
||
parameter) should have attributes “dest”, “option_strings”, “default”, “type”,
|
||
“required”, “help”, etc. defined. The easiest way to ensure these attributes
|
||
are defined is to call <code class="docutils literal notranslate"><span class="pre">Action.__init__</span></code>.</p>
|
||
<p>Action instances should be callable, so subclasses must override the
|
||
<code class="docutils literal notranslate"><span class="pre">__call__</span></code> method, which should accept four parameters:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">parser</span></code> - The ArgumentParser object which contains this action.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">namespace</span></code> - The <a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate"><span class="pre">Namespace</span></code></a> object that will be returned by
|
||
<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><code class="docutils literal notranslate"><span class="pre">values</span></code> - 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><code class="docutils literal notranslate"><span class="pre">option_string</span></code> - 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="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>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="the-parse-args-method">
|
||
<h2>The parse_args() method<a class="headerlink" href="#the-parse-args-method" title="Permalink to this headline">¶</a></h2>
|
||
<dl class="method">
|
||
<dt id="argparse.ArgumentParser.parse_args">
|
||
<code class="descclassname">ArgumentParser.</code><code class="descname">parse_args</code><span class="sig-paren">(</span><em>args=None</em>, <em>namespace=None</em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.parse_args" title="Permalink 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
|
||
<a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> for details.</p>
|
||
<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>
|
||
|
||
<div class="section" id="option-value-syntax">
|
||
<h3>Option value syntax<a class="headerlink" href="#option-value-syntax" title="Permalink to this headline">¶</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>
|
||
</div>
|
||
<div class="section" id="invalid-arguments">
|
||
<h3>Invalid arguments<a class="headerlink" href="#invalid-arguments" title="Permalink to this headline">¶</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>
|
||
</div>
|
||
<div class="section" id="arguments-containing">
|
||
<h3>Arguments containing <code class="docutils literal notranslate"><span class="pre">-</span></code><a class="headerlink" href="#arguments-containing" title="Permalink to this headline">¶</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>
|
||
</div>
|
||
<div class="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="Permalink to this headline">¶</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>
|
||
</div>
|
||
<div class="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="Permalink to this headline">¶</a></h3>
|
||
<p>Sometimes it may be useful to have an ArgumentParser 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>
|
||
</div>
|
||
<div class="section" id="the-namespace-object">
|
||
<span id="namespace"></span><h3>The Namespace object<a class="headerlink" href="#the-namespace-object" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="argparse.Namespace">
|
||
<em class="property">class </em><code class="descclassname">argparse.</code><code class="descname">Namespace</code><a class="headerlink" href="#argparse.Namespace" title="Permalink 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>
|
||
</dd></dl>
|
||
|
||
<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="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>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="other-utilities">
|
||
<h2>Other utilities<a class="headerlink" href="#other-utilities" title="Permalink to this headline">¶</a></h2>
|
||
<div class="section" id="sub-commands">
|
||
<h3>Sub-commands<a class="headerlink" href="#sub-commands" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="method">
|
||
<dt id="argparse.ArgumentParser.add_subparsers">
|
||
<code class="descclassname">ArgumentParser.</code><code class="descname">add_subparsers</code><span class="sig-paren">(</span><span class="optional">[</span><em>title</em><span class="optional">]</span><span class="optional">[</span>, <em>description</em><span class="optional">]</span><span class="optional">[</span>, <em>prog</em><span class="optional">]</span><span class="optional">[</span>, <em>parser_class</em><span class="optional">]</span><span class="optional">[</span>, <em>action</em><span class="optional">]</span><span class="optional">[</span>, <em>option_string</em><span class="optional">]</span><span class="optional">[</span>, <em>dest</em><span class="optional">]</span><span class="optional">[</span>, <em>required</em><span class="optional">]</span><span class="optional">[</span>, <em>help</em><span class="optional">]</span><span class="optional">[</span>, <em>metavar</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.add_subparsers" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Many programs split up their functionality into a number of sub-commands,
|
||
for example, the <code class="docutils literal notranslate"><span class="pre">svn</span></code> program can invoke sub-commands like <code class="docutils literal notranslate"><span class="pre">svn</span>
|
||
<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 sub-commands with 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. The <a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_subparsers()</span></code></a> method is normally
|
||
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 <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> constructor arguments, and
|
||
returns an <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> object that can be modified as usual.</p>
|
||
<p>Description of parameters:</p>
|
||
<ul class="simple">
|
||
<li><p>title - 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>description - 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>prog - 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>parser_class - class which will be used to create sub-parser instances, by
|
||
default the class of the current parser (e.g. ArgumentParser)</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>.</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 sub-commands in help; by default it
|
||
is <code class="docutils literal notranslate"><span class="pre">None</span></code> and presents sub-commands 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">'sub-command help'</span><span class="p">)</span>
|
||
<span class="go">>>></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="go">>>></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="s1">'XYZ'</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="go">>>></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} sub-command help</span>
|
||
<span class="go"> a a help</span>
|
||
<span class="go"> b b help</span>
|
||
|
||
<span class="go">optional arguments:</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">optional arguments:</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">optional arguments:</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">optional arguments:</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="docutils literal notranslate"><span class="pre">add_parser</span></code> supports an additional <code class="docutils literal notranslate"><span class="pre">aliases</span></code> argument,
|
||
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>One particularly effective way of handling sub-commands 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"># sub-command functions</span>
|
||
<span class="gp">>>> </span><span class="k">def</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="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="go">>>></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="go">>>></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="go">>>></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="go">>>></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>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="filetype-objects">
|
||
<h3>FileType objects<a class="headerlink" href="#filetype-objects" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="argparse.FileType">
|
||
<em class="property">class </em><code class="descclassname">argparse.</code><code class="descname">FileType</code><span class="sig-paren">(</span><em>mode='r'</em>, <em>bufsize=-1</em>, <em>encoding=None</em>, <em>errors=None</em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.FileType" title="Permalink 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 <code class="docutils literal notranslate"><span class="pre">sys.stdin</span></code> 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
|
||
<code class="docutils literal notranslate"><span class="pre">sys.stdout</span></code> 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="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.4: </span>The <em>encodings</em> and <em>errors</em> keyword arguments.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="argument-groups">
|
||
<h3>Argument groups<a class="headerlink" href="#argument-groups" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="method">
|
||
<dt id="argparse.ArgumentParser.add_argument_group">
|
||
<code class="descclassname">ArgumentParser.</code><code class="descname">add_argument_group</code><span class="sig-paren">(</span><em>title=None</em>, <em>description=None</em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.add_argument_group" title="Permalink 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 “optional arguments” when displaying help
|
||
messages. When there is a better conceptual grouping of arguments than this
|
||
default one, appropriate groups can be created using 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:</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 <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
|
||
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>Note that any arguments not in your user-defined groups will end up back
|
||
in the usual “positional arguments” and “optional arguments” sections.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="mutual-exclusion">
|
||
<h3>Mutual exclusion<a class="headerlink" href="#mutual-exclusion" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="method">
|
||
<dt id="argparse.ArgumentParser.add_mutually_exclusive_group">
|
||
<code class="descclassname">ArgumentParser.</code><code class="descname">add_mutually_exclusive_group</code><span class="sig-paren">(</span><em>required=False</em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.add_mutually_exclusive_group" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Create a mutually exclusive group. <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code></a> will make sure that only
|
||
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>.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="parser-defaults">
|
||
<h3>Parser defaults<a class="headerlink" href="#parser-defaults" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="method">
|
||
<dt id="argparse.ArgumentParser.set_defaults">
|
||
<code class="descclassname">ArgumentParser.</code><code class="descname">set_defaults</code><span class="sig-paren">(</span><em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.set_defaults" title="Permalink 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="method">
|
||
<dt id="argparse.ArgumentParser.get_default">
|
||
<code class="descclassname">ArgumentParser.</code><code class="descname">get_default</code><span class="sig-paren">(</span><em>dest</em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.get_default" title="Permalink 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>
|
||
|
||
</div>
|
||
<div class="section" id="printing-help">
|
||
<h3>Printing help<a class="headerlink" href="#printing-help" title="Permalink to this headline">¶</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="method">
|
||
<dt id="argparse.ArgumentParser.print_usage">
|
||
<code class="descclassname">ArgumentParser.</code><code class="descname">print_usage</code><span class="sig-paren">(</span><em>file=None</em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.print_usage" title="Permalink 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="method">
|
||
<dt id="argparse.ArgumentParser.print_help">
|
||
<code class="descclassname">ArgumentParser.</code><code class="descname">print_help</code><span class="sig-paren">(</span><em>file=None</em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.print_help" title="Permalink 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="method">
|
||
<dt id="argparse.ArgumentParser.format_usage">
|
||
<code class="descclassname">ArgumentParser.</code><code class="descname">format_usage</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.format_usage" title="Permalink 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="method">
|
||
<dt id="argparse.ArgumentParser.format_help">
|
||
<code class="descclassname">ArgumentParser.</code><code class="descname">format_help</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.format_help" title="Permalink 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>
|
||
|
||
</div>
|
||
<div class="section" id="partial-parsing">
|
||
<h3>Partial parsing<a class="headerlink" href="#partial-parsing" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="method">
|
||
<dt id="argparse.ArgumentParser.parse_known_args">
|
||
<code class="descclassname">ArgumentParser.</code><code class="descname">parse_known_args</code><span class="sig-paren">(</span><em>args=None</em>, <em>namespace=None</em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.parse_known_args" title="Permalink to this definition">¶</a></dt>
|
||
<dd></dd></dl>
|
||
|
||
<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>
|
||
<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
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_known_args()</span></code>. 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>
|
||
</div>
|
||
<div class="section" id="customizing-file-parsing">
|
||
<h3>Customizing file parsing<a class="headerlink" href="#customizing-file-parsing" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="method">
|
||
<dt id="argparse.ArgumentParser.convert_arg_line_to_args">
|
||
<code class="descclassname">ArgumentParser.</code><code class="descname">convert_arg_line_to_args</code><span class="sig-paren">(</span><em>arg_line</em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.convert_arg_line_to_args" title="Permalink 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="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="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>
|
||
|
||
</div>
|
||
<div class="section" id="exiting-methods">
|
||
<h3>Exiting methods<a class="headerlink" href="#exiting-methods" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="method">
|
||
<dt id="argparse.ArgumentParser.exit">
|
||
<code class="descclassname">ArgumentParser.</code><code class="descname">exit</code><span class="sig-paren">(</span><em>status=0</em>, <em>message=None</em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.exit" title="Permalink 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> before that.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="argparse.ArgumentParser.error">
|
||
<code class="descclassname">ArgumentParser.</code><code class="descname">error</code><span class="sig-paren">(</span><em>message</em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.error" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>This method prints a usage message including the <em>message</em> to the
|
||
standard error and terminates the program with a status code of 2.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="intermixed-parsing">
|
||
<h3>Intermixed parsing<a class="headerlink" href="#intermixed-parsing" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="method">
|
||
<dt id="argparse.ArgumentParser.parse_intermixed_args">
|
||
<code class="descclassname">ArgumentParser.</code><code class="descname">parse_intermixed_args</code><span class="sig-paren">(</span><em>args=None</em>, <em>namespace=None</em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.parse_intermixed_args" title="Permalink to this definition">¶</a></dt>
|
||
<dd></dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="argparse.ArgumentParser.parse_known_intermixed_args">
|
||
<code class="descclassname">ArgumentParser.</code><code class="descname">parse_known_intermixed_args</code><span class="sig-paren">(</span><em>args=None</em>, <em>namespace=None</em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.parse_known_intermixed_args" title="Permalink to this definition">¶</a></dt>
|
||
<dd></dd></dl>
|
||
|
||
<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 argparse features, and will raise
|
||
exceptions if unsupported features are used. In particular, subparsers,
|
||
<code class="docutils literal notranslate"><span class="pre">argparse.REMAINDER</span></code>, 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">New in version 3.7.</span></p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="upgrading-optparse-code">
|
||
<span id="id2"></span><h2>Upgrading optparse code<a class="headerlink" href="#upgrading-optparse-code" title="Permalink to this headline">¶</a></h2>
|
||
<p>Originally, the <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code></a> module had attempted to maintain compatibility
|
||
with <a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a>. However, <a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> was difficult to extend
|
||
transparently, particularly with the changes required to support the new
|
||
<code class="docutils literal notranslate"><span class="pre">nargs=</span></code> specifiers and better usage messages. When most everything in
|
||
<a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> had either been copy-pasted over or monkey-patched, it no
|
||
longer seemed practical to try to maintain the backwards compatibility.</p>
|
||
<p>The <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code></a> module improves on the standard library <a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a>
|
||
module in a number of ways including:</p>
|
||
<ul class="simple">
|
||
<li><p>Handling positional arguments.</p></li>
|
||
<li><p>Supporting sub-commands.</p></li>
|
||
<li><p>Allowing alternative option prefixes like <code class="docutils literal notranslate"><span class="pre">+</span></code> and <code class="docutils literal notranslate"><span class="pre">/</span></code>.</p></li>
|
||
<li><p>Handling zero-or-more and one-or-more style arguments.</p></li>
|
||
<li><p>Producing more informative usage messages.</p></li>
|
||
<li><p>Providing a much simpler interface for custom <code class="docutils literal notranslate"><span class="pre">type</span></code> and <code class="docutils literal notranslate"><span class="pre">action</span></code>.</p></li>
|
||
</ul>
|
||
<p>A partial upgrade path from <a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> to <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code></a>:</p>
|
||
<ul class="simple">
|
||
<li><p>Replace all <a class="reference internal" href="optparse.html#optparse.OptionParser.add_option" title="optparse.OptionParser.add_option"><code class="xref py py-meth docutils literal notranslate"><span class="pre">optparse.OptionParser.add_option()</span></code></a> calls with
|
||
<a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ArgumentParser.add_argument()</span></code></a> calls.</p></li>
|
||
<li><p>Replace <code class="docutils literal notranslate"><span class="pre">(options,</span> <span class="pre">args)</span> <span class="pre">=</span> <span class="pre">parser.parse_args()</span></code> with <code class="docutils literal notranslate"><span class="pre">args</span> <span class="pre">=</span>
|
||
<span class="pre">parser.parse_args()</span></code> and add additional <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ArgumentParser.add_argument()</span></code></a>
|
||
calls for the positional arguments. Keep in mind that what was previously
|
||
called <code class="docutils literal notranslate"><span class="pre">options</span></code>, now in the <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code></a> context is called <code class="docutils literal notranslate"><span class="pre">args</span></code>.</p></li>
|
||
<li><p>Replace <a class="reference internal" href="optparse.html#optparse.OptionParser.disable_interspersed_args" title="optparse.OptionParser.disable_interspersed_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">optparse.OptionParser.disable_interspersed_args()</span></code></a>
|
||
by using <a class="reference internal" href="#argparse.ArgumentParser.parse_intermixed_args" title="argparse.ArgumentParser.parse_intermixed_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_intermixed_args()</span></code></a> instead of
|
||
<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>Replace callback actions and the <code class="docutils literal notranslate"><span class="pre">callback_*</span></code> keyword arguments with
|
||
<code class="docutils literal notranslate"><span class="pre">type</span></code> or <code class="docutils literal notranslate"><span class="pre">action</span></code> arguments.</p></li>
|
||
<li><p>Replace string names for <code class="docutils literal notranslate"><span class="pre">type</span></code> keyword arguments with the corresponding
|
||
type objects (e.g. int, float, complex, etc).</p></li>
|
||
<li><p>Replace <code class="xref py py-class docutils literal notranslate"><span class="pre">optparse.Values</span></code> with <a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate"><span class="pre">Namespace</span></code></a> and
|
||
<code class="xref py py-exc docutils literal notranslate"><span class="pre">optparse.OptionError</span></code> and <code class="xref py py-exc docutils literal notranslate"><span class="pre">optparse.OptionValueError</span></code> with
|
||
<code class="xref py py-exc docutils literal notranslate"><span class="pre">ArgumentError</span></code>.</p></li>
|
||
<li><p>Replace strings with implicit arguments such as <code class="docutils literal notranslate"><span class="pre">%default</span></code> or <code class="docutils literal notranslate"><span class="pre">%prog</span></code> with
|
||
the standard Python syntax to use dictionaries to format strings, that is,
|
||
<code class="docutils literal notranslate"><span class="pre">%(default)s</span></code> and <code class="docutils literal notranslate"><span class="pre">%(prog)s</span></code>.</p></li>
|
||
<li><p>Replace the OptionParser constructor <code class="docutils literal notranslate"><span class="pre">version</span></code> argument with a call to
|
||
<code class="docutils literal notranslate"><span class="pre">parser.add_argument('--version',</span> <span class="pre">action='version',</span> <span class="pre">version='<the</span> <span class="pre">version>')</span></code>.</p></li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<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 sub-commands</a><ul>
|
||
<li><a class="reference internal" href="#example">Example</a><ul>
|
||
<li><a class="reference internal" href="#creating-a-parser">Creating a parser</a></li>
|
||
<li><a class="reference internal" href="#adding-arguments">Adding arguments</a></li>
|
||
<li><a class="reference internal" href="#parsing-arguments">Parsing arguments</a></li>
|
||
</ul>
|
||
</li>
|
||
<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>
|
||
</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="#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>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#upgrading-optparse-code">Upgrading optparse code</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="time.html"
|
||
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">time</span></code> — Time access and conversions</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="getopt.html"
|
||
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">getopt</span></code> — C-style parser for command line options</a></p>
|
||
<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/3.7/Doc/library/argparse.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<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="getopt.html" title="getopt — C-style parser for command line options"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="time.html" title="time — Time access and conversions"
|
||
>previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">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="allos.html" >Generic Operating System Services</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
||
<br />
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
Last updated on Jul 13, 2019.
|
||
<a href="../bugs.html">Found a bug</a>?
|
||
<br />
|
||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |