1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
|
<!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.0.2 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.0.2',
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.0.2 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.0.2 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>
</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>
</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>
</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.0.2 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>
|
