<!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>Other methods — 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 utilities" href="other-utilities.html" />
<link rel="prev" title="The parse_args() method" href="parse_args.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-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 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="other-methods">
<h1>Other methods<a class="headerlink" href="#other-methods" title="Permalink to this headline">¶</a></h1>
<div class="section" id="partial-parsing">
<h2>Partial parsing<a class="headerlink" href="#partial-parsing" title="Permalink to this headline">¶</a></h2>
<dl class="method">
<dt id="parse_known_args">
<tt class="descname">parse_known_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_known_args" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Sometimes a script may only parse a few of the command line arguments, passing the remaining arguments on to another script or program.
In these cases, the <a title="parse_known_args" class="reference internal" href="#parse_known_args"><tt class="xref docutils literal"><span class="pre">parse_known_args()</span></tt></a> method can be useful.
It works much like <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> except that it does not produce an error when extra arguments are present.
Instead, it returns a two item tuple containing the populated namespace and the list of remaining argument strings.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'--foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_true'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'bar'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_known_args</span><span class="p">([</span><span class="s">'--foo'</span><span class="p">,</span> <span class="s">'--badger'</span><span class="p">,</span> <span class="s">'BAR'</span><span class="p">,</span> <span class="s">'spam'</span><span class="p">])</span>
<span class="go">(Namespace(bar='BAR', foo=True), ['--badger', 'spam'])</span>
</pre></div>
</div>
</div>
<div class="section" id="printing-help">
<h2>Printing help<a class="headerlink" href="#printing-help" title="Permalink to this headline">¶</a></h2>
<p>In most typical applications, <a title="parse_args" class="reference external" href="parse_args.html#parse_args"><tt class="xref docutils literal"><span class="pre">parse_args()</span></tt></a> will take care of formatting and printing any usage or error messages. However, should you want to format or print these on your own, several methods are available:</p>
<dl class="method">
<dt>
<tt class="descname">print_usage([file]):</tt></dt>
<dd>Print a brief description of how the <a title="ArgumentParser" class="reference external" href="ArgumentParser.html#ArgumentParser"><tt class="xref docutils literal"><span class="pre">ArgumentParser</span></tt></a> should be invoked on the command line. If <tt class="docutils literal"><span class="pre">file</span></tt> is not present, <tt class="docutils literal"><span class="pre">sys.stderr</span></tt> is assumed.</dd></dl>
<dl class="method">
<dt>
<tt class="descname">print_help([file]):</tt></dt>
<dd>Print a help message, including the program usage and information about the arguments registered with the <a title="ArgumentParser" class="reference external" href="ArgumentParser.html#ArgumentParser"><tt class="xref docutils literal"><span class="pre">ArgumentParser</span></tt></a>. If <tt class="docutils literal"><span class="pre">file</span></tt> is not present, <tt class="docutils literal"><span class="pre">sys.stderr</span></tt> is assumed.</dd></dl>
<p>There are also variants of these methods that simply return a string instead of printing it:</p>
<dl class="method">
<dt>
<tt class="descname">format_usage():</tt></dt>
<dd>Return a string containing a brief description of how the <a title="ArgumentParser" class="reference external" href="ArgumentParser.html#ArgumentParser"><tt class="xref docutils literal"><span class="pre">ArgumentParser</span></tt></a> should be invoked on the command line.</dd></dl>
<dl class="method">
<dt>
<tt class="descname">format_help():</tt></dt>
<dd>Return a string containing a help message, including the program usage and information about the arguments registered with the <a title="ArgumentParser" class="reference external" href="ArgumentParser.html#ArgumentParser"><tt class="xref docutils literal"><span class="pre">ArgumentParser</span></tt></a>.</dd></dl>
</div>
<div class="section" id="parser-defaults">
<h2>Parser defaults<a class="headerlink" href="#parser-defaults" title="Permalink to this headline">¶</a></h2>
<dl class="method">
<dt id="set_defaults">
<tt class="descname">set_defaults</tt><big>(</big><em>**kwargs</em><big>)</big><a class="headerlink" href="#set_defaults" title="Permalink to this definition">¶</a></dt>
<dd><p>Most of the time, the attributes of the object returned by <a title="parse_args" class="reference external" href="parse_args.html#parse_args"><tt class="xref docutils literal"><span class="pre">parse_args()</span></tt></a> will be fully determined by inspecting the command-line args and the argument actions described in your <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> calls. However, sometimes it may be useful to add some additional attributes that are determined without any inspection of the command-line. The <a title="set_defaults" class="reference internal" href="#set_defaults"><tt class="xref docutils literal"><span class="pre">set_defaults()</span></tt></a> method allows you to do this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'foo'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">set_defaults</span><span class="p">(</span><span class="n">bar</span><span class="o">=</span><span class="mf">42</span><span class="p">,</span> <span class="n">baz</span><span class="o">=</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">'736'</span><span class="p">])</span>
<span class="go">Namespace(bar=42, baz='badger', foo=736)</span>
</pre></div>
</div>
<p>Note that parser-level defaults always override argument-level defaults. So if you set a parser-level default for a name that matches an argument, the old argument default will no longer be used:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'--foo'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s">'bar'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">set_defaults</span><span class="p">(</span><span class="n">foo</span><span class="o">=</span><span class="s">'spam'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>
<span class="go">Namespace(foo='spam')</span>
</pre></div>
</div>
<p>Parser-level defaults can be particularly useful when you’re working with multiple parsers. See the <a title="add_subparsers" class="reference internal" href="#add_subparsers"><tt class="xref docutils literal"><span class="pre">add_subparsers()</span></tt></a> method for an example of this type.</p>
</dd></dl>
<dl class="method">
<dt id="get_default">
<tt class="descname">get_default</tt><big>(</big><em>dest</em><big>)</big><a class="headerlink" href="#get_default" title="Permalink to this definition">¶</a></dt>
<dd><p>Get the default value for a namespace attribute, as set by either <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> or by <a title="set_defaults" class="reference internal" href="#set_defaults"><tt class="xref docutils literal"><span class="pre">set_defaults()</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'--foo'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</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">get_default</span><span class="p">(</span><span class="s">'foo'</span><span class="p">)</span>
<span class="go">'badger'</span>
</pre></div>
</div>
</dd></dl>
</div>
<div class="section" id="sub-commands">
<h2>Sub-commands<a class="headerlink" href="#sub-commands" title="Permalink to this headline">¶</a></h2>
<dl class="method">
<dt id="add_subparsers">
<tt class="descname">add_subparsers</tt><big>(</big><big>)</big><a class="headerlink" href="#add_subparsers" title="Permalink to this definition">¶</a></dt>
<dd><p>A lot of programs split up their functionality into a number of sub-commands, for example, the <tt class="docutils literal"><span class="pre">svn</span></tt> program can invoke sub-commands like <tt class="docutils literal"><span class="pre">svn</span> <span class="pre">checkout</span></tt>, <tt class="docutils literal"><span class="pre">svn</span> <span class="pre">update</span></tt>, <tt class="docutils literal"><span class="pre">svn</span> <span class="pre">commit</span></tt>, etc. Splitting up functionality this way can be a particularly good idea when a program performs several different functions which require different kinds of command-line arguments. ArgumentParser objects support the creation of such sub-commands with the <a title="add_subparsers" class="reference internal" href="#add_subparsers"><tt class="xref docutils literal"><span class="pre">add_subparsers()</span></tt></a> method. The <a title="add_subparsers" class="reference internal" href="#add_subparsers"><tt class="xref docutils literal"><span class="pre">add_subparsers()</span></tt></a> method is normally called with no arguments and returns an special action object. This object has a single method, <tt class="docutils literal"><span class="pre">add_parser</span></tt>, which takes a command name and any ArgumentParser constructor arguments, and returns an ArgumentParser object that can be modified as usual.</p>
<p>Some example usage:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="c"># create the top-level parser</span>
<span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">prog</span><span class="o">=</span><span class="s">'PROG'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'--foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_true'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s">'foo help'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">subparsers</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_subparsers</span><span class="p">(</span><span class="n">help</span><span class="o">=</span><span class="s">'sub-command help'</span><span class="p">)</span>
<span class="go">>>></span>
<span class="gp">>>> </span><span class="c"># create the parser for the "a" command</span>
<span class="gp">>>> </span><span class="n">parser_a</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s">'a'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s">'a help'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser_a</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'bar'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s">'bar help'</span><span class="p">)</span>
<span class="go">>>></span>
<span class="gp">>>> </span><span class="c"># create the parser for the "b" command</span>
<span class="gp">>>> </span><span class="n">parser_b</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s">'b'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s">'b help'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser_b</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'--baz'</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="s">'XYZ'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s">'baz help'</span><span class="p">)</span>
<span class="go">>>></span>
<span class="gp">>>> </span><span class="c"># parse some arg lists</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">'a'</span><span class="p">,</span> <span class="s">'12'</span><span class="p">])</span>
<span class="go">Namespace(bar=12, foo=False)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">'--foo'</span><span class="p">,</span> <span class="s">'b'</span><span class="p">,</span> <span class="s">'--baz'</span><span class="p">,</span> <span class="s">'Z'</span><span class="p">])</span>
<span class="go">Namespace(baz='Z', foo=True)</span>
</pre></div>
</div>
<p>Note that the object returned by <a title="parse_args" class="reference external" href="parse_args.html#parse_args"><tt class="xref docutils literal"><span class="pre">parse_args()</span></tt></a> will only contain attributes for the main parser and the subparser that was selected by the command line (and not any other subparsers). So in the example above, when the <tt class="docutils literal"><span class="pre">"a"</span></tt> command is specified, only the <tt class="docutils literal"><span class="pre">foo</span></tt> and <tt class="docutils literal"><span class="pre">bar</span></tt> attributes are present, and when the <tt class="docutils literal"><span class="pre">"b"</span></tt> command is specified, only the <tt class="docutils literal"><span class="pre">foo</span></tt> and <tt class="docutils literal"><span class="pre">baz</span></tt> attributes are present.</p>
<p>Similarly, when a help message is requested from a subparser, only the help for that particular parser will be printed. The help message will not include parent parser or sibling parser messages. (You can however supply a help message for each subparser command by suppling the <tt class="docutils literal"><span class="pre">help=</span></tt> argument to <tt class="docutils literal"><span class="pre">add_parser</span></tt> as above.)</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">'--help'</span><span class="p">])</span>
<span class="go">usage: PROG [-h] [--foo] {a,b} ...</span>
<span class="go">positional arguments:</span>
<span class="go"> {a,b} sub-command help</span>
<span class="go">a a help</span>
<span class="go">b b help</span>
<span class="go">optional arguments:</span>
<span class="go"> -h, --help show this help message and exit</span>
<span class="go"> --foo foo help</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">'a'</span><span class="p">,</span> <span class="s">'--help'</span><span class="p">])</span>
<span class="go">usage: PROG a [-h] bar</span>
<span class="go">positional arguments:</span>
<span class="go"> bar bar help</span>
<span class="go">optional arguments:</span>
<span class="go"> -h, --help show this help message and exit</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">'b'</span><span class="p">,</span> <span class="s">'--help'</span><span class="p">])</span>
<span class="go">usage: PROG b [-h] [--baz {X,Y,Z}]</span>
<span class="go">optional arguments:</span>
<span class="go"> -h, --help show this help message and exit</span>
<span class="go"> --baz {X,Y,Z} baz help</span>
</pre></div>
</div>
<p>The <a title="add_subparsers" class="reference internal" href="#add_subparsers"><tt class="xref docutils literal"><span class="pre">add_subparsers()</span></tt></a> method also supports <tt class="docutils literal"><span class="pre">title</span></tt> and <tt class="docutils literal"><span class="pre">description</span></tt> keyword arguments. When either is present, the subparser’s commands will appear in their own group in the help output. For example:</p>
<div class="highlight-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">subparsers</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_subparsers</span><span class="p">(</span><span class="n">title</span><span class="o">=</span><span class="s">'subcommands'</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">description</span><span class="o">=</span><span class="s">'valid subcommands'</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">help</span><span class="o">=</span><span class="s">'additional help'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s">'foo'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s">'bar'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">'-h'</span><span class="p">])</span>
<span class="go">usage: [-h] {foo,bar} ...</span>
<span class="go">optional arguments:</span>
<span class="go"> -h, --help show this help message and exit</span>
<span class="go">subcommands:</span>
<span class="go"> valid subcommands</span>
<span class="go"> {foo,bar} additional help</span>
</pre></div>
</div>
<p>One particularly effective way of handling sub-commands is to combine the use of the <a title="add_subparsers" class="reference internal" href="#add_subparsers"><tt class="xref docutils literal"><span class="pre">add_subparsers()</span></tt></a> method with calls to <a title="set_defaults" class="reference internal" href="#set_defaults"><tt class="xref docutils literal"><span class="pre">set_defaults()</span></tt></a> so that each subparser knows which Python function it should execute. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="c"># sub-command functions</span>
<span class="gp">>>> </span><span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="n">args</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">print</span> <span class="n">args</span><span class="o">.</span><span class="n">x</span> <span class="o">*</span> <span class="n">args</span><span class="o">.</span><span class="n">y</span>
<span class="gp">...</span>
<span class="gp">>>> </span><span class="k">def</span> <span class="nf">bar</span><span class="p">(</span><span class="n">args</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">print</span> <span class="s">'((</span><span class="si">%s</span><span class="s">))'</span> <span class="o">%</span> <span class="n">args</span><span class="o">.</span><span class="n">z</span>
<span class="gp">...</span>
<span class="gp">>>> </span><span class="c"># create the top-level parser</span>
<span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">subparsers</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_subparsers</span><span class="p">()</span>
<span class="go">>>></span>
<span class="gp">>>> </span><span class="c"># create the parser for the "foo" command</span>
<span class="gp">>>> </span><span class="n">parser_foo</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s">'foo'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser_foo</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'-x'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mf">1</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser_foo</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'y'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">float</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser_foo</span><span class="o">.</span><span class="n">set_defaults</span><span class="p">(</span><span class="n">func</span><span class="o">=</span><span class="n">foo</span><span class="p">)</span>
<span class="go">>>></span>
<span class="gp">>>> </span><span class="c"># create the parser for the "bar" command</span>
<span class="gp">>>> </span><span class="n">parser_bar</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s">'bar'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser_bar</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'z'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser_bar</span><span class="o">.</span><span class="n">set_defaults</span><span class="p">(</span><span class="n">func</span><span class="o">=</span><span class="n">bar</span><span class="p">)</span>
<span class="go">>>></span>
<span class="gp">>>> </span><span class="c"># parse the args and call whatever function was selected</span>
<span class="gp">>>> </span><span class="n">args</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s">'foo 1 -x 2'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="gp">>>> </span><span class="n">args</span><span class="o">.</span><span class="n">func</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>
<span class="go">2.0</span>
<span class="go">>>></span>
<span class="gp">>>> </span><span class="c"># parse the args and call whatever function was selected</span>
<span class="gp">>>> </span><span class="n">args</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s">'bar XYZYX'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="gp">>>> </span><span class="n">args</span><span class="o">.</span><span class="n">func</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>
<span class="go">((XYZYX))</span>
</pre></div>
</div>
<p>This way, you can let <a 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> do all the work for you, and then just call the appropriate function after the argument parsing is complete. Associating functions with actions like this is typically the easiest way to handle the different actions for each of your subparsers. However, if you find it necessary to check the name of the subparser that was invoked, you can always provide a <tt class="docutils literal"><span class="pre">dest</span></tt> keyword argument to the <a title="add_subparsers" class="reference internal" href="#add_subparsers"><tt class="xref docutils literal"><span class="pre">add_subparsers()</span></tt></a> call:</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">subparsers</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_subparsers</span><span class="p">(</span><span class="n">dest</span><span class="o">=</span><span class="s">'subparser_name'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">subparser1</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s">'1'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">subparser1</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'-x'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">subparser2</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s">'2'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">subparser2</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'y'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">'2'</span><span class="p">,</span> <span class="s">'frobble'</span><span class="p">])</span>
<span class="go">Namespace(subparser_name='2', y='frobble')</span>
</pre></div>
</div>
</dd></dl>
</div>
<div class="section" id="argument-groups">
<h2>Argument groups<a class="headerlink" href="#argument-groups" title="Permalink to this headline">¶</a></h2>
<dl class="method">
<dt id="add_argument_group">
<tt class="descname">add_argument_group</tt><big>(</big><span class="optional">[</span><em>title</em><span class="optional">]</span><span class="optional">[</span>, <em>description</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#add_argument_group" title="Permalink to this definition">¶</a></dt>
<dd><p>By default, ArgumentParser objects group command-line arguments into “positional arguments” and “optional arguments” when displaying help messages. When there is a better conceptual grouping of arguments than this default one, appropriate groups can be created using the <a title="add_argument_group" class="reference internal" href="#add_argument_group"><tt class="xref docutils literal"><span class="pre">add_argument_group()</span></tt></a> method:</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="n">add_help</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">group</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_argument_group</span><span class="p">(</span><span class="s">'group'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'--foo'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s">'foo help'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'bar'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s">'bar help'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage: PROG [--foo FOO] bar</span>
<span class="go">group:</span>
<span class="go"> bar bar help</span>
<span class="go"> --foo FOO foo help</span>
</pre></div>
</div>
<p>The <a title="add_argument_group" class="reference internal" href="#add_argument_group"><tt class="xref docutils literal"><span class="pre">add_argument_group()</span></tt></a> method returns an argument group object which has an <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> method just like a regular ArgumentParser objects. When an argument is added to the group, the parser treats it just like a normal argument, but displays the argument in a separate group for help messages. The <a title="add_argument_group" class="reference internal" href="#add_argument_group"><tt class="xref docutils literal"><span class="pre">add_argument_group()</span></tt></a> method accepts <tt class="docutils literal"><span class="pre">title</span></tt> and <tt class="docutils literal"><span class="pre">description</span></tt> arguments which can be used to customize this display:</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="n">add_help</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">group1</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_argument_group</span><span class="p">(</span><span class="s">'group1'</span><span class="p">,</span> <span class="s">'group1 description'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">group1</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'foo'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s">'foo help'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">group2</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_argument_group</span><span class="p">(</span><span class="s">'group2'</span><span class="p">,</span> <span class="s">'group2 description'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">group2</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'--bar'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s">'bar help'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage: PROG [--bar BAR] foo</span>
<span class="go">group1:</span>
<span class="go"> group1 description</span>
<span class="go"> foo foo help</span>
<span class="go">group2:</span>
<span class="go"> group2 description</span>
<span class="go"> --bar BAR bar help</span>
</pre></div>
</div>
<p>Note that any arguments not in your user defined groups will end up back in the usual “positional arguments” and “optional arguments” sections.</p>
</dd></dl>
</div>
<div class="section" id="mutual-exclusion">
<h2>Mutual exclusion<a class="headerlink" href="#mutual-exclusion" title="Permalink to this headline">¶</a></h2>
<dl class="method">
<dt id="add_mutually_exclusive_group">
<tt class="descname">add_mutually_exclusive_group</tt><big>(</big><span class="optional">[</span><em>required=False</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#add_mutually_exclusive_group" title="Permalink to this definition">¶</a></dt>
<dd><p>Sometimes, you need to make sure that only one of a couple different options is specified on the command line. You can create groups of such mutually exclusive arguments using the <a title="add_mutually_exclusive_group" class="reference internal" href="#add_mutually_exclusive_group"><tt class="xref docutils literal"><span class="pre">add_mutually_exclusive_group()</span></tt></a> method. 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, argparse will make sure that only one of the arguments in the mutually exclusive group was present on the command line:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">prog</span><span class="o">=</span><span class="s">'PROG'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">group</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_mutually_exclusive_group</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'--foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_true'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'--bar'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_false'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">'--foo'</span><span class="p">])</span>
<span class="go">Namespace(bar=True, foo=True)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">'--bar'</span><span class="p">])</span>
<span class="go">Namespace(bar=False, foo=False)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">'--foo'</span><span class="p">,</span> <span class="s">'--bar'</span><span class="p">])</span>
<span class="go">usage: PROG [-h] [--foo | --bar]</span>
<span class="go">PROG: error: argument --bar: not allowed with argument --foo</span>
</pre></div>
</div>
<p>The <a title="add_mutually_exclusive_group" class="reference internal" href="#add_mutually_exclusive_group"><tt class="xref docutils literal"><span class="pre">add_mutually_exclusive_group()</span></tt></a> method also accepts a <tt class="docutils literal"><span class="pre">required</span></tt> argument, to indicate that at least one of the mutually exclusive arguments is required:</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">group</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_mutually_exclusive_group</span><span class="p">(</span><span class="n">required</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'--foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_true'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'--bar'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_false'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>
<span class="go">usage: PROG [-h] (--foo | --bar)</span>
<span class="go">PROG: error: one of the arguments --foo --bar is required</span>
</pre></div>
</div>
<p>Note that currently mutually exclusive argument groups do not support the <tt class="docutils literal"><span class="pre">title</span></tt> and <tt class="docutils literal"><span class="pre">description</span></tt> arguments of <a title="add_argument_group" class="reference internal" href="#add_argument_group"><tt class="xref docutils literal"><span class="pre">add_argument_group()</span></tt></a>. This may change in the future however, so you are <em>strongly</em> recommended to specify <tt class="docutils literal"><span class="pre">required</span></tt> as a keyword argument if you use it.</p>
</dd></dl>
</div>
<div class="section" id="customizing-file-parsing">
<h2>Customizing file parsing<a class="headerlink" href="#customizing-file-parsing" title="Permalink to this headline">¶</a></h2>
<dl class="method">
<dt id="convert_arg_line_to_args">
<tt class="descname">convert_arg_line_to_args</tt><big>(</big><em>arg_line</em><big>)</big><a class="headerlink" href="#convert_arg_line_to_args" title="Permalink to this definition">¶</a></dt>
<dd><p>Arguments that are read from a file (see the <tt class="docutils literal"><span class="pre">fromfile_prefix_chars</span></tt> keyword argument to the <a title="ArgumentParser" class="reference external" href="ArgumentParser.html#ArgumentParser"><tt class="xref docutils literal"><span class="pre">ArgumentParser</span></tt></a> constructor) are read one argument per line. If you need fancier parsing, then you can subclass the <a title="ArgumentParser" class="reference external" href="ArgumentParser.html#ArgumentParser"><tt class="xref docutils literal"><span class="pre">ArgumentParser</span></tt></a> and override the <a title="convert_arg_line_to_args" class="reference internal" href="#convert_arg_line_to_args"><tt class="xref docutils literal"><span class="pre">convert_arg_line_to_args()</span></tt></a> method.</p>
<p>This method takes a single argument <tt class="docutils literal"><span class="pre">arg_line</span></tt> which is a string read from the argument file. It returns a list of arguments parsed from this string. The method is called once per line read from the argument file, in order.</p>
<p>A useful override of this method is one that treats each space-separated word as an argument:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">convert_arg_line_to_args</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">arg_line</span><span class="p">):</span>
<span class="k">for</span> <span class="n">arg</span> <span class="ow">in</span> <span class="n">arg_line</span><span class="o">.</span><span class="n">split</span><span class="p">():</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">arg</span><span class="o">.</span><span class="n">strip</span><span class="p">():</span>
<span class="k">continue</span>
<span class="k">yield</span> <span class="n">arg</span>
</pre></div>
</div>
</dd></dl>
</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="">Other methods</a><ul>
<li><a class="reference external" href="#partial-parsing">Partial parsing</a></li>
<li><a class="reference external" href="#printing-help">Printing help</a></li>
<li><a class="reference external" href="#parser-defaults">Parser defaults</a></li>
<li><a class="reference external" href="#sub-commands">Sub-commands</a></li>
<li><a class="reference external" href="#argument-groups">Argument groups</a></li>
<li><a class="reference external" href="#mutual-exclusion">Mutual exclusion</a></li>
<li><a class="reference external" href="#customizing-file-parsing">Customizing file parsing</a></li>
</ul>
</li>
</ul>
<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"
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-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 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>
distrib
>
Fedora
>
13
>
x86_64
>
media
>
updates
>
by-pkgid
>
35f15dfef6a5aceaac7285fbf44291b7
>
files
>
23
