<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>The add_argument() method — argparse v1.1 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '1.1',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="argparse v1.1 documentation" href="index.html" />
<link rel="up" title="API documentation" href="api-docs.html" />
<link rel="next" title="The parse_args() method" href="parse_args.html" />
<link rel="prev" title="ArgumentParser objects" href="ArgumentParser.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="parse_args.html" title="The parse_args() method"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="ArgumentParser.html" title="ArgumentParser objects"
accesskey="P">previous</a> |</li>
<li><a href="index.html">argparse v1.1 documentation</a> »</li>
<li><a href="api-docs.html" accesskey="U">API documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="the-add-argument-method">
<h1>The add_argument() method<a class="headerlink" href="#the-add-argument-method" title="Permalink to this headline">¶</a></h1>
<dl class="method">
<dt id="add_argument">
<tt class="descname">add_argument</tt><big>(</big><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><big>)</big><a class="headerlink" href="#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><a class="reference internal" href="#name-or-flags">name or flags</a> - Either a name or a list of option strings, e.g. <tt class="docutils literal"><span class="pre">foo</span></tt> or <tt class="docutils literal"><span class="pre">-f,</span> <span class="pre">--foo</span></tt></li>
<li><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.</li>
<li><a class="reference internal" href="#nargs">nargs</a> - The number of command-line arguments that should be consumed.</li>
<li><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.</li>
<li><a class="reference internal" href="#default">default</a> - The value produced if the argument is absent from the command-line.</li>
<li><a class="reference internal" href="#type">type</a> - The type to which the command-line arg should be converted.</li>
<li><a class="reference internal" href="#choices">choices</a> - A container of the allowable values for the argument.</li>
<li><a class="reference internal" href="#required">required</a> - Whether or not the command-line option may be omitted (optionals only).</li>
<li><a class="reference internal" href="#help">help</a> - A brief description of what the argument does.</li>
<li><a class="reference internal" href="#metavar">metavar</a> - A name for the argument in usage messages.</li>
<li><a class="reference internal" href="#dest">dest</a> - The name of the attribute to be added to the object returned by <a title="parse_args" class="reference external" href="parse_args.html#parse_args"><tt class="xref docutils literal"><span class="pre">parse_args()</span></tt></a>.</li>
</ul>
<p>The following sections describe how each of these are used.</p>
</dd></dl>
<div class="section" id="name-or-flags">
<h2>name or flags<a class="headerlink" href="#name-or-flags" title="Permalink to this headline">¶</a></h2>
<p>The <a title="add_argument" class="reference internal" href="#add_argument"><tt class="xref docutils literal"><span class="pre">add_argument()</span></tt></a> method needs to know whether you’re expecting an optional argument, e.g. <tt class="docutils literal"><span class="pre">-f</span></tt> or <tt class="docutils literal"><span class="pre">--foo</span></tt>, or a positional argument, e.g. a list of filenames. The first arguments passed to <a title="add_argument" class="reference internal" href="#add_argument"><tt class="xref docutils literal"><span class="pre">add_argument()</span></tt></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-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'-f'</span><span class="p">,</span> <span class="s">'--foo'</span><span class="p">)</span>
</pre></div>
</div>
<p>while a positional argument could be created like:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'bar'</span><span class="p">)</span>
</pre></div>
</div>
<p>When <a title="parse_args" class="reference external" href="parse_args.html#parse_args"><tt class="xref docutils literal"><span class="pre">parse_args()</span></tt></a> is called, optional arguments will be identified by the <tt class="docutils literal"><span class="pre">-</span></tt> prefix, and the remaining arguments will be assumed to be positional:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'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="s">'-f'</span><span class="p">,</span> <span class="s">'--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="s">'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="s">'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="s">'BAR'</span><span class="p">,</span> <span class="s">'--foo'</span><span class="p">,</span> <span class="s">'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="s">'--foo'</span><span class="p">,</span> <span class="s">'FOO'</span><span class="p">])</span>
<span class="go">usage: PROG [-h] [-f FOO] bar</span>
<span class="go">PROG: error: too few arguments</span>
</pre></div>
</div>
</div>
<div class="section" id="action">
<h2>action<a class="headerlink" href="#action" title="Permalink to this headline">¶</a></h2>
<p><a title="ArgumentParser" class="reference external" href="ArgumentParser.html#ArgumentParser"><tt class="xref docutils literal"><span class="pre">ArgumentParser</span></tt></a> objects associate command-line args with actions. These actions can do just about anything with the command-line args associated with them, though most actions simply add an attribute to the object returned by <a title="parse_args" class="reference external" href="parse_args.html#parse_args"><tt class="xref docutils literal"><span class="pre">parse_args()</span></tt></a>. When you specify a new argument using the <a title="add_argument" class="reference internal" href="#add_argument"><tt class="xref docutils literal"><span class="pre">add_argument()</span></tt></a> method, you can indicate how the command-line args should be handled by specifying the <tt class="docutils literal"><span class="pre">action</span></tt> keyword argument. The supported actions are:</p>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">'store'</span></tt> - This just stores the argument’s value. This is the default action. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'--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="s">'--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 class="first"><tt class="docutils literal"><span class="pre">'store_const'</span></tt> - This stores the value specified by the <a class="reference internal" href="#const">const</a> keyword argument. Note that the <a class="reference internal" href="#const">const</a> keyword argument defaults to <tt class="xref docutils literal"><span class="pre">None</span></tt>, so you’ll almost always need to provide a value for it. The <tt class="docutils literal"><span class="pre">'store_const'</span></tt> action is most commonly used with optional arguments that specify some sort of flag. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'--foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_const'</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="mf">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="s">'--foo'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(foo=42)</span>
</pre></div>
</div>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">'store_true'</span></tt> and <tt class="docutils literal"><span class="pre">'store_false'</span></tt> - These store the values <tt class="xref docutils literal"><span class="pre">True</span></tt> and <tt class="xref docutils literal"><span class="pre">False</span></tt> respectively. These are basically special cases of <tt class="docutils literal"><span class="pre">'store_const'</span></tt>. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'--foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'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="s">'--bar'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'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="s">'--foo --bar'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(bar=False, foo=True)</span>
</pre></div>
</div>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">'append'</span></tt> - This stores a list, and appends each argument value to the list. This is useful when you want to allow an option to be specified multiple times. Example usage:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'--foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'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="s">'--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 class="first"><tt class="docutils literal"><span class="pre">'append_const'</span></tt> - 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 <tt class="xref docutils literal"><span class="pre">None</span></tt>, so you’ll almost always need to provide a value for it. The <tt class="docutils literal"><span class="pre">'append_const'</span></tt> action is typically useful when you want multiple arguments to store constants to the same list, for example:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'--str'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">'types'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'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="s">'--int'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">'types'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'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="s">'--str --int'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(types=[<type 'str'>, <type 'int'>])</span>
</pre></div>
</div>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">'version'</span></tt> - This expects a <tt class="docutils literal"><span class="pre">version=</span></tt> keyword argument in the <a title="add_argument" class="reference internal" href="#add_argument"><tt class="xref docutils literal"><span class="pre">add_argument()</span></tt></a> call, and prints version information and exits when invoked.</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'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="s">'-v'</span><span class="p">,</span> <span class="s">'--version'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'version'</span><span class="p">,</span> <span class="n">version</span><span class="o">=</span><span class="s">'</span><span class="si">%(prog)s</span><span class="s"> 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="s">'-v'</span><span class="p">])</span>
<span class="go">PROG 2.0</span>
</pre></div>
</div>
</li>
</ul>
<p>You can also specify an arbitrary action by passing an object that implements the Action API. The easiest way to do this is to extend <tt class="docutils literal"><span class="pre">argparse.Action</span></tt>, supplying an appropriate <tt class="docutils literal"><span class="pre">__call__</span></tt> method. The <tt class="docutils literal"><span class="pre">__call__</span></tt> method accepts four parameters:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">parser</span></tt> - The ArgumentParser object which contains this action.</li>
<li><tt class="docutils literal"><span class="pre">namespace</span></tt> - The namespace object that will be returned by <a title="parse_args" class="reference external" href="parse_args.html#parse_args"><tt class="xref docutils literal"><span class="pre">parse_args()</span></tt></a>. Most actions add an attribute to this object.</li>
<li><tt class="docutils literal"><span class="pre">values</span></tt> - The associated command-line args, with any type-conversions applied. (Type-conversions are specified with the <a class="reference internal" href="#type">type</a> keyword argument to <a title="add_argument" class="reference internal" href="#add_argument"><tt class="xref docutils literal"><span class="pre">add_argument()</span></tt></a>.</li>
<li><tt class="docutils literal"><span class="pre">option_string</span></tt> - The option string that was used to invoke this action. The <tt class="docutils literal"><span class="pre">option_string</span></tt> argument is optional, and will be absent if the action is associated with a positional argument.</li>
</ul>
<p>So for example:</p>
<div class="highlight-python"><div class="highlight"><pre><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">__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="bp">None</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">print</span> <span class="s">'</span><span class="si">%r</span><span class="s"> </span><span class="si">%r</span><span class="s"> </span><span class="si">%r</span><span class="s">'</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="s">'--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="s">'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="s">'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>
</div>
<div class="section" id="nargs">
<h2>nargs<a class="headerlink" href="#nargs" title="Permalink to this headline">¶</a></h2>
<p>ArgumentParser objects usually associate a single command-line argument with a single action to be taken. In the situations where you’d like to associate a different number of command-line arguments with a single action, you can use the <tt class="docutils literal"><span class="pre">nargs</span></tt> keyword argument to <a title="add_argument" class="reference internal" href="#add_argument"><tt class="xref docutils literal"><span class="pre">add_argument()</span></tt></a>. The supported values are:</p>
<ul>
<li><p class="first">N (an integer). N args from the command-line will be gathered together into a list. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'--foo'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="mf">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="s">'bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="mf">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="s">'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 <tt class="docutils literal"><span class="pre">nargs=1</span></tt> produces a list of one item. This is different from the default, in which the item is produced by itself.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">'?'</span></tt>. One arg will be consumed from the command-line if possible, and produced as a single item. If no command-line arg 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 arg. 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-python"><div class="highlight"><pre><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="s">'--foo'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s">'?'</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s">'c'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s">'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="s">'bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s">'?'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s">'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="s">'XX --foo YY'</span><span class="o">.</span><span class="n">split</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="s">'XX --foo'</span><span class="o">.</span><span class="n">split</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="s">''</span><span class="o">.</span><span class="n">split</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 <tt class="docutils literal"><span class="pre">nargs='?'</span></tt> is to allow optional input and output files:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'infile'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s">'?'</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="s">'r'</span><span class="p">),</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="s">'outfile'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s">'?'</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="s">'w'</span><span class="p">),</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="s">'input.txt'</span><span class="p">,</span> <span class="s">'output.txt'</span><span class="p">])</span>
<span class="go">Namespace(infile=<open file 'input.txt', mode 'r' at 0x...>, outfile=<open file 'output.txt', mode 'w' at 0x...>)</span>
<span 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=<open file '<stdin>', mode 'r' at 0x...>, outfile=<open file '<stdout>', mode 'w' at 0x...>)</span>
</pre></div>
</div>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">'*'</span></tt>. All command-line args present are gathered into a list. Note that it generally doesn’t make much sense to have more than one positional argument with <tt class="docutils literal"><span class="pre">nargs='*'</span></tt>, but multiple optional arguments with <tt class="docutils literal"><span class="pre">nargs='*'</span></tt> is possible. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'--foo'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s">'*'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'--bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s">'*'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'baz'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s">'*'</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="s">'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>
<li><p class="first"><tt class="docutils literal"><span class="pre">'+'</span></tt>. Just like <tt class="docutils literal"><span class="pre">'*'</span></tt>, 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 arg present. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'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="s">'foo'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s">'+'</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="s">'a b'</span><span class="o">.</span><span class="n">split</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="s">''</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">usage: PROG [-h] foo [foo ...]</span>
<span class="go">PROG: error: too few arguments</span>
</pre></div>
</div>
</li>
</ul>
<p>If the <tt class="docutils literal"><span class="pre">nargs</span></tt> keyword argument is not provided, the number of args consumed is determined by the <a class="reference internal" href="#action">action</a>. Generally this means a single command-line arg will be consumed and a single item (not a list) will be produced.</p>
</div>
<div class="section" id="const">
<h2>const<a class="headerlink" href="#const" title="Permalink to this headline">¶</a></h2>
<p>The <tt class="docutils literal"><span class="pre">const</span></tt> argument of <a title="add_argument" class="reference internal" href="#add_argument"><tt class="xref docutils literal"><span class="pre">add_argument()</span></tt></a> is used to hold constant values that are not read from the command line but are required for the various ArgumentParser actions. The two most common uses of it are:</p>
<ul class="simple">
<li>When <a title="add_argument" class="reference internal" href="#add_argument"><tt class="xref docutils literal"><span class="pre">add_argument()</span></tt></a> is called with <tt class="docutils literal"><span class="pre">action='store_const'</span></tt> or <tt class="docutils literal"><span class="pre">action='append_const'</span></tt>. These actions add the <tt class="docutils literal"><span class="pre">const</span></tt> value to one of the attributes of the object returned by <a title="parse_args" class="reference external" href="parse_args.html#parse_args"><tt class="xref docutils literal"><span class="pre">parse_args()</span></tt></a>. See the <a class="reference internal" href="#action">action</a> description for examples.</li>
<li>When <a title="add_argument" class="reference internal" href="#add_argument"><tt class="xref docutils literal"><span class="pre">add_argument()</span></tt></a> is called with option strings (like <tt class="docutils literal"><span class="pre">-f</span></tt> or <tt class="docutils literal"><span class="pre">--foo</span></tt>) and <tt class="docutils literal"><span class="pre">nargs='?'</span></tt>. This creates an optional argument that can be followed by zero or one command-line args. When parsing the command-line, if the option string is encountered with no command-line arg following it, the value of <tt class="docutils literal"><span class="pre">const</span></tt> will be assumed instead. See the <a class="reference internal" href="#nargs">nargs</a> description for examples.</li>
</ul>
<p>The <tt class="docutils literal"><span class="pre">const</span></tt> keyword argument defaults to <tt class="xref docutils literal"><span class="pre">None</span></tt>.</p>
</div>
<div class="section" id="default">
<h2>default<a class="headerlink" href="#default" title="Permalink to this headline">¶</a></h2>
<p>All optional arguments and some positional arguments may be omitted at the command-line. The <tt class="docutils literal"><span class="pre">default</span></tt> keyword argument of <a title="add_argument" class="reference internal" href="#add_argument"><tt class="xref docutils literal"><span class="pre">add_argument()</span></tt></a>, whose value defaults to <tt class="xref docutils literal"><span class="pre">None</span></tt>, specifies what value should be used if the command-line arg is not present. For optional arguments, the <tt class="docutils literal"><span class="pre">default</span></tt> value is used when the option string was not present at the command line:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'--foo'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mf">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="s">'--foo 2'</span><span class="o">.</span><span class="n">split</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="s">''</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(foo=42)</span>
</pre></div>
</div>
<p>For positional arguments with <a class="reference internal" href="#nargs">nargs</a> <tt class="docutils literal"><span class="pre">='?'</span></tt> or <tt class="docutils literal"><span class="pre">'*'</span></tt>, the <tt class="docutils literal"><span class="pre">default</span></tt> value is used when no command-line arg was present:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'foo'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s">'?'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mf">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="s">'a'</span><span class="o">.</span><span class="n">split</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="s">''</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(foo=42)</span>
</pre></div>
</div>
<p>If you don’t want to see an attribute when an option was not present at the command line, you can supply <tt class="docutils literal"><span class="pre">default=argparse.SUPPRESS</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'--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="s">'--foo'</span><span class="p">,</span> <span class="s">'1'</span><span class="p">])</span>
<span class="go">Namespace(foo='1')</span>
</pre></div>
</div>
</div>
<div class="section" id="type">
<h2>type<a class="headerlink" href="#type" title="Permalink to this headline">¶</a></h2>
<p>By default, ArgumentParser objects read command-line args in as simple strings. However, quite often the command-line string should instead be interpreted as another type, e.g. <tt class="docutils literal"><span class="pre">float</span></tt>, <tt class="docutils literal"><span class="pre">int</span></tt> or <tt class="docutils literal"><span class="pre">file</span></tt>. The <tt class="docutils literal"><span class="pre">type</span></tt> keyword argument of <a title="add_argument" class="reference internal" href="#add_argument"><tt class="xref docutils literal"><span class="pre">add_argument()</span></tt></a> allows any necessary type-checking and type-conversions to be performed. Many common builtin types can be used directly as the value of the <tt class="docutils literal"><span class="pre">type</span></tt> argument:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'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="s">'bar'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">file</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="s">'2 temp.txt'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(bar=<open file 'temp.txt', mode 'r' at 0x...>, foo=2)</span>
</pre></div>
</div>
<p>To ease the use of various types of files, the argparse module provides the factory FileType which takes the <tt class="docutils literal"><span class="pre">mode=</span></tt> and <tt class="docutils literal"><span class="pre">bufsize=</span></tt> arguments of the <tt class="docutils literal"><span class="pre">file</span></tt> object. For example, <tt class="docutils literal"><span class="pre">FileType('w')</span></tt> can be used to create a writable file:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'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="s">'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="s">'out.txt'</span><span class="p">])</span>
<span class="go">Namespace(bar=<open file 'out.txt', mode 'w' at 0x...>)</span>
</pre></div>
</div>
<p>If you need to do some special type-checking or type-conversions, you can provide your own types by passing to <tt class="docutils literal"><span class="pre">type=</span></tt> a callable that takes a single string argument and returns the type-converted value:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">"</span><span class="si">%r</span><span class="s"> 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="s">'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="s">'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="s">'9'</span><span class="o">.</span><span class="n">split</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="s">'7'</span><span class="o">.</span><span class="n">split</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>Note that if your type-checking function is just checking for a particular set of values, it may be more convenient to use the <a class="reference internal" href="#choices">choices</a> keyword argument:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'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="s">'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">xrange</span><span class="p">(</span><span class="mf">5</span><span class="p">,</span> <span class="mf">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="s">'7'</span><span class="o">.</span><span class="n">split</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="s">'11'</span><span class="o">.</span><span class="n">split</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">
<h2>choices<a class="headerlink" href="#choices" title="Permalink to this headline">¶</a></h2>
<p>Some command-line args should be selected from a restricted set of values. ArgumentParser objects can be told about such sets of values by passing a container object as the <tt class="docutils literal"><span class="pre">choices</span></tt> keyword argument to <a title="add_argument" class="reference internal" href="#add_argument"><tt class="xref docutils literal"><span class="pre">add_argument()</span></tt></a>. When the command-line is parsed with <a title="parse_args" class="reference external" href="parse_args.html#parse_args"><tt class="xref docutils literal"><span class="pre">parse_args()</span></tt></a>, arg values will be checked, and an error message will be displayed if the arg was not one of the acceptable values:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'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="s">'foo'</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="s">'abc'</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="s">'c'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(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="s">'X'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">usage: PROG [-h] {a,b,c}</span>
<span class="go">PROG: error: argument foo: invalid choice: 'X' (choose from 'a', 'b', 'c')</span>
</pre></div>
</div>
<p>Note that inclusion in the <tt class="docutils literal"><span class="pre">choices</span></tt> 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 <tt class="docutils literal"><span class="pre">choices</span></tt> container should match the <a class="reference internal" href="#type">type</a> specified:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'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="s">'foo'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">complex</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="p">[</span><span class="mf">1</span><span class="p">,</span> <span class="mf">1</span><span class="n">j</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="s">'1j'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(foo=1j)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s">'-- -4'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">usage: PROG [-h] {1,1j}</span>
<span class="go">PROG: error: argument foo: invalid choice: (-4+0j) (choose from 1, 1j)</span>
</pre></div>
</div>
<p>Any object that supports the <tt class="docutils literal"><span class="pre">in</span></tt> operator can be passed as the <tt class="docutils literal"><span class="pre">choices</span></tt> value, so <tt class="docutils literal"><span class="pre">dict</span></tt> objects, <tt class="docutils literal"><span class="pre">set</span></tt> objects, custom containers, etc. are all supported.</p>
</div>
<div class="section" id="required">
<h2>required<a class="headerlink" href="#required" title="Permalink to this headline">¶</a></h2>
<p>In general, the argparse module assumes that flags like <tt class="docutils literal"><span class="pre">-f</span></tt> and <tt class="docutils literal"><span class="pre">--bar</span></tt> indicate <em>optional</em> arguments, which can always be omitted at the command-line. To change this behavior, i.e. to make an option <em>required</em>, the value <tt class="xref docutils literal"><span class="pre">True</span></tt> should be specified for the <tt class="docutils literal"><span class="pre">required=</span></tt> keyword argument to <a title="add_argument" class="reference internal" href="#add_argument"><tt class="xref docutils literal"><span class="pre">add_argument()</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'--foo'</span><span class="p">,</span> <span class="n">required</span><span class="o">=</span><span class="bp">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="s">'--foo'</span><span class="p">,</span> <span class="s">'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 <tt class="docutils literal"><span class="pre">required</span></tt>, <a title="parse_args" class="reference external" href="parse_args.html#parse_args"><tt class="xref docutils literal"><span class="pre">parse_args()</span></tt></a> will report an error if that option is not present at the command line.</p>
<p><strong>Warning:</strong> Required options are generally considered bad form - normal users expect <em>options</em> to be <em>optional</em>. You should avoid the use of required options whenever possible.</p>
</div>
<div class="section" id="help">
<h2>help<a class="headerlink" href="#help" title="Permalink to this headline">¶</a></h2>
<p>A great command-line interface isn’t worth anything if your users can’t figure out which option does what. So for the end-users, <tt class="docutils literal"><span class="pre">help</span></tt> is probably the most important argument to include in your <a title="add_argument" class="reference internal" href="#add_argument"><tt class="xref docutils literal"><span class="pre">add_argument()</span></tt></a> calls. The <tt class="docutils literal"><span class="pre">help</span></tt> value should be a string containing a brief description of what the argument specifies. When a user requests help (usually by using <tt class="docutils literal"><span class="pre">-h</span></tt> or <tt class="docutils literal"><span class="pre">--help</span></tt> at the command-line), these <tt class="docutils literal"><span class="pre">help</span></tt> descriptions will be displayed with each argument:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'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="s">'--foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_true'</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">help</span><span class="o">=</span><span class="s">'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="s">'bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s">'+'</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">help</span><span class="o">=</span><span class="s">'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="s">'-h'</span><span class="o">.</span><span class="n">split</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 <tt class="docutils literal"><span class="pre">help</span></tt> 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, <tt class="docutils literal"><span class="pre">%(prog)s</span></tt> and most keyword arguments to <a title="add_argument" class="reference internal" href="#add_argument"><tt class="xref docutils literal"><span class="pre">add_argument()</span></tt></a>, e.g. <tt class="docutils literal"><span class="pre">%(default)s</span></tt>, <tt class="docutils literal"><span class="pre">%(type)s</span></tt>, etc.:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'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="s">'bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s">'?'</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="mf">42</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">help</span><span class="o">=</span><span class="s">'the bar to </span><span class="si">%(prog)s</span><span class="s"> (default: </span><span class="si">%(default)s</span><span class="s">)'</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>
</div>
<div class="section" id="metavar">
<h2>metavar<a class="headerlink" href="#metavar" title="Permalink to this headline">¶</a></h2>
<p>When ArgumentParser objects generate help messages, they need 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 if we have a single positional argument with <tt class="docutils literal"><span class="pre">dest='bar'</span></tt>, that argument will be referred to as <tt class="docutils literal"><span class="pre">bar</span></tt>. And if we have a single optional argument <tt class="docutils literal"><span class="pre">--foo</span></tt> that should be followed by a single command-line arg, that arg will be referred to as <tt class="docutils literal"><span class="pre">FOO</span></tt>. You can see this behavior in the example below:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'--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="s">'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="s">'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>If you would like to provide a different name for your argument in help messages, you can supply a value for the <tt class="docutils literal"><span class="pre">metavar</span></tt> keyword argument to <a title="add_argument" class="reference internal" href="#add_argument"><tt class="xref docutils literal"><span class="pre">add_argument()</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'--foo'</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s">'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="s">'bar'</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s">'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="s">'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 <tt class="docutils literal"><span class="pre">metavar</span></tt> only changes the <em>displayed</em> name - the name of the attribute on the <a title="parse_args" class="reference external" href="parse_args.html#parse_args"><tt class="xref docutils literal"><span class="pre">parse_args()</span></tt></a> object is still determined by the <a class="reference internal" href="#dest">dest</a> value.</p>
<p>Different values of <tt class="docutils literal"><span class="pre">nargs</span></tt> may cause the metavar to be used multiple times.
If you’d like to specify a different display name for each of the arguments, you can provide a tuple to <tt class="docutils literal"><span class="pre">metavar</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'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="s">'-x'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="mf">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="s">'--foo'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="mf">2</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="p">(</span><span class="s">'bar'</span><span class="p">,</span> <span class="s">'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">
<h2>dest<a class="headerlink" href="#dest" title="Permalink to this headline">¶</a></h2>
<p>Most ArgumentParser actions add some value as an attribute of the object returned by <a title="parse_args" class="reference external" href="parse_args.html#parse_args"><tt class="xref docutils literal"><span class="pre">parse_args()</span></tt></a>. The name of this attribute is determined by the <tt class="docutils literal"><span class="pre">dest</span></tt> keyword argument of <a title="add_argument" class="reference internal" href="#add_argument"><tt class="xref docutils literal"><span class="pre">add_argument()</span></tt></a>. For positional argument actions, <tt class="docutils literal"><span class="pre">dest</span></tt> is normally supplied as the first argument to <a title="add_argument" class="reference internal" href="#add_argument"><tt class="xref docutils literal"><span class="pre">add_argument()</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'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="s">'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>
<p>For optional argument actions, the value of <tt class="docutils literal"><span class="pre">dest</span></tt> is normally inferred from the option strings. ArgumentParser objects generate the value of <tt class="docutils literal"><span class="pre">dest</span></tt> by taking the first long option string and stripping away the initial <tt class="docutils literal"><span class="pre">'--'</span></tt> string. If no long option strings were supplied, <tt class="docutils literal"><span class="pre">dest</span></tt> will be derived from the first short option string by stripping the initial <tt class="docutils literal"><span class="pre">'-'</span></tt> character. Any internal <tt class="docutils literal"><span class="pre">'-'</span></tt> characters will be converted to <tt class="docutils literal"><span class="pre">'_'</span></tt> characters to make sure the string is a valid attribute name. The examples below illustrate this behavior:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'-f'</span><span class="p">,</span> <span class="s">'--foo-bar'</span><span class="p">,</span> <span class="s">'--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="s">'-x'</span><span class="p">,</span> <span class="s">'-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="s">'-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="s">'--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>If you would like to use a different attribute name from the one automatically inferred by the ArgumentParser, you can supply it with an explicit <tt class="docutils literal"><span class="pre">dest</span></tt> parameter:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">'--foo'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">'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="s">'--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>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference external" href="">The add_argument() method</a><ul>
<li><a class="reference external" href="#name-or-flags">name or flags</a></li>
<li><a class="reference external" href="#action">action</a></li>
<li><a class="reference external" href="#nargs">nargs</a></li>
<li><a class="reference external" href="#const">const</a></li>
<li><a class="reference external" href="#default">default</a></li>
<li><a class="reference external" href="#type">type</a></li>
<li><a class="reference external" href="#choices">choices</a></li>
<li><a class="reference external" href="#required">required</a></li>
<li><a class="reference external" href="#help">help</a></li>
<li><a class="reference external" href="#metavar">metavar</a></li>
<li><a class="reference external" href="#dest">dest</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="ArgumentParser.html"
title="previous chapter">ArgumentParser objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="parse_args.html"
title="next chapter">The parse_args() method</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/add_argument.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="parse_args.html" title="The parse_args() method"
>next</a> |</li>
<li class="right" >
<a href="ArgumentParser.html" title="ArgumentParser objects"
>previous</a> |</li>
<li><a href="index.html">argparse v1.1 documentation</a> »</li>
<li><a href="api-docs.html" >API documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2006-2009, Steven Bethard.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.1.
</div>
</body>
</html>
