Describe the syntax of option strings on the command line.

Include documentation for FileType.

10 files changed, 196 insertions, 8 deletions

diff --git a/doc/add_argument.html b/doc/add_argument.html
index 89026ad..083ac90 100644
--- a/doc/add_argument.html
+++ b/doc/add_argument.html
@@ -51,9 +51,10 @@
 <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><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>
+<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>
@@ -68,9 +69,33 @@
 <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&#8217;re expecting an optional argument, e.g. <tt class="docutils literal"><span class="pre">-f</span></tt> or <a href="#id1"><span class="problematic" id="id2">``</span></a>&#8211;foo`, 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">&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;-f&#39;</span><span class="p">,</span> <span class="s">&#39;--foo&#39;</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">&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>
+</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">&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;-f&#39;</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">add_argument</span><span class="p">(</span><span class="s">&#39;bar&#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;BAR&#39;</span><span class="p">])</span>
+<span class="go">Namespace(bar=&#39;BAR&#39;, foo=None)</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="s">&#39;--foo&#39;</span><span class="p">,</span> <span class="s">&#39;FOO&#39;</span><span class="p">])</span>
+<span class="go">Namespace(bar=&#39;BAR&#39;, foo=&#39;FOO&#39;)</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;FOO&#39;</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>ArgumentParser 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>
+<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&#8217;s value. This is the default action. For example:</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>
@@ -434,6 +459,7 @@
             <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>
diff --git a/doc/api-docs.html b/doc/api-docs.html
index 70173aa..8b62f39 100644
--- a/doc/api-docs.html
+++ b/doc/api-docs.html
@@ -63,6 +63,7 @@
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference external" href="add_argument.html">The add_argument() method</a><ul>
+<li class="toctree-l2"><a class="reference external" href="add_argument.html#name-or-flags">name or flags</a></li>
 <li class="toctree-l2"><a class="reference external" href="add_argument.html#action">action</a></li>
 <li class="toctree-l2"><a class="reference external" href="add_argument.html#nargs">nargs</a></li>
 <li class="toctree-l2"><a class="reference external" href="add_argument.html#const">const</a></li>
@@ -76,7 +77,10 @@
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference external" href="parse_args.html">The parse_args() method</a><ul>
+<li class="toctree-l2"><a class="reference external" href="parse_args.html#option-value-syntax">Option value syntax</a></li>
 <li class="toctree-l2"><a class="reference external" href="parse_args.html#invalid-arguments">Invalid arguments</a></li>
+<li class="toctree-l2"><a class="reference external" href="parse_args.html#arguments-containing">Arguments containing <tt class="docutils literal"><span class="pre">&quot;-&quot;</span></tt></a></li>
+<li class="toctree-l2"><a class="reference external" href="parse_args.html#argument-abbreviations">Argument abbreviations</a></li>
 <li class="toctree-l2"><a class="reference external" href="parse_args.html#beyond-sys-argv">Beyond <tt class="docutils literal"><span class="pre">sys.argv</span></tt></a></li>
 <li class="toctree-l2"><a class="reference external" href="parse_args.html#custom-namespaces">Custom namespaces</a></li>
 </ul>
@@ -88,6 +92,10 @@
 <li class="toctree-l2"><a class="reference external" href="other-methods.html#mutual-exclusion">Mutual exclusion</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference external" href="other-utilities.html">Other utilities</a><ul>
+<li class="toctree-l2"><a class="reference external" href="other-utilities.html#filetype-objects">FileType objects</a></li>
+</ul>
+</li>
 </ul>
 </div>
 
diff --git a/doc/genindex.html b/doc/genindex.html
index ba4170a..9d2896f 100644
--- a/doc/genindex.html
+++ b/doc/genindex.html
@@ -40,7 +40,7 @@
 
    <h1 id="index">Index</h1>
 
-   <a href="#A"><strong>A</strong></a> | <a href="#P"><strong>P</strong></a> | <a href="#S"><strong>S</strong></a> 
+   <a href="#A"><strong>A</strong></a> | <a href="#F"><strong>F</strong></a> | <a href="#P"><strong>P</strong></a> | <a href="#S"><strong>S</strong></a> 
 
    <hr />
 
@@ -56,6 +56,13 @@
 <dt><a href="ArgumentParser.html#ArgumentParser">ArgumentParser (built-in class)</a></dt>
 </dl></td></tr></table>
 
+<h2 id="F">F</h2>
+<table width="100%" class="indextable"><tr><td width="33%" valign="top">
+<dl>
+
+<dt><a href="other-utilities.html#FileType">FileType (built-in class)</a></dt></dl></td><td width="33%" valign="top"><dl>
+</dl></td></tr></table>
+
 <h2 id="P">P</h2>
 <table width="100%" class="indextable"><tr><td width="33%" valign="top">
 <dl>
diff --git a/doc/index.html b/doc/index.html
index b03eb7e..e252e53 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -59,6 +59,7 @@
 <li class="toctree-l2"><a class="reference external" href="add_argument.html">The add_argument() method</a></li>
 <li class="toctree-l2"><a class="reference external" href="parse_args.html">The parse_args() method</a></li>
 <li class="toctree-l2"><a class="reference external" href="other-methods.html">Other methods</a></li>
+<li class="toctree-l2"><a class="reference external" href="other-utilities.html">Other utilities</a></li>
 </ul>
 </li>
 </ul>
diff --git a/doc/other-methods.html b/doc/other-methods.html
index ef547da..dd9397d 100644
--- a/doc/other-methods.html
+++ b/doc/other-methods.html
@@ -21,6 +21,7 @@
     <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 utilities" href="other-utilities.html" />
     <link rel="prev" title="The parse_args() method" href="parse_args.html" /> 
   </head>
   <body>
@@ -31,6 +32,9 @@
           <a href="genindex.html" title="General Index"
              accesskey="I">index</a></li>
         <li class="right" >
+          <a href="other-utilities.html" title="Other utilities"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
           <a href="parse_args.html" title="The parse_args() method"
              accesskey="P">previous</a> |</li>
         <li><a href="index.html">argparse v0.9.0 documentation</a> &raquo;</li>
@@ -273,6 +277,9 @@
             <h4>Previous topic</h4>
             <p class="topless"><a href="parse_args.html"
                                   title="previous chapter">The parse_args() method</a></p>
+            <h4>Next topic</h4>
+            <p class="topless"><a href="other-utilities.html"
+                                  title="next chapter">Other utilities</a></p>
             <h3>This Page</h3>
             <ul class="this-page-menu">
               <li><a href="_sources/other-methods.txt"
@@ -302,6 +309,9 @@
           <a href="genindex.html" title="General Index"
              >index</a></li>
         <li class="right" >
+          <a href="other-utilities.html" title="Other utilities"
+             >next</a> |</li>
+        <li class="right" >
           <a href="parse_args.html" title="The parse_args() method"
              >previous</a> |</li>
         <li><a href="index.html">argparse v0.9.0 documentation</a> &raquo;</li>
diff --git a/doc/parse_args.html b/doc/parse_args.html
index c5d9f17..8c395c6 100644
--- a/doc/parse_args.html
+++ b/doc/parse_args.html
@@ -57,9 +57,41 @@
 <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">&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="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 X&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
+<span class="go">Namespace(foo=None, x=&#39;X&#39;)</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 FOO&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
+<span class="go">Namespace(foo=&#39;FOO&#39;, 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">&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=FOO&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
+<span class="go">Namespace(foo=&#39;FOO&#39;, 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">&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;-xX&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
+<span class="go">Namespace(foo=None, x=&#39;X&#39;)</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">&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="n">action</span><span class="o">=</span><span class="s">&#39;store_true&#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;-y&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">&#39;store_true&#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;-z&#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;-xyzZ&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
+<span class="go">Namespace(x=True, y=True, z=&#39;Z&#39;)</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 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>
+<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">&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>
@@ -80,6 +112,9 @@
 <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">&quot;-&quot;</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">&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>
@@ -118,6 +153,23 @@
 </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">&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;-bacon&#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;-badger&#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;-bac MMM&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
+<span class="go">Namespace(bacon=&#39;MMM&#39;, badger=None)</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;-bad WOOD&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
+<span class="go">Namespace(bacon=None, badger=&#39;WOOD&#39;)</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;-ba BA&#39;</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>
@@ -161,7 +213,10 @@
             <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">&quot;-&quot;</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>
diff --git a/doc/searchindex.js b/doc/searchindex.js
index 46b203b..926a85a 100644
--- a/doc/searchindex.js
+++ b/doc/searchindex.js
@@ -1 +1 @@
-Search.setIndex({desctypes:{"0":"method","1":"class"},terms:{all:[5,3,6,4,2],code:[0,6,5],partial:6,messg:6,whatev:2,illustr:[6,4],global:5,four:4,prefix:5,follow:[0,6,4,5,3],formatter_class:[7,5],whose:[4,5],typeerror:4,"const":[7,3,6,1,4],prefix_char:[7,6,5],program:[5,0,4,2,3],those:[6,1],sens:4,worth:4,consum:[6,4],everi:3,string:[3,6,1,5,4],fals:[5,6,4,2],subcommand:6,prog:[1,2,4,5,6,7],default_:5,exact:6,implement:4,level:2,list:[1,2,3,4,5,6],"try":[6,5],item:4,adjust:5,readi:3,pleas:5,subparser_nam:2,dogmat:6,past:6,zero:[6,4],fyoyo:6,group1:2,pass:[6,1,5,4],append:4,compat:6,what:[3,6,1,5,4],abc:[6,4],sub:[7,6,2],neg:1,section:[5,6,4,2],advanc:6,brief:[4,5],current:2,version:[7,5],"new":[6,1,5,4],method:[0,1,2,3,4,5,6,7],told:4,deriv:[6,4],gener:[0,6,4,5,3],never:6,here:[6,1],let:2,inher:1,path:6,along:1,standard:6,modifi:2,sinc:6,interpret:4,convert:[3,6,1,4],convers:4,later:3,action:[1,2,3,4,5,6,7],weird:5,commonli:4,regardless:5,extra:1,appli:4,modul:[0,6,4,3],prefer:6,"while":[6,1],api:[7,0,6,4],txt:[0,4],select:[4,2],add_argument_group:2,from:[1,2,3,4,5,6],describ:[5,4,2],would:[6,4],frobbl:[4,2],two:[3,4,5],few:[6,4],call:[0,1,2,3,4,5,6],add_help:[7,6,5,2],recommend:2,taken:[6,1,4],care:6,type:[0,1,2,3,4,5,6,7],tell:[3,1],more:[0,6,4,5,3],sort:[3,4,5],parser_a:2,parser_b:2,line:[0,1,2,3,4,5,6],notic:[6,1],warn:4,flag:[6,4],indic:[5,4,2],particular:[6,4,2],known:6,hold:[3,4],easiest:[6,4,2],must:1,dictat:6,none:[6,1,5,4],word:5,work:[5,2],conceptu:2,remain:[3,6],kwarg:[6,2],can:[0,1,2,3,4,5,6],def:[6,4,2],overrid:[6,5,2],omit:4,prompt:1,puriti:6,give:[1,5],frabbl:3,share:[6,5],add_argu:[0,1,2,3,4,5,6,7],accept:[6,4,2],cautiou:1,want:[3,6,4,5],alwai:[5,4,2],multipl:[6,4,2],turn:3,rather:[1,5],anoth:[4,5],check_method:6,fooaction:[6,4],write:[0,6,3],how:[3,1,5,4],"__init__":6,instead:[6,4],narg:[0,1,3,4,5,6,7],simpl:[0,6,4,3],updat:2,parser_abc:6,foo_pars:[6,5],overridden:5,mess:5,max:[3,1],after:[5,6,1,2,4],befor:[4,5],wrong:1,okai:5,mai:[5,6,1,2,4],end:[6,4,2],associ:[4,2],xfoox:6,"0x013a2410":4,"short":[4,5],store_tru:[3,6,4,2],practic:6,read:4,stdin:4,explicit:4,correspond:[3,6],ambigu:1,caus:5,inform:[3,6],type_:[],maintain:[6,5],combin:2,allow:[5,6,4,2],callabl:[6,4],origin:6,least:[4,2],help:[0,1,2,3,4,5,6,7],over:6,becaus:5,through:6,sqrt:4,hierarchi:6,metavar_:[],still:4,subparser2:2,subparser1:2,paramet:[6,4,5],style:1,interspers:6,group:[7,2],fit:5,better:[6,2],foo_bar_baz_pars:6,easier:1,them:[0,4,1,5,3],good:2,"return":[3,6,1,2,4],thei:[6,1,5,4],python:[0,6,5,2],initi:[3,4],option_str:[6,4],now:[3,6],discuss:6,introduct:[0,3],choic:[1,2,3,4,6,7],allow_interspersed_arg:6,optionerror:6,name:[5,3,6,4,2],anyth:[6,4],choices_:[],separ:2,easili:6,achiev:[1,5],mode:[6,4],each:[5,3,6,4,2],fulli:2,complet:2,mean:[3,6,4],myprogram:5,replac:6,idea:2,heavi:1,expect:[3,1,4],our:3,happen:6,beyond:[7,1],metavar:[0,1,3,4,6,7],special:[4,2],out:[0,4,3],variabl:6,accomplish:[1,5],space:5,foo_bar:4,newli:1,parser_xyz:6,perfect_squar:4,print:[1,2,3,4,5,6],factori:4,math:4,optionvalueerror:6,worthwhil:6,situat:[1,4],given:5,argv:[7,3,1,5],infil:4,reason:6,base:6,dictionari:6,rawtexthelpformatt:5,indent:5,could:1,traceback:5,refus:6,thing:4,isn:[6,4],retain:5,const_:[],assign:1,first:4,oper:4,rang:[3,1],directli:4,carri:3,onc:3,number:[5,6,1,2,4],restrict:4,instruct:3,alreadi:[6,1,5],construct:[6,5],wasn:4,open:[6,4],differ:[6,4,2],script:3,top:2,sometim:[5,1,2],messag:[0,1,2,4,5,6],too:4,similarli:2,conveni:[6,4],store:[3,4],monkei:6,option:[0,1,2,3,4,5,6],namespac:[1,2,3,4,5,6,7],copi:6,specifi:[0,1,2,3,4,5,6],pars:[0,1,2,3,4,6],attempt:[6,1],exactli:[3,1,5],than:[5,6,1,2,4],wide:5,kind:2,setattr:[6,4],whenev:[1,4],provid:[0,6,1,2,4],remov:5,charact:[6,4,5],str:4,were:4,posit:[0,1,2,3,4,5,6],seri:3,sai:6,behavior:[3,4,5],group2:2,argument:[0,1,2,3,4,5,6,7],dash:6,add_pars:[6,2],manner:[3,6],have:[6,1,5,4],"__main__":[0,3],need:[5,6,4,2],seem:6,probabl:4,built:[3,1],callback:6,self:[6,4],append_const:4,also:[5,1,2,4],builtin:4,without:2,take:[5,3,6,4,2],which:[5,6,1,2,4],singl:[5,3,6,4,2],uppercas:4,begin:[3,1],sure:[6,4,2],though:4,previou:[6,1],most:[5,3,6,4,2],regular:2,pair:[6,5],choos:[6,4],"class":[6,1,5,4],don:[6,1,4],gather:4,request:[4,2],doe:[6,4,5],declar:6,determin:[1,2,3,4,5,6],occasion:5,sum:[0,1,3],"0x00b8fb18":4,parser_bar:2,show:[5,0,6,4,2],text:5,filetyp:[0,4],syntax:6,particularli:[6,2],hack:6,find:[3,1,2],onli:[5,6,1,2,4],execut:2,pretti:3,"true":[5,3,6,4,2],parser_foo:2,written:0,should:[0,2,3,4,5,6],store_const:[3,6,1,4],dict:4,"__call__":[6,4],add_opt:6,variou:[4,5],get:[3,6,5],likewis:5,report:4,requir:[7,6,4,2],bar:[1,2,3,4,5,6],keyword:[1,2,3,4,5,6],baz:[6,4,2],dramat:6,patch:6,store_fals:[4,2],"default":[0,1,2,3,4,5,6,7],bad:4,calcul:5,common:[3,4,5],contain:[5,6,4,2],where:[0,4,5],set:[5,3,6,4,2],see:[1,2,3,4,5,6],arg:[0,1,2,3,4,5,6],close:0,parent:[7,6,5,2],correctli:5,someth:3,figur:4,subdir:5,between:5,"import":[0,6,4,5,3],awai:4,badger:[6,1,2],across:5,attribut:[1,2,3,4,5,6],extend:[6,4],xrang:[3,6,1,4],disallow:[6,5],extens:6,outfil:4,come:6,addit:[5,6,4,2],both:[6,1],last:5,howev:[5,6,4,2],against:6,etc:[6,1,2,4],mani:[6,4],simpli:[6,4,5],point:6,within:5,argumentpars:[0,1,2,3,4,5,6,7],dispatch:6,suppli:[5,3,6,4,2],respect:4,assum:[0,4,3],duplic:6,quit:[6,4],coupl:[5,2],addition:4,empti:1,implicit:6,accumul:[3,1],secret:6,much:[3,6,1,4],valu:[6,1,5,4],basic:4,popul:1,strategi:5,epilog:[7,5],suppress:[6,4,5],xxx:[6,4,5],great:4,ani:[5,6,4,2],togeth:4,func:2,child:5,repetit:4,present:[6,1,2,4],"case":[3,4],main:2,look:[3,6,1],defin:[5,4,2],invok:[5,3,6,4,2],abov:[0,5,2,3],error:[5,6,1,2,4],argpars:[0,1,2,3,4,5,6],advantag:[0,6],stdout:[0,4],almost:[4,5],itself:4,sever:[5,2],disabl:5,clearli:1,perform:[4,2],make:[5,3,6,4,2],transpar:6,same:[6,4,5],handl:[6,4,2],complex:[6,4],help_:[],split:[1,2,3,4,5,6],document:[7,0,1],infer:4,dest_:[],difficult:6,dedent:5,effect:2,rais:[4,5],user:[5,6,1,2,4],store_act:6,typic:[3,6,4,2],recent:5,appropri:[0,2,3,4,5,6],older:5,thu:6,inherit:[6,5],exampl:[0,1,2,3,4,5],command:[0,1,2,3,4,5,6,7],thi:[0,1,2,3,4,5,6],conflict:5,everyth:[6,1],sibl:2,usual:[5,6,4,2],just:[4,2],object:[0,1,2,3,4,5,6,7],add_mutually_exclusive_group:2,note:[5,6,4,2],action_:[],exclus:[7,2],expos:6,had:6,except:5,add:[0,2,3,4,5,6],other:[7,0,6,1,2],remaining_arg:6,rawdescriptionhelpformatt:5,save:[0,3],match:[5,6,4,2],applic:5,format:[6,4,5],dest:[1,2,3,4,6,7],textwrap:5,test:6,know:[6,2],insert:[1,5],like:[1,2,3,4,5,6],specif:5,arbitrari:4,whitespac:5,manual:6,resolv:5,integ:[0,4,6,1,3],collect:5,necessari:[3,6,4,2],either:[3,6,1,5],argumenterror:[6,5],output:[4,5],unnecessari:5,encount:[3,1,4],old:[5,2],often:4,"0x00b1f020":4,interact:1,some:[1,2,3,4,5,6],back:2,intern:4,suppl:2,mistak:1,proper:6,librari:6,subpars:[6,2],avoid:4,normal:[1,2,4],definit:5,exit:[0,1,2,4,5,6],parent_pars:5,foo:[1,2,3,4,5,6],refer:4,nargs_:[],print_help:[5,6,4,2],run:[0,3],inspect:[3,2],usag:[0,1,2,4,5,6,7],argument_default:[7,5],found:1,add_subpars:[6,2],"__name__":[0,3],"super":6,about:[3,6,4],actual:6,callback_:6,optpars:[0,6],constructor:[6,5,2],commit:2,produc:[6,4],own:[6,4,5],xyz:[6,2],"float":[6,4,2],automat:4,upgrad:[0,6],been:[3,6,4],strip:4,wrap:5,chang:[5,6,4,2],mark:4,yyi:[4,5],your:[5,3,6,4,2],manag:3,inclus:4,log:0,wai:[5,6,4,2],spam:[6,1,2],support:[5,6,4,2],"long":[6,4],custom:[5,7,1,2,4],avail:[4,5],start:3,interfac:[0,6,4,3],includ:[5,6,1,2,4],lot:[6,2],parse_arg:[0,1,2,3,4,5,6,7],treat:2,"function":[1,2,4],svn:2,creation:[5,2],form:[3,6,4],bufsiz:4,parents_:[],"0x00b8fe78":4,eas:4,conflict_handl:[7,5],absent:4,made:1,input:4,temp:4,possibl:4,whether:[4,5],checkout:2,displai:[5,6,4,2],below:[6,4,5],otherwis:5,similar:6,featur:6,constant:4,creat:[0,1,2,3,4,5,6],"int":[0,1,2,3,4,5,6],pseudo:1,parser:[0,1,2,3,4,5,6,7],"0x00b1f068":4,doesn:[6,4],strongli:2,exist:1,file:[0,6,4,5,3],xyzyx:2,check:[6,1,2,4],fill:[3,5],again:6,mutual:[7,2],titl:2,when:[0,1,2,3,4,5,6],detail:[1,5,4],invalid:[7,6,1,4],valid:[6,4],futur:2,scriptnam:0,varieti:1,writabl:4,set_default:[5,2],you:[1,2,3,4,5,6],bar_pars:[6,5],repeat:5,clean:5,why:6,consid:[4,5],reduc:6,receiv:6,longer:[6,2],descript:[0,2,3,4,5,7],time:[6,4,2],backward:6},titles:["Documentation","The parse_args() method","Other methods","Introduction to argparse","The add_argument() method","ArgumentParser objects","argparse vs. optparse","API documentation"],modules:{},descrefs:{"":{parse_args:[1,0],add_mutually_exclusive_group:[2,0],set_defaults:[2,0],add_argument:[4,0],ArgumentParser:[5,1],add_subparsers:[2,0],add_argument_group:[2,0]}},filenames:["index","parse_args","other-methods","overview","add_argument","ArgumentParser","argparse-vs-optparse","api-docs"]})
\ No newline at end of file
+Search.setIndex({desctypes:{"0":"method","1":"class"},terms:{all:[6,3,7,5,2],code:[0,7,6],partial:7,messg:7,whatev:2,illustr:[7,5],global:6,four:5,prefix:[1,6,5],follow:[0,7,5,6,3],concaten:1,formatter_class:[8,6],whose:[5,6],typeerror:5,"const":[8,3,7,1,5],readabl:4,prefix_char:[8,7,6],program:[6,0,5,2,3],those:[7,1],sens:5,worth:5,consum:[7,5],everi:3,string:[3,7,1,6,5],fals:[6,7,5,2],subcommand:7,util:[8,0,4],prog:[1,2,5,6,7,8],default_:6,exact:7,implement:5,level:2,list:[1,2,3,5,6,7],"try":[7,6],item:5,adjust:6,readi:3,pleas:6,subparser_nam:2,bacon:1,dogmat:7,past:7,zero:[7,5],fyoyo:7,group1:2,pass:[4,7,1,6,5],append:5,compat:7,what:[3,7,1,6,5],abc:[7,5],sub:[8,7,2],neg:1,section:[6,7,5,2],advanc:7,brief:[5,6],current:2,abbrevi:[8,1],version:[8,6],"new":[7,1,6,5],method:[0,1,2,3,5,6,7,8],told:5,deriv:[7,5],gener:[0,7,5,6,3],never:7,here:[7,1],let:2,inher:1,path:7,along:1,standard:7,modifi:2,sinc:7,interpret:5,convert:[3,4,7,1,5],convers:5,pick:1,action:[1,2,3,5,6,7,8],weird:6,commonli:5,regardless:6,extra:1,appli:5,modul:[0,7,5,3],prefer:7,"while":[7,1,5],filenam:5,api:[8,0,7,5],txt:[0,5],select:[5,2],add_argument_group:2,from:[1,2,3,5,6,7],describ:[6,5,2],would:[7,5],frobbl:[5,2],two:[3,1,6,5],few:[7,5],call:[0,1,2,3,5,6,7],add_help:[8,7,6,2],recommend:2,taken:[7,1,5],care:7,type:[0,1,2,3,4,5,6,7,8],tell:[3,1],more:[0,1,3,5,6,7],sort:[3,5,6],parser_a:2,parser_b:2,line:[0,1,2,3,4,5,6,7],notic:[7,1],warn:5,flag:[8,7,5],indic:[6,5,2],particular:[7,5,2],known:7,hold:[3,5],easiest:[7,5,2],must:[1,5],dictat:7,none:[4,7,1,6,5],word:6,work:[6,2],conceptu:2,remain:[3,7,5],kwarg:[7,2],can:[0,1,2,3,4,5,6,7],def:[7,5,2],overrid:[7,6,2],omit:5,prompt:1,puriti:7,give:[1,6],frabbl:3,share:[7,6],add_argu:[0,1,2,3,4,5,6,7,8],accept:[7,5,2],cautiou:1,want:[3,7,5,6],alwai:[6,5,2],multipl:[7,5,2],turn:3,rather:[1,6],anoth:[5,6],check_method:7,fooaction:[7,5],write:[0,7,3],how:[3,1,6,5],"__init__":7,instead:[7,5],narg:[0,1,3,5,6,7,8],simpl:[0,7,5,3],updat:2,parser_abc:7,foo_pars:[7,6],overridden:6,mess:6,max:[3,1],after:[6,7,1,2,5],befor:[5,6],wrong:1,okai:6,mai:[6,7,1,2,5],end:[7,5,2],associ:[5,2],xfoox:7,"0x013a2410":5,"short":[1,6,5],store_tru:[3,7,1,2,5],practic:7,read:5,stdin:[4,5],explicit:5,correspond:[3,7],ambigu:1,caus:6,inform:[3,7],type_:[],maintain:[7,6],combin:[1,2],allow:[6,7,1,2,5],callabl:[7,5],origin:7,least:[5,2],help:[0,1,2,3,5,6,7,8],over:7,becaus:6,through:7,sqrt:5,hierarchi:7,metavar_:[],still:5,subparser2:2,subparser1:2,paramet:[7,5,6],style:1,interspers:7,group:[8,2],fit:6,better:[7,2],main:2,easier:1,them:[0,5,1,6,3],good:2,"return":[3,7,1,2,5],thei:[7,1,6,5],python:[0,7,6,2],initi:[3,5],option_str:[7,5],now:[3,7],discuss:7,introduct:[0,3],choic:[1,2,3,5,7,8],allow_interspersed_arg:7,optionerror:7,name:[1,2,3,5,6,7,8],anyth:[7,5],choices_:[],separ:[1,2],easili:7,achiev:[1,6],mode:[4,7,5],each:[6,3,7,5,2],fulli:2,complet:2,mean:[3,7,5],myprogram:6,replac:7,idea:2,heavi:1,expect:[3,1,5],our:3,happen:7,beyond:[8,1],metavar:[0,1,3,5,7,8],special:[5,2],out:[0,4,5,3],variabl:7,accomplish:[1,6],space:6,foo_bar:5,newli:1,parser_xyz:7,perfect_squar:5,print:[1,2,3,5,6,7],factori:[4,5],math:5,bac:1,optionvalueerror:7,worthwhil:7,situat:[1,5],given:6,argv:[8,3,1,6],infil:[4,5],mmm:1,reason:7,base:7,dictionari:7,rawtexthelpformatt:6,indent:6,could:[1,5],traceback:6,refus:7,thing:5,isn:[7,5],retain:6,const_:[],assign:1,first:5,oper:5,rang:[3,1],directli:5,carri:3,onc:3,number:[6,7,1,2,5],restrict:5,instruct:3,alreadi:[7,1,6],construct:[7,6],wasn:5,open:[4,7,5],size:4,differ:[7,5,2],script:3,top:2,sometim:[6,1,2],messag:[0,1,2,5,6,7],too:5,similarli:2,gather:5,conveni:[7,5],"final":[],store:[3,5],monkei:7,option:[0,1,2,3,5,6,7,8],namespac:[1,2,3,4,5,6,7,8],copi:7,specifi:[0,1,2,3,5,6,7],pars:[0,1,2,3,5,7],attempt:[7,1],exactli:[3,1,6],than:[6,7,1,2,5],wide:6,kind:2,setattr:[7,5],whenev:[1,5],provid:[0,7,1,2,5],remov:6,charact:[7,1,6,5],str:5,were:5,posit:[0,1,2,3,5,6,7],seri:[3,5],sai:7,behavior:[3,5,6],"0x013a2380":4,group2:2,argument:[0,1,2,3,4,5,6,7,8],dash:7,add_pars:[7,2],manner:[3,7],have:[4,7,1,6,5],"__main__":[0,3],need:[6,7,5,2],seem:7,probabl:5,built:[3,1],callback:7,self:[7,5],append_const:5,also:[6,1,2,5],builtin:5,without:2,take:[1,2,3,5,6,7],which:[6,7,1,2,5],singl:[1,2,3,5,6,7],uppercas:5,begin:[3,1],sure:[7,5,2],though:5,buffer:4,previou:[7,1],most:[6,3,7,5,2],regular:2,pair:[7,6],choos:[7,5],"class":[4,7,1,6,5],don:[7,1,5],later:3,request:[4,5,2],doe:[7,5,6],declar:7,determin:[1,2,3,5,6,7],occasion:6,sum:[0,1,3],"0x00b8fb18":5,parser_bar:2,show:[6,0,7,5,2],text:6,filetyp:[8,0,4,5],syntax:[8,7,1],particularli:[7,2],hack:7,find:[3,1,2],onli:[6,7,1,2,5],execut:2,pretti:3,"true":[1,2,3,5,6,7],parser_foo:2,written:0,should:[0,2,3,5,6,7],store_const:[3,7,1,5],wood:1,dict:5,"__call__":[7,5],add_opt:7,variou:[5,6],get:[3,7,1,6],likewis:6,report:5,requir:[8,7,1,2,5],bar:[1,2,3,5,6,7],keyword:[1,2,3,5,6,7],baz:[7,5,2],dramat:7,patch:7,store_fals:[5,2],"default":[0,1,2,3,5,6,7,8],bad:[1,5],calcul:6,common:[3,5,6],contain:[1,2,5,6,7,8],where:[0,5,6],set:[6,3,7,5,2],see:[1,2,3,5,6,7],arg:[0,1,2,3,4,5,6,7],close:0,parent:[8,7,6,2],correctli:6,someth:3,figur:5,subdir:6,between:6,"import":[0,7,5,6,3],awai:5,badger:[7,1,2],across:6,attribut:[1,2,3,5,6,7],extend:[7,5],xrang:[3,7,1,5],disallow:[7,6],extens:7,outfil:5,come:7,addit:[6,7,5,2],both:[7,1],last:[1,6],howev:[6,7,5,2],against:7,etc:[7,1,2,5],mani:[7,5],simpli:[7,1,6,5],point:7,within:6,argumentpars:[0,1,2,3,4,5,6,7,8],dispatch:7,suppli:[6,3,7,5,2],respect:5,assum:[0,5,3],duplic:7,quit:[7,5],coupl:[6,2],addition:5,empti:1,implicit:7,accumul:[3,1],secret:7,much:[3,7,1,5],valu:[8,7,1,6,5],basic:5,unambigu:1,popul:1,strategi:6,epilog:[8,6],suppress:[7,5,6],xxx:[7,5,6],great:5,ani:[6,7,5,2],understand:4,togeth:[1,5],func:2,child:6,repetit:5,present:[7,1,2,5],"case":[3,1,5],therefor:5,look:[3,7,1],defin:[6,5,2],invok:[6,3,7,5,2],abov:[6,0,1,2,3],error:[6,7,1,2,5],argpars:[0,1,2,3,4,5,6,7],advantag:[0,7],stdout:[0,4,5],almost:[5,6],itself:5,sever:[6,1,2],disabl:6,clearli:1,perform:[5,2],make:[6,3,7,5,2],transpar:7,same:[7,5,6],handl:[7,5,2],complex:[7,5],help_:[],split:[1,2,3,5,6,7],document:[8,0,1],infer:5,dest_:[],difficult:7,dedent:6,foo_bar_baz_pars:7,effect:2,rais:[5,6],user:[6,7,1,2,5],store_act:7,typic:[3,7,5,2],recent:6,appropri:[0,2,3,5,6,7],older:6,thu:7,inherit:[7,6],exampl:[0,1,2,3,5,6],command:[0,1,2,3,4,5,6,7,8],thi:[0,1,2,3,4,5,6,7],conflict:6,everyth:[7,1],sibl:2,usual:[6,7,5,2],identifi:5,just:[5,2],object:[0,1,2,3,4,5,6,7,8],add_mutually_exclusive_group:2,note:[6,7,5,2],action_:[],exclus:[8,2],expos:7,had:7,except:6,add:[0,2,3,5,6,7],other:[0,1,2,4,7,8],remaining_arg:7,rawdescriptionhelpformatt:6,save:[0,3],match:[6,7,1,2,5],applic:6,format:[7,5,6],dest:[1,2,3,5,7,8],textwrap:6,test:7,know:[7,5,2],insert:[1,6],like:[1,2,3,5,6,7],specif:6,arbitrari:5,whitespac:6,manual:7,resolv:6,integ:[0,5,7,1,3],collect:6,necessari:[3,7,5,2],either:[3,7,1,6,5],argumenterror:[7,6],output:[4,5,6],unnecessari:6,encount:[3,1,5],old:[6,2],often:5,"0x00b1f020":5,interact:1,some:[1,2,3,5,6,7],back:2,intern:5,suppl:2,mistak:1,proper:7,librari:7,subpars:[7,2],avoid:5,normal:[1,2,5],definit:6,exit:[0,1,2,5,6,7],parent_pars:6,foo:[1,2,3,5,6,7],refer:[1,5],nargs_:[],print_help:[6,7,5,2],run:[0,3],inspect:[3,2],usag:[0,1,2,5,6,7,8],argument_default:[8,6],found:1,add_subpars:[7,2],"__name__":[0,3],"super":7,xyzz:1,about:[3,7,5],simplest:1,actual:7,callback_:7,optpars:[0,7],constructor:[7,6,2],commit:2,produc:[7,5],own:[7,5,6],xyz:[7,2],"float":[7,5,2],automat:[4,5],upgrad:[0,7],been:[3,7,5],strip:5,wrap:6,chang:[6,7,5,2],mark:5,yyi:[5,6],your:[6,3,7,5,2],manag:3,inclus:5,log:0,wai:[6,7,1,2,5],spam:[7,1,2],support:[6,7,1,2,5],"long":[7,1,5],custom:[6,8,1,2,5],avail:[5,6],start:3,interfac:[0,7,5,3],includ:[6,7,1,2,5],lot:[7,2],parse_arg:[0,1,2,3,4,5,6,7,8],treat:2,"function":[1,2,5],svn:2,creation:[6,2],form:[3,7,5],bufsiz:[4,5],parents_:[],"0x00b8fe78":5,eas:5,conflict_handl:[8,6],absent:5,made:1,input:5,temp:5,possibl:5,whether:[5,6],checkout:2,displai:[6,7,5,2],below:[7,5,6],otherwis:6,similar:7,featur:7,constant:5,creat:[0,1,2,3,4,5,6,7],"int":[0,1,2,3,5,6,7],pseudo:[4,1],parser:[0,1,2,3,4,5,6,7,8],"0x00b1f068":5,doesn:[7,5],strongli:2,exist:1,file:[0,3,4,5,6,7],xyzyx:2,check:[7,1,2,5],fill:[3,6],again:7,mutual:[8,2],titl:2,when:[0,1,2,3,5,6,7],detail:[1,6,5],invalid:[8,7,1,5],valid:[7,5],futur:2,scriptnam:0,varieti:1,writabl:[4,5],set_default:[6,2],you:[1,2,3,5,6,7],bar_pars:[7,6],repeat:6,clean:6,why:7,consid:[5,6],"0x00adf020":4,reduc:7,receiv:7,longer:[7,1,2],descript:[0,2,3,5,6,8],time:[7,5,2],backward:7},titles:["Documentation","The parse_args() method","Other methods","Introduction to argparse","Other utilities","The add_argument() method","ArgumentParser objects","argparse vs. optparse","API documentation"],modules:{},descrefs:{"":{parse_args:[1,0],add_mutually_exclusive_group:[2,0],set_defaults:[2,0],FileType:[4,1],add_argument:[5,0],ArgumentParser:[6,1],add_subparsers:[2,0],add_argument_group:[2,0]}},filenames:["index","parse_args","other-methods","overview","other-utilities","add_argument","ArgumentParser","argparse-vs-optparse","api-docs"]})
\ No newline at end of file
diff --git a/doc/source/add_argument.rst b/doc/source/add_argument.rst
index a1eda68..5d01eb7 100644
--- a/doc/source/add_argument.rst
+++ b/doc/source/add_argument.rst
@@ -1,10 +1,11 @@
 The add_argument() method

 =========================

 

-.. method:: add_argument([action], [nargs], [const], [default], [type], [choices], [required], [help], [metavar], [dest])

+.. method:: add_argument(name or flags..., [action], [nargs], [const], [default], [type], [choices], [required], [help], [metavar], [dest])

 

    Define how a single command line argument should be parsed. Each parameter has its own more detailed description below, but in short they are:

    

+   * `name or flags`_ - Either a name or a list of option strings, e.g. ``foo`` or ``-f, --foo``

    * action_ - The basic type of action to be taken when this argument is encountered at the command-line.

    * nargs_ - The number of command-line arguments that should be consumed.

    * const_ - A constant value required by some action_ and nargs_ selections.

@@ -18,11 +19,34 @@ The add_argument() method
    

    The following sections describe how each of these are used.

 

+name or flags

+-------------

+

+The :meth:`add_argument` method needs to know whether you're expecting an optional argument, e.g. ``-f`` or ``--foo`, or a positional argument, e.g. a list of filenames. The first arguments passed to :meth:`add_argument` must therefore be either a series of flags, or a simple argument name. For example, an optional argument could be created like::

+

+  >>> parser.add_argument('-f', '--foo')

+

+while a positional argument could be created like::

+

+  >>> parser.add_argument('bar')

+

+When :meth:`parse_args` is called, optional arguments will be identified by the ``-`` prefix, and the remaining arguments will be assumed to be positional::

+

+  >>> parser = argparse.ArgumentParser(prog='PROG')

+  >>> parser.add_argument('-f', '--foo')

+  >>> parser.add_argument('bar')

+  >>> parser.parse_args(['BAR'])

+  Namespace(bar='BAR', foo=None)

+  >>> parser.parse_args(['BAR', '--foo', 'FOO'])

+  Namespace(bar='BAR', foo='FOO')

+  >>> parser.parse_args(['--foo', 'FOO'])

+  usage: PROG [-h] [-f FOO] bar

+  PROG: error: too few arguments

 

 action

 ------

 

-ArgumentParser 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 :meth:`parse_args`.  When you specify a new argument using the :meth:`add_argument` method, you can indicate how the command-line args should be handled by specifying the ``action`` keyword argument. The supported actions are:

+:class:`ArgumentParser` 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 :meth:`parse_args`.  When you specify a new argument using the :meth:`add_argument` method, you can indicate how the command-line args should be handled by specifying the ``action`` keyword argument. The supported actions are:

 

 * ``'store'`` - This just stores the argument's value. This is the default action. For example::

 

diff --git a/doc/source/api-docs.rst b/doc/source/api-docs.rst
index cb55a5a..2d6ded4 100644
--- a/doc/source/api-docs.rst
+++ b/doc/source/api-docs.rst
@@ -8,3 +8,4 @@ API documentation
     add_argument

     parse_args

     other-methods

+    other-utilities

diff --git a/doc/source/parse_args.rst b/doc/source/parse_args.rst
index d70ba89..9ce86f4 100644
--- a/doc/source/parse_args.rst
+++ b/doc/source/parse_args.rst
@@ -9,10 +9,43 @@ The parse_args() method
    

    By default, the arg strings are taken from ``sys.argv``, and a new empty ``Namespace`` object is created for the attributes.

 

+Option value syntax

+-------------------

+

+The :meth:`parse_args` 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::

+

+  >>> parser = argparse.ArgumentParser(prog='PROG')

+  >>> parser.add_argument('-x')

+  >>> parser.add_argument('--foo')

+  >>> parser.parse_args('-x X'.split())

+  Namespace(foo=None, x='X')

+  >>> parser.parse_args('--foo FOO'.split())

+  Namespace(foo='FOO', x=None)

+

+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 ``=`` to separate them::

+

+  >>> parser.parse_args('--foo=FOO'.split())

+  Namespace(foo='FOO', x=None)

+

+For short options (options only one character long), you may simply concatenate the option and its value::

+

+  >>> parser.parse_args('-xX'.split())

+  Namespace(foo=None, x='X')

+

+You can also combine several short options together, using only a single ``-`` prefix, as long as only the last option (or none of them) requires a value::

+

+  >>> parser = argparse.ArgumentParser(prog='PROG')

+  >>> parser.add_argument('-x', action='store_true')

+  >>> parser.add_argument('-y', action='store_true')

+  >>> parser.add_argument('-z')

+  >>> parser.parse_args('-xyzZ'.split())

+  Namespace(x=True, y=True, z='Z')

+

+

 Invalid arguments

 -----------------

 

-While parsing the command-line, ``parse_args`` 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::

+While parsing the command-line, ``parse_args`` 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::

 

   >>> parser = argparse.ArgumentParser(prog='PROG')

   >>> parser.add_argument('--foo', type=int)

@@ -33,6 +66,10 @@ While parsing the command-line, ``parse_args`` checks for a variety of errors, i
   usage: PROG [-h] [--foo FOO] [bar]

   PROG: error: extra arguments found: badger

 

+

+Arguments containing ``"-"``

+----------------------------

+

 The ``parse_args`` 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 ``'-1'`` could either be an attempt to specify an option or an attempt to provide a positional argument. The ``parse_args`` method is cautious here: positional arguments may only begin with ``'-'`` if they look like negative numbers and there are no options in the parser that look like negative numbers::

 

   >>> parser = argparse.ArgumentParser(prog='PROG')

@@ -71,6 +108,25 @@ If you have positional arguments that must begin with ``'-'`` and don't look lik
   Namespace(foo='-f', one=None)

 

 

+Argument abbreviations

+----------------------

+

+The :meth:`parse_args` method allows you to abbreviate long options if the abbreviation is unambiguous::

+

+  >>> parser = argparse.ArgumentParser(prog='PROG')

+  >>> parser.add_argument('-bacon')

+  >>> parser.add_argument('-badger')

+  >>> parser.parse_args('-bac MMM'.split())

+  Namespace(bacon='MMM', badger=None)

+  >>> parser.parse_args('-bad WOOD'.split())

+  Namespace(bacon=None, badger='WOOD')

+  >>> parser.parse_args('-ba BA'.split())

+  usage: PROG [-h] [-bacon BACON] [-badger BADGER]

+  PROG: error: ambiguous option: -ba could match -badger, -bacon

+

+As you can see above, you will get an error if you pick a prefix that could refer to more than one option.

+

+

 Beyond ``sys.argv``

 -------------------