<!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 parse_args() 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="Other methods" href="other-methods.html" /> <link rel="prev" title="The add_argument() method" href="add_argument.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="other-methods.html" title="Other methods" accesskey="N">next</a> |</li> <li class="right" > <a href="add_argument.html" title="The add_argument() method" 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-parse-args-method"> <h1>The parse_args() method<a class="headerlink" href="#the-parse-args-method" title="Permalink to this headline">¶</a></h1> <dl class="method"> <dt id="parse_args"> <tt class="descname">parse_args</tt><big>(</big><span class="optional">[</span><em>args</em><span class="optional">]</span><span class="optional">[</span>, <em>namespace</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#parse_args" title="Permalink to this definition">¶</a></dt> <dd><p>Convert the strings to objects and assign them as attributes of the namespace. Return the populated namespace.</p> <p>Previous calls to <a title="add_argument" class="reference external" href="add_argument.html#add_argument"><tt class="xref docutils literal"><span class="pre">add_argument()</span></tt></a> determine exactly what objects are created and how they are assigned. See the documentation for <a title="add_argument" class="reference external" href="add_argument.html#add_argument"><tt class="xref docutils literal"><span class="pre">add_argument()</span></tt></a> for details.</p> <p>By default, the arg strings are taken from <tt class="docutils literal"><span class="pre">sys.argv</span></tt>, and a new empty <tt class="docutils literal"><span class="pre">Namespace</span></tt> object is created for the attributes.</p> </dd></dl> <div class="section" id="option-value-syntax"> <h2>Option value syntax<a class="headerlink" href="#option-value-syntax" title="Permalink to this headline">¶</a></h2> <p>The <a title="parse_args" class="reference internal" href="#parse_args"><tt class="xref docutils literal"><span class="pre">parse_args()</span></tt></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-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="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">'-x X'</span><span class="o">.</span><span class="n">split</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="s">'--foo FOO'</span><span class="o">.</span><span class="n">split</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), you may also pass the option and value as a single command line argument, using <tt class="docutils literal"><span class="pre">=</span></tt> to separate them:</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">parse_args</span><span class="p">(</span><span class="s">'--foo=FOO'</span><span class="o">.</span><span class="n">split</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), you may simply concatenate the option and its value:</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">parse_args</span><span class="p">(</span><span class="s">'-xX'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span> <span class="go">Namespace(foo=None, x='X')</span> </pre></div> </div> <p>You can also combine several short options together, using only a single <tt class="docutils literal"><span class="pre">-</span></tt> prefix, as long as only the last option (or none of them) requires a value:</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">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">'-y'</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">'-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="s">'-xyzZ'</span><span class="o">.</span><span class="n">split</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"> <h2>Invalid arguments<a class="headerlink" href="#invalid-arguments" title="Permalink to this headline">¶</a></h2> <p>While parsing the command-line, <tt class="docutils literal"><span class="pre">parse_args</span></tt> 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-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="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="c"># 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="s">'--foo'</span><span class="p">,</span> <span class="s">'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="c"># 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="s">'--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="c"># 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="s">'spam'</span><span class="p">,</span> <span class="s">'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"> <h2>Arguments containing <tt class="docutils literal"><span class="pre">"-"</span></tt><a class="headerlink" href="#arguments-containing" title="Permalink to this headline">¶</a></h2> <p>The <tt class="docutils literal"><span class="pre">parse_args</span></tt> method attempts to give errors whenever the user has clearly made a mistake, but some situations are inherently ambiguous. For example, the command-line arg <tt class="docutils literal"><span class="pre">'-1'</span></tt> could either be an attempt to specify an option or an attempt to provide a positional argument. The <tt class="docutils literal"><span class="pre">parse_args</span></tt> method is cautious here: positional arguments may only begin with <tt class="docutils literal"><span class="pre">'-'</span></tt> if they look like negative numbers and there are no options in the parser that look like negative numbers:</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="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="c"># 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="s">'-x'</span><span class="p">,</span> <span class="s">'-1'</span><span class="p">])</span> <span class="go">Namespace(foo=None, x='-1')</span> <span class="gp">>>> </span><span class="c"># 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="s">'-x'</span><span class="p">,</span> <span class="s">'-1'</span><span class="p">,</span> <span class="s">'-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="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">'-1'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">'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="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="c"># 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="s">'-1'</span><span class="p">,</span> <span class="s">'X'</span><span class="p">])</span> <span class="go">Namespace(foo=None, one='X')</span> <span class="gp">>>> </span><span class="c"># 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="s">'-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="c"># 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="s">'-1'</span><span class="p">,</span> <span class="s">'-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 <tt class="docutils literal"><span class="pre">'-'</span></tt> and don’t look like negative numbers, you can insert the pseudo-argument <tt class="docutils literal"><span class="pre">'--'</span></tt> which tells <tt class="docutils literal"><span class="pre">parse_args</span></tt> that everything after that is a positional 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">parse_args</span><span class="p">([</span><span class="s">'--'</span><span class="p">,</span> <span class="s">'-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"> <h2>Argument abbreviations<a class="headerlink" href="#argument-abbreviations" title="Permalink to this headline">¶</a></h2> <p>The <a title="parse_args" class="reference internal" href="#parse_args"><tt class="xref docutils literal"><span class="pre">parse_args()</span></tt></a> method allows you to abbreviate long options if the abbreviation is unambiguous:</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">'-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="s">'-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="s">'-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="s">'-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="s">'-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>As you can see above, you will get an error if you pick a prefix that could refer to more than one option.</p> </div> <div class="section" id="beyond-sys-argv"> <h2>Beyond <tt class="docutils literal"><span class="pre">sys.argv</span></tt><a class="headerlink" href="#beyond-sys-argv" title="Permalink to this headline">¶</a></h2> <p>Sometimes it may be useful to have an ArgumentParser parse args other than those of <tt class="docutils literal"><span class="pre">sys.argv</span></tt>. This can be accomplished by passing a list of strings to <tt class="docutils literal"><span class="pre">parse_args</span></tt>. You may have noticed that the examples in the argparse documentation have made heavy use of this calling style - it is much easier to use at the interactive prompt:</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="gp">... </span> <span class="s">'integers'</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s">'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">xrange</span><span class="p">(</span><span class="mf">10</span><span class="p">),</span> <span class="gp">... </span> <span class="n">nargs</span><span class="o">=</span><span class="s">'+'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s">'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="s">'--sum'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">'accumulate'</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="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="s">'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="s">'1'</span><span class="p">,</span> <span class="s">'2'</span><span class="p">,</span> <span class="s">'3'</span><span class="p">,</span> <span class="s">'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="s">'1 2 3 4 --sum'</span><span class="o">.</span><span class="n">split</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="custom-namespaces"> <h2>Custom namespaces<a class="headerlink" href="#custom-namespaces" title="Permalink to this headline">¶</a></h2> <p>It may also be useful to have an ArgumentParser assign attributes to an already existing object, rather than the newly-created Namespace object that is normally used. This can be achieved by specifying the <tt class="docutils literal"><span class="pre">namespace=</span></tt> keyword argument:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">C</span><span class="p">(</span><span class="nb">object</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="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="n">args</span><span class="o">=</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="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> </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 parse_args() method</a><ul> <li><a class="reference external" href="#option-value-syntax">Option value syntax</a></li> <li><a class="reference external" href="#invalid-arguments">Invalid arguments</a></li> <li><a class="reference external" href="#arguments-containing">Arguments containing <tt class="docutils literal"><span class="pre">"-"</span></tt></a></li> <li><a class="reference external" href="#argument-abbreviations">Argument abbreviations</a></li> <li><a class="reference external" href="#beyond-sys-argv">Beyond <tt class="docutils literal"><span class="pre">sys.argv</span></tt></a></li> <li><a class="reference external" href="#custom-namespaces">Custom namespaces</a></li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="add_argument.html" title="previous chapter">The add_argument() method</a></p> <h4>Next topic</h4> <p class="topless"><a href="other-methods.html" title="next chapter">Other methods</a></p> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="_sources/parse_args.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="other-methods.html" title="Other methods" >next</a> |</li> <li class="right" > <a href="add_argument.html" title="The add_argument() method" >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>