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
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
|
<!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>ArgumentParser objects — 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="The add_argument() method" href="add_argument.html" />
<link rel="prev" title="API documentation" href="api-docs.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="add_argument.html" title="The add_argument() method"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="api-docs.html" title="API documentation"
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="argumentparser-objects">
<h1>ArgumentParser objects<a class="headerlink" href="#argumentparser-objects" title="Permalink to this headline">¶</a></h1>
<dl class="class">
<dt id="ArgumentParser">
<em class="property">
class </em><tt class="descname">ArgumentParser</tt><big>(</big><span class="optional">[</span><em>description</em><span class="optional">]</span><span class="optional">[</span>, <em>epilog</em><span class="optional">]</span><span class="optional">[</span>, <em>prog</em><span class="optional">]</span><span class="optional">[</span>, <em>usage</em><span class="optional">]</span><span class="optional">[</span>, <em>add_help</em><span class="optional">]</span><span class="optional">[</span>, <em>argument_default</em><span class="optional">]</span><span class="optional">[</span>, <em>parents</em><span class="optional">]</span><span class="optional">[</span>, <em>prefix_chars</em><span class="optional">]</span><span class="optional">[</span>, <em>conflict_handler</em><span class="optional">]</span><span class="optional">[</span>, <em>formatter_class</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#ArgumentParser" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a new <a title="ArgumentParser" class="reference internal" href="#ArgumentParser"><tt class="xref docutils literal"><span class="pre">ArgumentParser</span></tt></a> object. Each parameter has its own more detailed description below, but in short they are:</p>
<ul class="simple">
<li><a class="reference internal" href="#description">description</a> - Text to display before the argument help.</li>
<li><a class="reference internal" href="#epilog">epilog</a> - Text to display after the argument help.</li>
<li><a class="reference internal" href="#add-help">add_help</a> - Add a -h/–help option to the parser. (default: True)</li>
<li><a class="reference internal" href="#argument-default">argument_default</a> - Set the global default value for arguments. (default: None)</li>
<li><a class="reference internal" href="#parents">parents</a> - A list of :class:ArgumentParser objects whose arguments should also be included.</li>
<li><a class="reference internal" href="#prefix-chars">prefix_chars</a> - The set of characters that prefix optional arguments. (default: ‘-‘)</li>
<li><a class="reference internal" href="#fromfile-prefix-chars">fromfile_prefix_chars</a> - The set of characters that prefix files from which additional arguments should be read. (default: None)</li>
<li><a class="reference internal" href="#formatter-class">formatter_class</a> - A class for customizing the help output.</li>
<li><a class="reference internal" href="#conflict-handler">conflict_handler</a> - Usually unnecessary, defines strategy for resolving conflicting optionals.</li>
<li><a class="reference internal" href="#prog">prog</a> - Usually unnecessary, the name of the program (default: <tt class="docutils literal"><span class="pre">sys.argv[0]</span></tt>)</li>
<li><a class="reference internal" href="#usage">usage</a> - Usually unnecessary, the string describing the program usage (default: generated)</li>
</ul>
<p>The following sections describe how each of these are used.</p>
</dd></dl>
<div class="section" id="description">
<h2>description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p>Most calls to the ArgumentParser constructor will use the <tt class="docutils literal"><span class="pre">description=</span></tt> keyword argument. This argument gives a brief description of what the program does and how it works. In help messages, the description is displayed between the command-line usage string and the help messages for the various arguments:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">description</span><span class="o">=</span><span class="s">'A foo that bars'</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: argparse.py [-h]</span>
<span class="go">A foo that bars</span>
<span class="go">optional arguments:</span>
<span class="go"> -h, --help show this help message and exit</span>
</pre></div>
</div>
<p>By default, the description will be line-wrapped so that it fits within the given space. To change this behavior, see the <a class="reference internal" href="#formatter-class">formatter_class</a> argument.</p>
</div>
<div class="section" id="epilog">
<h2>epilog<a class="headerlink" href="#epilog" title="Permalink to this headline">¶</a></h2>
<p>Some programs like to display additional description of the program after the description of the arguments. Such text can be specified using the <tt class="docutils literal"><span class="pre">epilog=</span></tt> argument to ArgumentParser:</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">description</span><span class="o">=</span><span class="s">'A foo that bars'</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">epilog</span><span class="o">=</span><span class="s">"And that's how you'd foo a bar"</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: argparse.py [-h]</span>
<span class="go">A foo that bars</span>
<span class="go">optional arguments:</span>
<span class="go"> -h, --help show this help message and exit</span>
<span class="go">And that's how you'd foo a bar</span>
</pre></div>
</div>
<p>As with the <a class="reference internal" href="#description">description</a> argument, the <tt class="docutils literal"><span class="pre">epilog=</span></tt> text is by default line-wrapped, but this behavior can be adjusted with the <a class="reference internal" href="#formatter-class">formatter_class</a> argument to ArgumentParser.</p>
</div>
<div class="section" id="add-help">
<h2>add_help<a class="headerlink" href="#add-help" title="Permalink to this headline">¶</a></h2>
<p>By default, ArgumentParser objects add a <tt class="docutils literal"><span class="pre">-h/--help</span></tt> option which simply displays the parser’s help message. For example, consider a file named <tt class="docutils literal"><span class="pre">myprogram.py</span></tt> containing the following code:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">argparse</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">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">help</span><span class="o">=</span><span class="s">'foo help'</span><span class="p">)</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>
</pre></div>
</div>
<p>If <tt class="docutils literal"><span class="pre">-h</span></tt> or <tt class="docutils literal"><span class="pre">--help</span></tt> is supplied is at the command-line, the ArgumentParser help will be printed:</p>
<div class="highlight-python"><pre>$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo help</pre>
</div>
<p>Occasionally, it may be useful to disable the addition of this help option. This can be achieved by passing <tt class="xref docutils literal"><span class="pre">False</span></tt> as the <tt class="docutils literal"><span class="pre">add_help=</span></tt> argument to ArgumentParser:</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">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">help</span><span class="o">=</span><span class="s">'foo 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]</span>
<span class="go">optional arguments:</span>
<span class="go"> --foo FOO foo help</span>
</pre></div>
</div>
</div>
<div class="section" id="prefix-chars">
<h2>prefix_chars<a class="headerlink" href="#prefix-chars" title="Permalink to this headline">¶</a></h2>
<p>Most command-line options will use <tt class="docutils literal"><span class="pre">'-'</span></tt> as the prefix, e.g. <tt class="docutils literal"><span class="pre">-f/--foo</span></tt>. Parsers that need to support additional prefix characters, e.g. for options like <tt class="docutils literal"><span class="pre">+f</span></tt> or <tt class="docutils literal"><span class="pre">/foo</span></tt>, may specify them using the <tt class="docutils literal"><span class="pre">prefix_chars=</span></tt> argument to the ArgumentParser constructor:</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">prefix_chars</span><span class="o">=</span><span class="s">'-+'</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">'+f'</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_args</span><span class="p">(</span><span class="s">'+f X ++bar Y'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(bar='Y', f='X')</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">prefix_chars=</span></tt> argument defaults to <tt class="docutils literal"><span class="pre">'-'</span></tt>. Supplying a set of characters that does not include <tt class="docutils literal"><span class="pre">'-'</span></tt> will cause <tt class="docutils literal"><span class="pre">-f/--foo</span></tt> options to be disallowed.</p>
</div>
<div class="section" id="fromfile-prefix-chars">
<h2>fromfile_prefix_chars<a class="headerlink" href="#fromfile-prefix-chars" title="Permalink to this headline">¶</a></h2>
<p>Sometimes, e.g. for particularly long argument lists, it may make sense to keep the list of arguments in a file rather than typing it out at the command line.
If the <tt class="docutils literal"><span class="pre">fromfile_prefix_chars=</span></tt> argument is given to the ArgumentParser constructor, then arguments that start with any of the specified characters will be treated as files, and will be replaced by the arguments they contain. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nb">open</span><span class="p">(</span><span class="s">'args.txt'</span><span class="p">,</span> <span class="s">'w'</span><span class="p">)</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">'-f</span><span class="se">\n</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">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">fromfile_prefix_chars</span><span class="o">=</span><span class="s">'@'</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">'-f'</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">'-f'</span><span class="p">,</span> <span class="s">'foo'</span><span class="p">,</span> <span class="s">'@args.txt'</span><span class="p">])</span>
<span class="go">Namespace(f='bar')</span>
</pre></div>
</div>
<p>Arguments read from a file must by default be one per line (but see also <a title="convert_arg_line_to_args" class="reference external" href="other-methods.html#convert_arg_line_to_args"><tt class="xref docutils literal"><span class="pre">convert_arg_line_to_args()</span></tt></a>) and are treated as if they were in the same place as the original file referencing argument on the command line.
So in the example above, the expression <tt class="docutils literal"><span class="pre">['-f',</span> <span class="pre">'foo',</span> <span class="pre">'@args.txt']</span></tt> is considered equivalent to the expression <tt class="docutils literal"><span class="pre">['-f',</span> <span class="pre">'foo',</span> <span class="pre">'-f',</span> <span class="pre">'bar']</span></tt>.</p>
<p>The <tt class="docutils literal"><span class="pre">fromfile_prefix_chars=</span></tt> argument defaults to <tt class="xref docutils literal"><span class="pre">None</span></tt>, meaning that arguments will never be treated as file references.</p>
</div>
<div class="section" id="argument-default">
<h2>argument_default<a class="headerlink" href="#argument-default" title="Permalink to this headline">¶</a></h2>
<p>Generally, argument defaults are specified either by passing a default to <a title="add_argument" class="reference external" href="add_argument.html#add_argument"><tt class="xref docutils literal"><span class="pre">add_argument()</span></tt></a> or by calling the <a title="set_defaults" class="reference external" href="other-methods.html#set_defaults"><tt class="xref docutils literal"><span class="pre">set_defaults()</span></tt></a> methods with a specific set of name-value pairs. Sometimes however, it may be useful to specify a single parser-wide default for arguments. This can be accomplished by passing the <tt class="docutils literal"><span class="pre">argument_default=</span></tt> keyword argument to ArgumentParser. For example, to globally suppress attribute creation on <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> calls, we supply <tt class="docutils literal"><span class="pre">argument_default=SUPPRESS</span></tt>:</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">argument_default</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">SUPPRESS</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'--foo'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s">'?'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="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">'1'</span><span class="p">,</span> <span class="s">'BAR'</span><span class="p">])</span>
<span class="go">Namespace(bar='BAR', foo='1')</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()</span>
</pre></div>
</div>
</div>
<div class="section" id="parents">
<h2>parents<a class="headerlink" href="#parents" title="Permalink to this headline">¶</a></h2>
<p>Sometimes, several parsers share a common set of arguments. Rather than repeating the definitions of these arguments, you can define a single parser with all the shared arguments and then use the <tt class="docutils literal"><span class="pre">parents=</span></tt> argument to ArgumentParser to have these “inherited”. The <tt class="docutils literal"><span class="pre">parents=</span></tt> argument takes a list of ArgumentParser objects, collects all the positional and optional actions from them, and adds these actions to the ArgumentParser object being constructed:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">parent_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">add_help</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parent_parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'--parent'</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">foo_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">parents</span><span class="o">=</span><span class="p">[</span><span class="n">parent_parser</span><span class="p">])</span>
<span class="gp">>>> </span><span class="n">foo_parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'foo'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">foo_parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s">'--parent'</span><span class="p">,</span> <span class="s">'2'</span><span class="p">,</span> <span class="s">'XXX'</span><span class="p">])</span>
<span class="go">Namespace(foo='XXX', parent=2)</span>
<span class="gp">>>> </span><span class="n">bar_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">parents</span><span class="o">=</span><span class="p">[</span><span class="n">parent_parser</span><span class="p">])</span>
<span class="gp">>>> </span><span class="n">bar_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">bar_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="s">'YYY'</span><span class="p">])</span>
<span class="go">Namespace(bar='YYY', parent=None)</span>
</pre></div>
</div>
<p>Note that most parent parsers will specify <tt class="docutils literal"><span class="pre">add_help=False</span></tt>. Otherwise, the ArgumentParser will see two <tt class="docutils literal"><span class="pre">-h/--help</span></tt> options (one in the parent and one in the child) and raise an error.</p>
</div>
<div class="section" id="formatter-class">
<h2>formatter_class<a class="headerlink" href="#formatter-class" title="Permalink to this headline">¶</a></h2>
<p>ArgumentParser objects allow the help formatting to be customized by specifying an alternate formatting class.
Currently, there are three such classes: <tt class="docutils literal"><span class="pre">argparse.RawDescriptionHelpFormatter</span></tt>, <tt class="docutils literal"><span class="pre">argparse.RawTextHelpFormatter</span></tt> and <tt class="docutils literal"><span class="pre">argparse.ArgumentDefaultsHelpFormatter</span></tt>.
The first two allow more control over how textual descriptions are displayed, while the last automatically adds information about argument default values.</p>
<p>By default, ArgumentParser objects line-wrap the <a class="reference internal" href="#description">description</a> and <a class="reference internal" href="#epilog">epilog</a> texts in command-line help messages:</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">prog</span><span class="o">=</span><span class="s">'PROG'</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">description</span><span class="o">=</span><span class="s">'''this description</span>
<span class="gp">... </span><span class="s"> was indented weird</span>
<span class="gp">... </span><span class="s"> but that is okay'''</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">epilog</span><span class="o">=</span><span class="s">'''</span>
<span class="gp">... </span><span class="s"> likewise for this epilog whose whitespace will</span>
<span class="gp">... </span><span class="s"> be cleaned up and whose words will be wrapped</span>
<span class="gp">... </span><span class="s"> across a couple lines'''</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 [-h]</span>
<span class="go">this description was indented weird but that is okay</span>
<span class="go">optional arguments:</span>
<span class="go"> -h, --help show this help message and exit</span>
<span class="go">likewise for this epilog whose whitespace will be cleaned up and whose words</span>
<span class="go">will be wrapped across a couple lines</span>
</pre></div>
</div>
<p>When you have <a class="reference internal" href="#description">description</a> and <a class="reference internal" href="#epilog">epilog</a> that is already correctly formatted and should not be line-wrapped, you can indicate this by passing <tt class="docutils literal"><span class="pre">argparse.RawDescriptionHelpFormatter</span></tt> as the <tt class="docutils literal"><span class="pre">formatter_class=</span></tt> argument to ArgumentParser:</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">prog</span><span class="o">=</span><span class="s">'PROG'</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">formatter_class</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">RawDescriptionHelpFormatter</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">description</span><span class="o">=</span><span class="n">textwrap</span><span class="o">.</span><span class="n">dedent</span><span class="p">(</span><span class="s">'''</span><span class="se">\</span>
<span class="gp">... </span><span class="s"> Please do not mess up this text!</span>
<span class="gp">... </span><span class="s"> --------------------------------</span>
<span class="gp">... </span><span class="s"> I have indented it</span>
<span class="gp">... </span><span class="s"> exactly the way</span>
<span class="gp">... </span><span class="s"> I want it</span>
<span class="gp">... </span><span class="s"> '''</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 [-h]</span>
<span class="go">Please do not mess up this text!</span>
<span class="go">--------------------------------</span>
<span class="go"> I have indented it</span>
<span class="go"> exactly the way</span>
<span class="go"> I want it</span>
<span class="go">optional arguments:</span>
<span class="go"> -h, --help show this help message and exit</span>
</pre></div>
</div>
<p>If you want to maintain whitespace for all sorts of help text (including argument descriptions), you can use <tt class="docutils literal"><span class="pre">argparse.RawTextHelpFormatter</span></tt>.</p>
<p>The other formatter class available, <tt class="docutils literal"><span class="pre">argparse.ArgumentDefaultsHelpFormatter</span></tt>, will add information about the default value of each of the arguments:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span>
<span class="gp">... </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">formatter_class</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentDefaultsHelpFormatter</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="n">default</span><span class="o">=</span><span class="mf">42</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s">'FOO!'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s">'*'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="p">[</span><span class="mf">1</span><span class="p">,</span> <span class="mf">2</span><span class="p">,</span> <span class="mf">3</span><span class="p">],</span> <span class="n">help</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">print_help</span><span class="p">()</span>
<span class="go">usage: PROG [-h] [--foo FOO] [bar [bar ...]]</span>
<span class="go">positional arguments:</span>
<span class="go"> bar BAR! (default: [1, 2, 3])</span>
<span class="go">optional arguments:</span>
<span class="go"> -h, --help show this help message and exit</span>
<span class="go"> --foo FOO FOO! (default: 42)</span>
</pre></div>
</div>
</div>
<div class="section" id="conflict-handler">
<h2>conflict_handler<a class="headerlink" href="#conflict-handler" title="Permalink to this headline">¶</a></h2>
<p>ArgumentParser objects do not allow two actions with the same option string. By default, ArgumentParser objects will raise an exception if you try to create an argument with an option string that is already in use:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">prog</span><span class="o">=</span><span class="s">'PROG'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'-f'</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">'old foo help'</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">help</span><span class="o">=</span><span class="s">'new foo help'</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c"> ..</span>
<span class="nc">ArgumentError: argument --foo: conflicting option string(s)</span>: <span class="n-Identifier">--foo</span>
</pre></div>
</div>
<p>Sometimes (e.g. when using <a class="reference internal" href="#parents">parents</a>) it may be useful to simply override any older arguments with the same option string. To get this behavior, the value <tt class="docutils literal"><span class="pre">'resolve'</span></tt> can be supplied to the <tt class="docutils literal"><span class="pre">conflict_handler=</span></tt> argument of ArgumentParser:</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">conflict_handler</span><span class="o">=</span><span class="s">'resolve'</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">'-f'</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">'old foo help'</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">help</span><span class="o">=</span><span class="s">'new foo 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 [-h] [-f FOO] [--foo FOO]</span>
<span class="go">optional arguments:</span>
<span class="go"> -h, --help show this help message and exit</span>
<span class="go"> -f FOO old foo help</span>
<span class="go"> --foo FOO new foo help</span>
</pre></div>
</div>
<p>Note that ArgumentParser objects only remove an action if all of its option strings are overridden. So, in the example above, the old <tt class="docutils literal"><span class="pre">-f/--foo</span></tt> action is retained as the <tt class="docutils literal"><span class="pre">-f</span></tt> action, because only the <tt class="docutils literal"><span class="pre">--foo</span></tt> option string was overridden.</p>
</div>
<div class="section" id="prog">
<h2>prog<a class="headerlink" href="#prog" title="Permalink to this headline">¶</a></h2>
<p>By default, ArgumentParser objects use <tt class="docutils literal"><span class="pre">sys.argv[0]</span></tt> to determine how to display the name of the program in help messages. This default is almost always what you want because it will make the help messages match what your users have typed at the command line. For example, consider a file named <tt class="docutils literal"><span class="pre">myprogram.py</span></tt> with the following code:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">argparse</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">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">help</span><span class="o">=</span><span class="s">'foo help'</span><span class="p">)</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>
</pre></div>
</div>
<p>The help for this program will display <tt class="docutils literal"><span class="pre">myprogram.py</span></tt> as the program name (regardless of where the program was invoked from):</p>
<div class="highlight-python"><pre>$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo help
$ cd ..
$ python subdir\myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo help</pre>
</div>
<p>To change this default behavior, another value can be supplied using the <tt class="docutils literal"><span class="pre">prog=</span></tt> argument to ArgumentParser:</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">'myprogram'</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: myprogram [-h]</span>
<span class="go">optional arguments:</span>
<span class="go"> -h, --help show this help message and exit</span>
</pre></div>
</div>
<p>Note that the program name, whether determined from <tt class="docutils literal"><span class="pre">sys.argv[0]</span></tt> or from the <tt class="docutils literal"><span class="pre">prog=</span></tt> argument, is available to help messages using the <tt class="docutils literal"><span class="pre">%(prog)s</span></tt> format specifier.</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">'myprogram'</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">help</span><span class="o">=</span><span class="s">'foo of the </span><span class="si">%(prog)s</span><span class="s"> program'</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: myprogram [-h] [--foo FOO]</span>
<span class="go">optional arguments:</span>
<span class="go"> -h, --help show this help message and exit</span>
<span class="go"> --foo FOO foo of the myprogram program</span>
</pre></div>
</div>
</div>
<div class="section" id="usage">
<h2>usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
<p>By default, ArgumentParser objects calculate the usage message from the arguments it contains:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">prog</span><span class="o">=</span><span class="s">'PROG'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'--foo'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s">'?'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s">'foo help'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s">'+'</span><span class="p">,</span> <span class="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 [-h] [--foo [FOO]] bar [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="go"> --foo [FOO] foo help</span>
</pre></div>
</div>
<p>If the default usage message is not appropriate for your application, you can supply your own usage message using the <tt class="docutils literal"><span class="pre">usage=</span></tt> keyword argument to ArgumentParser:</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">usage</span><span class="o">=</span><span class="s">'</span><span class="si">%(prog)s</span><span class="s"> [options]'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'--foo'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s">'?'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s">'foo help'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s">'bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s">'+'</span><span class="p">,</span> <span class="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 [options]</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="go"> --foo [FOO] foo help</span>
</pre></div>
</div>
<p>Note you can use the <tt class="docutils literal"><span class="pre">%(prog)s</span></tt> format specifier to fill in the program name in your usage messages.</p>
</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="">ArgumentParser objects</a><ul>
<li><a class="reference external" href="#description">description</a></li>
<li><a class="reference external" href="#epilog">epilog</a></li>
<li><a class="reference external" href="#add-help">add_help</a></li>
<li><a class="reference external" href="#prefix-chars">prefix_chars</a></li>
<li><a class="reference external" href="#fromfile-prefix-chars">fromfile_prefix_chars</a></li>
<li><a class="reference external" href="#argument-default">argument_default</a></li>
<li><a class="reference external" href="#parents">parents</a></li>
<li><a class="reference external" href="#formatter-class">formatter_class</a></li>
<li><a class="reference external" href="#conflict-handler">conflict_handler</a></li>
<li><a class="reference external" href="#prog">prog</a></li>
<li><a class="reference external" href="#usage">usage</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="api-docs.html"
title="previous chapter">API documentation</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="add_argument.html"
title="next chapter">The add_argument() method</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/ArgumentParser.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="add_argument.html" title="The add_argument() method"
>next</a> |</li>
<li class="right" >
<a href="api-docs.html" title="API documentation"
>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>
|
