summaryrefslogtreecommitdiff
path: root/doc/parse_args.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/parse_args.html')
-rw-r--r--doc/parse_args.html220
1 files changed, 220 insertions, 0 deletions
diff --git a/doc/parse_args.html b/doc/parse_args.html
new file mode 100644
index 0000000..c5d9f17
--- /dev/null
+++ b/doc/parse_args.html
@@ -0,0 +1,220 @@
+<!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 &mdash; argparse v0.9.0 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: '0.9.0',
+ 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 v0.9.0 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 v0.9.0 documentation</a> &raquo;</li>
+ <li><a href="api-docs.html" accesskey="U">API documentation</a> &raquo;</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="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 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">&gt;&gt;&gt; </span><span class="n">parser</span> <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">&#39;PROG&#39;</span><span class="p">)</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">&#39;--foo&#39;</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">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">&#39;bar&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s">&#39;?&#39;</span><span class="p">)</span>
+
+<span class="gp">&gt;&gt;&gt; </span><span class="c"># invalid type</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">&#39;--foo&#39;</span><span class="p">,</span> <span class="s">&#39;spam&#39;</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: &#39;spam&#39;</span>
+
+<span class="gp">&gt;&gt;&gt; </span><span class="c"># invalid option</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">&#39;--bar&#39;</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">&gt;&gt;&gt; </span><span class="c"># wrong number of arguments</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">&#39;spam&#39;</span><span class="p">,</span> <span class="s">&#39;badger&#39;</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>
+<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">&gt;&gt;&gt; </span><span class="n">parser</span> <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">&#39;PROG&#39;</span><span class="p">)</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">&#39;-x&#39;</span><span class="p">)</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">&#39;foo&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s">&#39;?&#39;</span><span class="p">)</span>
+
+<span class="gp">&gt;&gt;&gt; </span><span class="c"># no negative number options, so -1 is a positional argument</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">&#39;-x&#39;</span><span class="p">,</span> <span class="s">&#39;-1&#39;</span><span class="p">])</span>
+<span class="go">Namespace(foo=None, x=&#39;-1&#39;)</span>
+
+<span class="gp">&gt;&gt;&gt; </span><span class="c"># no negative number options, so -1 and -5 are positional arguments</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">&#39;-x&#39;</span><span class="p">,</span> <span class="s">&#39;-1&#39;</span><span class="p">,</span> <span class="s">&#39;-5&#39;</span><span class="p">])</span>
+<span class="go">Namespace(foo=&#39;-5&#39;, x=&#39;-1&#39;)</span>
+
+<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span> <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">&#39;PROG&#39;</span><span class="p">)</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">&#39;-1&#39;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">&#39;one&#39;</span><span class="p">)</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">&#39;foo&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s">&#39;?&#39;</span><span class="p">)</span>
+
+<span class="gp">&gt;&gt;&gt; </span><span class="c"># negative number options present, so -1 is an option</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">&#39;-1&#39;</span><span class="p">,</span> <span class="s">&#39;X&#39;</span><span class="p">])</span>
+<span class="go">Namespace(foo=None, one=&#39;X&#39;)</span>
+
+<span class="gp">&gt;&gt;&gt; </span><span class="c"># negative number options present, so -2 is an option</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">&#39;-2&#39;</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">&gt;&gt;&gt; </span><span class="c"># negative number options present, so both -1s are options</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">&#39;-1&#39;</span><span class="p">,</span> <span class="s">&#39;-1&#39;</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&#8217;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">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">&#39;--&#39;</span><span class="p">,</span> <span class="s">&#39;-f&#39;</span><span class="p">])</span>
+<span class="go">Namespace(foo=&#39;-f&#39;, one=None)</span>
+</pre></div>
+</div>
+</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">&gt;&gt;&gt; </span><span class="n">parser</span> <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">&gt;&gt;&gt; </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">&#39;integers&#39;</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s">&#39;int&#39;</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">&#39;+&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s">&#39;an integer in the range 0..9&#39;</span><span class="p">)</span>
+<span class="gp">&gt;&gt;&gt; </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">&#39;--sum&#39;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">&#39;accumulate&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">&#39;store_const&#39;</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">&#39;sum the integers (default: find the max)&#39;</span><span class="p">)</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">&#39;1&#39;</span><span class="p">,</span> <span class="s">&#39;2&#39;</span><span class="p">,</span> <span class="s">&#39;3&#39;</span><span class="p">,</span> <span class="s">&#39;4&#39;</span><span class="p">])</span>
+<span class="go">Namespace(accumulate=&lt;built-in function max&gt;, integers=[1, 2, 3, 4])</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s">&#39;1 2 3 4 --sum&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
+<span class="go">Namespace(accumulate=&lt;built-in function sum&gt;, 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">&gt;&gt;&gt; </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">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">C</span><span class="p">()</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span> <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">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">&#39;--foo&#39;</span><span class="p">)</span>
+<span class="gp">&gt;&gt;&gt; </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">&#39;--foo&#39;</span><span class="p">,</span> <span class="s">&#39;BAR&#39;</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">&gt;&gt;&gt; </span><span class="n">c</span><span class="o">.</span><span class="n">foo</span>
+<span class="go">&#39;BAR&#39;</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="#invalid-arguments">Invalid arguments</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 v0.9.0 documentation</a> &raquo;</li>
+ <li><a href="api-docs.html" >API documentation</a> &raquo;</li>
+ </ul>
+ </div>
+ <div class="footer">
+ &copy; Copyright 2006-2009, Steven Bethard.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.1.
+ </div>
+ </body>
+</html> \ No newline at end of file