blob: 1b80d2ad7f8b3720be0d955efdf4082703ea0232 [file] [log] [blame]
Georg Brandl1d827ff2011-04-16 16:44:54 +02001:mod:`argparse` --- Parser for command-line options, arguments and sub-commands
Georg Brandle0bf91d2010-10-17 10:34:28 +00002===============================================================================
Benjamin Peterson698a18a2010-03-02 22:34:37 +00003
4.. module:: argparse
Éric Araujod9d7bca2011-08-10 04:19:03 +02005 :synopsis: Command-line option and argument parsing library.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00006.. moduleauthor:: Steven Bethard <steven.bethard@gmail.com>
Benjamin Peterson698a18a2010-03-02 22:34:37 +00007.. sectionauthor:: Steven Bethard <steven.bethard@gmail.com>
8
Raymond Hettingera1993682011-01-27 01:20:32 +00009.. versionadded:: 3.2
10
Éric Araujo19f9b712011-08-19 00:49:18 +020011**Source code:** :source:`Lib/argparse.py`
12
Raymond Hettingera1993682011-01-27 01:20:32 +000013--------------
Benjamin Peterson698a18a2010-03-02 22:34:37 +000014
Ezio Melotti6cc7a412012-05-06 16:15:35 +030015.. sidebar:: Tutorial
16
17 This page contains the API reference information. For a more gentle
18 introduction to Python command-line parsing, have a look at the
19 :ref:`argparse tutorial <argparse-tutorial>`.
20
Ezio Melotti2409d772011-04-16 23:13:50 +030021The :mod:`argparse` module makes it easy to write user-friendly command-line
Benjamin Peterson98047eb2010-03-03 02:07:08 +000022interfaces. The program defines what arguments it requires, and :mod:`argparse`
Benjamin Peterson698a18a2010-03-02 22:34:37 +000023will figure out how to parse those out of :data:`sys.argv`. The :mod:`argparse`
Benjamin Peterson98047eb2010-03-03 02:07:08 +000024module also automatically generates help and usage messages and issues errors
25when users give the program invalid arguments.
Benjamin Peterson698a18a2010-03-02 22:34:37 +000026
Georg Brandle0bf91d2010-10-17 10:34:28 +000027
Benjamin Peterson698a18a2010-03-02 22:34:37 +000028Example
29-------
30
Benjamin Peterson98047eb2010-03-03 02:07:08 +000031The following code is a Python program that takes a list of integers and
32produces either the sum or the max::
Benjamin Peterson698a18a2010-03-02 22:34:37 +000033
34 import argparse
35
36 parser = argparse.ArgumentParser(description='Process some integers.')
37 parser.add_argument('integers', metavar='N', type=int, nargs='+',
38 help='an integer for the accumulator')
39 parser.add_argument('--sum', dest='accumulate', action='store_const',
40 const=sum, default=max,
41 help='sum the integers (default: find the max)')
42
43 args = parser.parse_args()
Benjamin Petersonb2deb112010-03-03 02:09:18 +000044 print(args.accumulate(args.integers))
Benjamin Peterson698a18a2010-03-02 22:34:37 +000045
46Assuming the Python code above is saved into a file called ``prog.py``, it can
47be run at the command line and provides useful help messages::
48
49 $ prog.py -h
50 usage: prog.py [-h] [--sum] N [N ...]
51
52 Process some integers.
53
54 positional arguments:
55 N an integer for the accumulator
56
57 optional arguments:
58 -h, --help show this help message and exit
59 --sum sum the integers (default: find the max)
60
61When run with the appropriate arguments, it prints either the sum or the max of
62the command-line integers::
63
64 $ prog.py 1 2 3 4
65 4
66
67 $ prog.py 1 2 3 4 --sum
68 10
69
70If invalid arguments are passed in, it will issue an error::
71
72 $ prog.py a b c
73 usage: prog.py [-h] [--sum] N [N ...]
74 prog.py: error: argument N: invalid int value: 'a'
75
76The following sections walk you through this example.
77
Georg Brandle0bf91d2010-10-17 10:34:28 +000078
Benjamin Peterson698a18a2010-03-02 22:34:37 +000079Creating a parser
80^^^^^^^^^^^^^^^^^
81
Benjamin Peterson2614cda2010-03-21 22:36:19 +000082The first step in using the :mod:`argparse` is creating an
Benjamin Peterson98047eb2010-03-03 02:07:08 +000083:class:`ArgumentParser` object::
Benjamin Peterson698a18a2010-03-02 22:34:37 +000084
85 >>> parser = argparse.ArgumentParser(description='Process some integers.')
86
87The :class:`ArgumentParser` object will hold all the information necessary to
Ezio Melotticca4ef82011-04-21 15:26:46 +030088parse the command line into Python data types.
Benjamin Peterson698a18a2010-03-02 22:34:37 +000089
90
91Adding arguments
92^^^^^^^^^^^^^^^^
93
Benjamin Peterson98047eb2010-03-03 02:07:08 +000094Filling an :class:`ArgumentParser` with information about program arguments is
95done by making calls to the :meth:`~ArgumentParser.add_argument` method.
96Generally, these calls tell the :class:`ArgumentParser` how to take the strings
97on the command line and turn them into objects. This information is stored and
98used when :meth:`~ArgumentParser.parse_args` is called. For example::
Benjamin Peterson698a18a2010-03-02 22:34:37 +000099
100 >>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
101 ... help='an integer for the accumulator')
102 >>> parser.add_argument('--sum', dest='accumulate', action='store_const',
103 ... const=sum, default=max,
104 ... help='sum the integers (default: find the max)')
105
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300106Later, calling :meth:`~ArgumentParser.parse_args` will return an object with
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000107two attributes, ``integers`` and ``accumulate``. The ``integers`` attribute
108will be a list of one or more ints, and the ``accumulate`` attribute will be
109either the :func:`sum` function, if ``--sum`` was specified at the command line,
110or the :func:`max` function if it was not.
111
Georg Brandle0bf91d2010-10-17 10:34:28 +0000112
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000113Parsing arguments
114^^^^^^^^^^^^^^^^^
115
Éric Araujod9d7bca2011-08-10 04:19:03 +0200116:class:`ArgumentParser` parses arguments through the
Georg Brandl1d827ff2011-04-16 16:44:54 +0200117:meth:`~ArgumentParser.parse_args` method. This will inspect the command line,
Éric Araujofde92422011-08-19 01:30:26 +0200118convert each argument to the appropriate type and then invoke the appropriate action.
Éric Araujo63b18a42011-07-29 17:59:17 +0200119In most cases, this means a simple :class:`Namespace` object will be built up from
Georg Brandl1d827ff2011-04-16 16:44:54 +0200120attributes parsed out of the command line::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000121
122 >>> parser.parse_args(['--sum', '7', '-1', '42'])
123 Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])
124
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000125In a script, :meth:`~ArgumentParser.parse_args` will typically be called with no
126arguments, and the :class:`ArgumentParser` will automatically determine the
Éric Araujod9d7bca2011-08-10 04:19:03 +0200127command-line arguments from :data:`sys.argv`.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000128
129
130ArgumentParser objects
131----------------------
132
Ezio Melottie0add762012-09-14 06:32:35 +0300133.. class:: ArgumentParser(prog=None, usage=None, description=None, \
134 epilog=None, parents=[], \
135 formatter_class=argparse.HelpFormatter, \
136 prefix_chars='-', fromfile_prefix_chars=None, \
137 argument_default=None, conflict_handler='error', \
138 add_help=True)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000139
140 Create a new :class:`ArgumentParser` object. Each parameter has its own more
141 detailed description below, but in short they are:
142
143 * description_ - Text to display before the argument help.
144
145 * epilog_ - Text to display after the argument help.
146
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000147 * add_help_ - Add a -h/--help option to the parser. (default: ``True``)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000148
149 * argument_default_ - Set the global default value for arguments.
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000150 (default: ``None``)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000151
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000152 * parents_ - A list of :class:`ArgumentParser` objects whose arguments should
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000153 also be included.
154
155 * prefix_chars_ - The set of characters that prefix optional arguments.
156 (default: '-')
157
158 * fromfile_prefix_chars_ - The set of characters that prefix files from
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000159 which additional arguments should be read. (default: ``None``)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000160
161 * formatter_class_ - A class for customizing the help output.
162
163 * conflict_handler_ - Usually unnecessary, defines strategy for resolving
164 conflicting optionals.
165
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000166 * prog_ - The name of the program (default:
Éric Araujo37b5f9e2011-09-01 03:19:30 +0200167 ``sys.argv[0]``)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000168
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000169 * usage_ - The string describing the program usage (default: generated)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000170
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000171The following sections describe how each of these are used.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000172
173
174description
175^^^^^^^^^^^
176
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000177Most calls to the :class:`ArgumentParser` constructor will use the
178``description=`` keyword argument. This argument gives a brief description of
179what the program does and how it works. In help messages, the description is
180displayed between the command-line usage string and the help messages for the
181various arguments::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000182
183 >>> parser = argparse.ArgumentParser(description='A foo that bars')
184 >>> parser.print_help()
185 usage: argparse.py [-h]
186
187 A foo that bars
188
189 optional arguments:
190 -h, --help show this help message and exit
191
192By default, the description will be line-wrapped so that it fits within the
193given space. To change this behavior, see the formatter_class_ argument.
194
195
196epilog
197^^^^^^
198
199Some programs like to display additional description of the program after the
200description of the arguments. Such text can be specified using the ``epilog=``
201argument to :class:`ArgumentParser`::
202
203 >>> parser = argparse.ArgumentParser(
204 ... description='A foo that bars',
205 ... epilog="And that's how you'd foo a bar")
206 >>> parser.print_help()
207 usage: argparse.py [-h]
208
209 A foo that bars
210
211 optional arguments:
212 -h, --help show this help message and exit
213
214 And that's how you'd foo a bar
215
216As with the description_ argument, the ``epilog=`` text is by default
217line-wrapped, but this behavior can be adjusted with the formatter_class_
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000218argument to :class:`ArgumentParser`.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000219
220
221add_help
222^^^^^^^^
223
R. David Murray88c49fe2010-08-03 17:56:09 +0000224By default, ArgumentParser objects add an option which simply displays
225the parser's help message. For example, consider a file named
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000226``myprogram.py`` containing the following code::
227
228 import argparse
229 parser = argparse.ArgumentParser()
230 parser.add_argument('--foo', help='foo help')
231 args = parser.parse_args()
232
Georg Brandl1d827ff2011-04-16 16:44:54 +0200233If ``-h`` or ``--help`` is supplied at the command line, the ArgumentParser
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000234help will be printed::
235
236 $ python myprogram.py --help
237 usage: myprogram.py [-h] [--foo FOO]
238
239 optional arguments:
240 -h, --help show this help message and exit
241 --foo FOO foo help
242
243Occasionally, it may be useful to disable the addition of this help option.
244This can be achieved by passing ``False`` as the ``add_help=`` argument to
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000245:class:`ArgumentParser`::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000246
247 >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
248 >>> parser.add_argument('--foo', help='foo help')
249 >>> parser.print_help()
250 usage: PROG [--foo FOO]
251
252 optional arguments:
253 --foo FOO foo help
254
R. David Murray88c49fe2010-08-03 17:56:09 +0000255The help option is typically ``-h/--help``. The exception to this is
Éric Araujo543edbd2011-08-19 01:45:12 +0200256if the ``prefix_chars=`` is specified and does not include ``-``, in
R. David Murray88c49fe2010-08-03 17:56:09 +0000257which case ``-h`` and ``--help`` are not valid options. In
258this case, the first character in ``prefix_chars`` is used to prefix
259the help options::
260
261 >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
262 >>> parser.print_help()
263 usage: PROG [+h]
264
265 optional arguments:
266 +h, ++help show this help message and exit
267
268
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000269prefix_chars
270^^^^^^^^^^^^
271
Éric Araujo543edbd2011-08-19 01:45:12 +0200272Most command-line options will use ``-`` as the prefix, e.g. ``-f/--foo``.
R. David Murray88c49fe2010-08-03 17:56:09 +0000273Parsers that need to support different or additional prefix
274characters, e.g. for options
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000275like ``+f`` or ``/foo``, may specify them using the ``prefix_chars=`` argument
276to the ArgumentParser constructor::
277
278 >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
279 >>> parser.add_argument('+f')
280 >>> parser.add_argument('++bar')
281 >>> parser.parse_args('+f X ++bar Y'.split())
282 Namespace(bar='Y', f='X')
283
284The ``prefix_chars=`` argument defaults to ``'-'``. Supplying a set of
Éric Araujo543edbd2011-08-19 01:45:12 +0200285characters that does not include ``-`` will cause ``-f/--foo`` options to be
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000286disallowed.
287
288
289fromfile_prefix_chars
290^^^^^^^^^^^^^^^^^^^^^
291
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000292Sometimes, for example when dealing with a particularly long argument lists, it
293may make sense to keep the list of arguments in a file rather than typing it out
294at the command line. If the ``fromfile_prefix_chars=`` argument is given to the
295:class:`ArgumentParser` constructor, then arguments that start with any of the
296specified characters will be treated as files, and will be replaced by the
297arguments they contain. For example::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000298
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000299 >>> with open('args.txt', 'w') as fp:
300 ... fp.write('-f\nbar')
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000301 >>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
302 >>> parser.add_argument('-f')
303 >>> parser.parse_args(['-f', 'foo', '@args.txt'])
304 Namespace(f='bar')
305
306Arguments read from a file must by default be one per line (but see also
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300307:meth:`~ArgumentParser.convert_arg_line_to_args`) and are treated as if they
308were in the same place as the original file referencing argument on the command
309line. So in the example above, the expression ``['-f', 'foo', '@args.txt']``
310is considered equivalent to the expression ``['-f', 'foo', '-f', 'bar']``.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000311
312The ``fromfile_prefix_chars=`` argument defaults to ``None``, meaning that
313arguments will never be treated as file references.
314
Georg Brandle0bf91d2010-10-17 10:34:28 +0000315
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000316argument_default
317^^^^^^^^^^^^^^^^
318
319Generally, argument defaults are specified either by passing a default to
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300320:meth:`~ArgumentParser.add_argument` or by calling the
321:meth:`~ArgumentParser.set_defaults` methods with a specific set of name-value
322pairs. Sometimes however, it may be useful to specify a single parser-wide
323default for arguments. This can be accomplished by passing the
324``argument_default=`` keyword argument to :class:`ArgumentParser`. For example,
325to globally suppress attribute creation on :meth:`~ArgumentParser.parse_args`
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000326calls, we supply ``argument_default=SUPPRESS``::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000327
328 >>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
329 >>> parser.add_argument('--foo')
330 >>> parser.add_argument('bar', nargs='?')
331 >>> parser.parse_args(['--foo', '1', 'BAR'])
332 Namespace(bar='BAR', foo='1')
333 >>> parser.parse_args([])
334 Namespace()
335
336
337parents
338^^^^^^^
339
340Sometimes, several parsers share a common set of arguments. Rather than
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000341repeating the definitions of these arguments, a single parser with all the
342shared arguments and passed to ``parents=`` argument to :class:`ArgumentParser`
343can be used. The ``parents=`` argument takes a list of :class:`ArgumentParser`
344objects, collects all the positional and optional actions from them, and adds
345these actions to the :class:`ArgumentParser` object being constructed::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000346
347 >>> parent_parser = argparse.ArgumentParser(add_help=False)
348 >>> parent_parser.add_argument('--parent', type=int)
349
350 >>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
351 >>> foo_parser.add_argument('foo')
352 >>> foo_parser.parse_args(['--parent', '2', 'XXX'])
353 Namespace(foo='XXX', parent=2)
354
355 >>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
356 >>> bar_parser.add_argument('--bar')
357 >>> bar_parser.parse_args(['--bar', 'YYY'])
358 Namespace(bar='YYY', parent=None)
359
360Note that most parent parsers will specify ``add_help=False``. Otherwise, the
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000361:class:`ArgumentParser` will see two ``-h/--help`` options (one in the parent
362and one in the child) and raise an error.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000363
Steven Bethardd186f992011-03-26 21:49:00 +0100364.. note::
365 You must fully initialize the parsers before passing them via ``parents=``.
366 If you change the parent parsers after the child parser, those changes will
367 not be reflected in the child.
368
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000369
370formatter_class
371^^^^^^^^^^^^^^^
372
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000373:class:`ArgumentParser` objects allow the help formatting to be customized by
374specifying an alternate formatting class. Currently, there are three such
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300375classes:
376
377.. class:: RawDescriptionHelpFormatter
378 RawTextHelpFormatter
379 ArgumentDefaultsHelpFormatter
380
381The first two allow more control over how textual descriptions are displayed,
382while the last automatically adds information about argument default values.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000383
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000384By default, :class:`ArgumentParser` objects line-wrap the description_ and
385epilog_ texts in command-line help messages::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000386
387 >>> parser = argparse.ArgumentParser(
388 ... prog='PROG',
389 ... description='''this description
390 ... was indented weird
391 ... but that is okay''',
392 ... epilog='''
393 ... likewise for this epilog whose whitespace will
394 ... be cleaned up and whose words will be wrapped
395 ... across a couple lines''')
396 >>> parser.print_help()
397 usage: PROG [-h]
398
399 this description was indented weird but that is okay
400
401 optional arguments:
402 -h, --help show this help message and exit
403
404 likewise for this epilog whose whitespace will be cleaned up and whose words
405 will be wrapped across a couple lines
406
Éric Araujo543edbd2011-08-19 01:45:12 +0200407Passing :class:`RawDescriptionHelpFormatter` as ``formatter_class=``
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000408indicates that description_ and epilog_ are already correctly formatted and
409should not be line-wrapped::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000410
411 >>> parser = argparse.ArgumentParser(
412 ... prog='PROG',
413 ... formatter_class=argparse.RawDescriptionHelpFormatter,
414 ... description=textwrap.dedent('''\
415 ... Please do not mess up this text!
416 ... --------------------------------
417 ... I have indented it
418 ... exactly the way
419 ... I want it
420 ... '''))
421 >>> parser.print_help()
422 usage: PROG [-h]
423
424 Please do not mess up this text!
425 --------------------------------
426 I have indented it
427 exactly the way
428 I want it
429
430 optional arguments:
431 -h, --help show this help message and exit
432
Éric Araujo543edbd2011-08-19 01:45:12 +0200433:class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text,
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000434including argument descriptions.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000435
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000436The other formatter class available, :class:`ArgumentDefaultsHelpFormatter`,
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000437will add information about the default value of each of the arguments::
438
439 >>> parser = argparse.ArgumentParser(
440 ... prog='PROG',
441 ... formatter_class=argparse.ArgumentDefaultsHelpFormatter)
442 >>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
443 >>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
444 >>> parser.print_help()
445 usage: PROG [-h] [--foo FOO] [bar [bar ...]]
446
447 positional arguments:
448 bar BAR! (default: [1, 2, 3])
449
450 optional arguments:
451 -h, --help show this help message and exit
452 --foo FOO FOO! (default: 42)
453
454
455conflict_handler
456^^^^^^^^^^^^^^^^
457
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000458:class:`ArgumentParser` objects do not allow two actions with the same option
459string. By default, :class:`ArgumentParser` objects raises an exception if an
460attempt is made to create an argument with an option string that is already in
461use::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000462
463 >>> parser = argparse.ArgumentParser(prog='PROG')
464 >>> parser.add_argument('-f', '--foo', help='old foo help')
465 >>> parser.add_argument('--foo', help='new foo help')
466 Traceback (most recent call last):
467 ..
468 ArgumentError: argument --foo: conflicting option string(s): --foo
469
470Sometimes (e.g. when using parents_) it may be useful to simply override any
471older arguments with the same option string. To get this behavior, the value
472``'resolve'`` can be supplied to the ``conflict_handler=`` argument of
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000473:class:`ArgumentParser`::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000474
475 >>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
476 >>> parser.add_argument('-f', '--foo', help='old foo help')
477 >>> parser.add_argument('--foo', help='new foo help')
478 >>> parser.print_help()
479 usage: PROG [-h] [-f FOO] [--foo FOO]
480
481 optional arguments:
482 -h, --help show this help message and exit
483 -f FOO old foo help
484 --foo FOO new foo help
485
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000486Note that :class:`ArgumentParser` objects only remove an action if all of its
487option strings are overridden. So, in the example above, the old ``-f/--foo``
488action is retained as the ``-f`` action, because only the ``--foo`` option
489string was overridden.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000490
491
492prog
493^^^^
494
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000495By default, :class:`ArgumentParser` objects uses ``sys.argv[0]`` to determine
496how to display the name of the program in help messages. This default is almost
Ezio Melottif82340d2010-05-27 22:38:16 +0000497always desirable because it will make the help messages match how the program was
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000498invoked on the command line. For example, consider a file named
499``myprogram.py`` with the following code::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000500
501 import argparse
502 parser = argparse.ArgumentParser()
503 parser.add_argument('--foo', help='foo help')
504 args = parser.parse_args()
505
506The help for this program will display ``myprogram.py`` as the program name
507(regardless of where the program was invoked from)::
508
509 $ python myprogram.py --help
510 usage: myprogram.py [-h] [--foo FOO]
511
512 optional arguments:
513 -h, --help show this help message and exit
514 --foo FOO foo help
515 $ cd ..
516 $ python subdir\myprogram.py --help
517 usage: myprogram.py [-h] [--foo FOO]
518
519 optional arguments:
520 -h, --help show this help message and exit
521 --foo FOO foo help
522
523To change this default behavior, another value can be supplied using the
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000524``prog=`` argument to :class:`ArgumentParser`::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000525
526 >>> parser = argparse.ArgumentParser(prog='myprogram')
527 >>> parser.print_help()
528 usage: myprogram [-h]
529
530 optional arguments:
531 -h, --help show this help message and exit
532
533Note that the program name, whether determined from ``sys.argv[0]`` or from the
534``prog=`` argument, is available to help messages using the ``%(prog)s`` format
535specifier.
536
537::
538
539 >>> parser = argparse.ArgumentParser(prog='myprogram')
540 >>> parser.add_argument('--foo', help='foo of the %(prog)s program')
541 >>> parser.print_help()
542 usage: myprogram [-h] [--foo FOO]
543
544 optional arguments:
545 -h, --help show this help message and exit
546 --foo FOO foo of the myprogram program
547
548
549usage
550^^^^^
551
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000552By default, :class:`ArgumentParser` calculates the usage message from the
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000553arguments it contains::
554
555 >>> parser = argparse.ArgumentParser(prog='PROG')
556 >>> parser.add_argument('--foo', nargs='?', help='foo help')
557 >>> parser.add_argument('bar', nargs='+', help='bar help')
558 >>> parser.print_help()
559 usage: PROG [-h] [--foo [FOO]] bar [bar ...]
560
561 positional arguments:
562 bar bar help
563
564 optional arguments:
565 -h, --help show this help message and exit
566 --foo [FOO] foo help
567
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000568The default message can be overridden with the ``usage=`` keyword argument::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000569
570 >>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
571 >>> parser.add_argument('--foo', nargs='?', help='foo help')
572 >>> parser.add_argument('bar', nargs='+', help='bar help')
573 >>> parser.print_help()
574 usage: PROG [options]
575
576 positional arguments:
577 bar bar help
578
579 optional arguments:
580 -h, --help show this help message and exit
581 --foo [FOO] foo help
582
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000583The ``%(prog)s`` format specifier is available to fill in the program name in
584your usage messages.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000585
586
587The add_argument() method
588-------------------------
589
Georg Brandlc9007082011-01-09 09:04:08 +0000590.. method:: ArgumentParser.add_argument(name or flags..., [action], [nargs], \
591 [const], [default], [type], [choices], [required], \
592 [help], [metavar], [dest])
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000593
Georg Brandl1d827ff2011-04-16 16:44:54 +0200594 Define how a single command-line argument should be parsed. Each parameter
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000595 has its own more detailed description below, but in short they are:
596
597 * `name or flags`_ - Either a name or a list of option strings, e.g. ``foo``
Ezio Melottidca309d2011-04-21 23:09:27 +0300598 or ``-f, --foo``.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000599
600 * action_ - The basic type of action to be taken when this argument is
Georg Brandl1d827ff2011-04-16 16:44:54 +0200601 encountered at the command line.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000602
603 * nargs_ - The number of command-line arguments that should be consumed.
604
605 * const_ - A constant value required by some action_ and nargs_ selections.
606
607 * default_ - The value produced if the argument is absent from the
Georg Brandl1d827ff2011-04-16 16:44:54 +0200608 command line.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000609
Ezio Melotti2409d772011-04-16 23:13:50 +0300610 * type_ - The type to which the command-line argument should be converted.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000611
612 * choices_ - A container of the allowable values for the argument.
613
614 * required_ - Whether or not the command-line option may be omitted
615 (optionals only).
616
617 * help_ - A brief description of what the argument does.
618
619 * metavar_ - A name for the argument in usage messages.
620
621 * dest_ - The name of the attribute to be added to the object returned by
622 :meth:`parse_args`.
623
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000624The following sections describe how each of these are used.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000625
Georg Brandle0bf91d2010-10-17 10:34:28 +0000626
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000627name or flags
628^^^^^^^^^^^^^
629
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300630The :meth:`~ArgumentParser.add_argument` method must know whether an optional
631argument, like ``-f`` or ``--foo``, or a positional argument, like a list of
632filenames, is expected. The first arguments passed to
633:meth:`~ArgumentParser.add_argument` must therefore be either a series of
634flags, or a simple argument name. For example, an optional argument could
635be created like::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000636
637 >>> parser.add_argument('-f', '--foo')
638
639while a positional argument could be created like::
640
641 >>> parser.add_argument('bar')
642
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300643When :meth:`~ArgumentParser.parse_args` is called, optional arguments will be
644identified by the ``-`` prefix, and the remaining arguments will be assumed to
645be positional::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000646
647 >>> parser = argparse.ArgumentParser(prog='PROG')
648 >>> parser.add_argument('-f', '--foo')
649 >>> parser.add_argument('bar')
650 >>> parser.parse_args(['BAR'])
651 Namespace(bar='BAR', foo=None)
652 >>> parser.parse_args(['BAR', '--foo', 'FOO'])
653 Namespace(bar='BAR', foo='FOO')
654 >>> parser.parse_args(['--foo', 'FOO'])
655 usage: PROG [-h] [-f FOO] bar
656 PROG: error: too few arguments
657
Georg Brandle0bf91d2010-10-17 10:34:28 +0000658
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000659action
660^^^^^^
661
Éric Araujod9d7bca2011-08-10 04:19:03 +0200662:class:`ArgumentParser` objects associate command-line arguments with actions. These
663actions can do just about anything with the command-line arguments associated with
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000664them, though most actions simply add an attribute to the object returned by
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300665:meth:`~ArgumentParser.parse_args`. The ``action`` keyword argument specifies
Éric Araujod9d7bca2011-08-10 04:19:03 +0200666how the command-line arguments should be handled. The supported actions are:
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000667
668* ``'store'`` - This just stores the argument's value. This is the default
Ezio Melotti2f1db7d2011-04-21 23:06:48 +0300669 action. For example::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000670
671 >>> parser = argparse.ArgumentParser()
672 >>> parser.add_argument('--foo')
673 >>> parser.parse_args('--foo 1'.split())
674 Namespace(foo='1')
675
676* ``'store_const'`` - This stores the value specified by the const_ keyword
Ezio Melotti2f1db7d2011-04-21 23:06:48 +0300677 argument. (Note that the const_ keyword argument defaults to the rather
678 unhelpful ``None``.) The ``'store_const'`` action is most commonly used with
679 optional arguments that specify some sort of flag. For example::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000680
681 >>> parser = argparse.ArgumentParser()
682 >>> parser.add_argument('--foo', action='store_const', const=42)
683 >>> parser.parse_args('--foo'.split())
684 Namespace(foo=42)
685
686* ``'store_true'`` and ``'store_false'`` - These store the values ``True`` and
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000687 ``False`` respectively. These are special cases of ``'store_const'``. For
688 example::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000689
690 >>> parser = argparse.ArgumentParser()
691 >>> parser.add_argument('--foo', action='store_true')
692 >>> parser.add_argument('--bar', action='store_false')
693 >>> parser.parse_args('--foo --bar'.split())
694 Namespace(bar=False, foo=True)
695
696* ``'append'`` - This stores a list, and appends each argument value to the
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000697 list. This is useful to allow an option to be specified multiple times.
698 Example usage::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000699
700 >>> parser = argparse.ArgumentParser()
701 >>> parser.add_argument('--foo', action='append')
702 >>> parser.parse_args('--foo 1 --foo 2'.split())
703 Namespace(foo=['1', '2'])
704
705* ``'append_const'`` - This stores a list, and appends the value specified by
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000706 the const_ keyword argument to the list. (Note that the const_ keyword
707 argument defaults to ``None``.) The ``'append_const'`` action is typically
708 useful when multiple arguments need to store constants to the same list. For
709 example::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000710
711 >>> parser = argparse.ArgumentParser()
712 >>> parser.add_argument('--str', dest='types', action='append_const', const=str)
713 >>> parser.add_argument('--int', dest='types', action='append_const', const=int)
714 >>> parser.parse_args('--str --int'.split())
Florent Xicluna74e64952011-10-28 11:21:19 +0200715 Namespace(types=[<class 'str'>, <class 'int'>])
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000716
Sandro Tosi98492a52012-01-04 23:25:04 +0100717* ``'count'`` - This counts the number of times a keyword argument occurs. For
718 example, this is useful for increasing verbosity levels::
719
720 >>> parser = argparse.ArgumentParser()
721 >>> parser.add_argument('--verbose', '-v', action='count')
722 >>> parser.parse_args('-vvv'.split())
723 Namespace(verbose=3)
724
725* ``'help'`` - This prints a complete help message for all the options in the
726 current parser and then exits. By default a help action is automatically
727 added to the parser. See :class:`ArgumentParser` for details of how the
728 output is created.
729
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000730* ``'version'`` - This expects a ``version=`` keyword argument in the
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300731 :meth:`~ArgumentParser.add_argument` call, and prints version information
Éric Araujoc3ef0372012-02-20 01:44:55 +0100732 and exits when invoked::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000733
734 >>> import argparse
735 >>> parser = argparse.ArgumentParser(prog='PROG')
Steven Bethard59710962010-05-24 03:21:08 +0000736 >>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')
737 >>> parser.parse_args(['--version'])
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000738 PROG 2.0
739
740You can also specify an arbitrary action by passing an object that implements
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000741the Action API. The easiest way to do this is to extend
742:class:`argparse.Action`, supplying an appropriate ``__call__`` method. The
743``__call__`` method should accept four parameters:
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000744
745* ``parser`` - The ArgumentParser object which contains this action.
746
Éric Araujo63b18a42011-07-29 17:59:17 +0200747* ``namespace`` - The :class:`Namespace` object that will be returned by
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300748 :meth:`~ArgumentParser.parse_args`. Most actions add an attribute to this
749 object.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000750
Éric Araujod9d7bca2011-08-10 04:19:03 +0200751* ``values`` - The associated command-line arguments, with any type conversions
752 applied. (Type conversions are specified with the type_ keyword argument to
Sandro Tosiee903c52012-08-12 10:49:26 +0200753 :meth:`~ArgumentParser.add_argument`.)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000754
755* ``option_string`` - The option string that was used to invoke this action.
756 The ``option_string`` argument is optional, and will be absent if the action
757 is associated with a positional argument.
758
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000759An example of a custom action::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000760
761 >>> class FooAction(argparse.Action):
762 ... def __call__(self, parser, namespace, values, option_string=None):
Georg Brandl571a9532010-07-26 17:00:20 +0000763 ... print('%r %r %r' % (namespace, values, option_string))
764 ... setattr(namespace, self.dest, values)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000765 ...
766 >>> parser = argparse.ArgumentParser()
767 >>> parser.add_argument('--foo', action=FooAction)
768 >>> parser.add_argument('bar', action=FooAction)
769 >>> args = parser.parse_args('1 --foo 2'.split())
770 Namespace(bar=None, foo=None) '1' None
771 Namespace(bar='1', foo=None) '2' '--foo'
772 >>> args
773 Namespace(bar='1', foo='2')
774
775
776nargs
777^^^^^
778
779ArgumentParser objects usually associate a single command-line argument with a
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000780single action to be taken. The ``nargs`` keyword argument associates a
Ezio Melotti00f53af2011-04-21 22:56:51 +0300781different number of command-line arguments with a single action. The supported
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000782values are:
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000783
Éric Araujoc3ef0372012-02-20 01:44:55 +0100784* ``N`` (an integer). ``N`` arguments from the command line will be gathered
785 together into a list. For example::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000786
Georg Brandl682d7e02010-10-06 10:26:05 +0000787 >>> parser = argparse.ArgumentParser()
788 >>> parser.add_argument('--foo', nargs=2)
789 >>> parser.add_argument('bar', nargs=1)
790 >>> parser.parse_args('c --foo a b'.split())
791 Namespace(bar=['c'], foo=['a', 'b'])
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000792
Georg Brandl682d7e02010-10-06 10:26:05 +0000793 Note that ``nargs=1`` produces a list of one item. This is different from
794 the default, in which the item is produced by itself.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000795
Éric Araujofde92422011-08-19 01:30:26 +0200796* ``'?'``. One argument will be consumed from the command line if possible, and
797 produced as a single item. If no command-line argument is present, the value from
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000798 default_ will be produced. Note that for optional arguments, there is an
799 additional case - the option string is present but not followed by a
Éric Araujofde92422011-08-19 01:30:26 +0200800 command-line argument. In this case the value from const_ will be produced. Some
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000801 examples to illustrate this::
802
803 >>> parser = argparse.ArgumentParser()
804 >>> parser.add_argument('--foo', nargs='?', const='c', default='d')
805 >>> parser.add_argument('bar', nargs='?', default='d')
806 >>> parser.parse_args('XX --foo YY'.split())
807 Namespace(bar='XX', foo='YY')
808 >>> parser.parse_args('XX --foo'.split())
809 Namespace(bar='XX', foo='c')
810 >>> parser.parse_args(''.split())
811 Namespace(bar='d', foo='d')
812
813 One of the more common uses of ``nargs='?'`` is to allow optional input and
814 output files::
815
816 >>> parser = argparse.ArgumentParser()
Georg Brandle0bf91d2010-10-17 10:34:28 +0000817 >>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
818 ... default=sys.stdin)
819 >>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
820 ... default=sys.stdout)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000821 >>> parser.parse_args(['input.txt', 'output.txt'])
Georg Brandl04536b02011-01-09 09:31:01 +0000822 Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,
823 outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000824 >>> parser.parse_args([])
Georg Brandl04536b02011-01-09 09:31:01 +0000825 Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>,
826 outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000827
Éric Araujod9d7bca2011-08-10 04:19:03 +0200828* ``'*'``. All command-line arguments present are gathered into a list. Note that
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000829 it generally doesn't make much sense to have more than one positional argument
830 with ``nargs='*'``, but multiple optional arguments with ``nargs='*'`` is
831 possible. For example::
832
833 >>> parser = argparse.ArgumentParser()
834 >>> parser.add_argument('--foo', nargs='*')
835 >>> parser.add_argument('--bar', nargs='*')
836 >>> parser.add_argument('baz', nargs='*')
837 >>> parser.parse_args('a b --foo x y --bar 1 2'.split())
838 Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])
839
840* ``'+'``. Just like ``'*'``, all command-line args present are gathered into a
841 list. Additionally, an error message will be generated if there wasn't at
Éric Araujofde92422011-08-19 01:30:26 +0200842 least one command-line argument present. For example::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000843
844 >>> parser = argparse.ArgumentParser(prog='PROG')
845 >>> parser.add_argument('foo', nargs='+')
846 >>> parser.parse_args('a b'.split())
847 Namespace(foo=['a', 'b'])
848 >>> parser.parse_args(''.split())
849 usage: PROG [-h] foo [foo ...]
850 PROG: error: too few arguments
851
Sandro Tosida8e11a2012-01-19 22:23:00 +0100852* ``argparse.REMAINDER``. All the remaining command-line arguments are gathered
853 into a list. This is commonly useful for command line utilities that dispatch
Éric Araujoc3ef0372012-02-20 01:44:55 +0100854 to other command line utilities::
Sandro Tosi16bd0b42012-01-19 21:59:55 +0100855
856 >>> parser = argparse.ArgumentParser(prog='PROG')
857 >>> parser.add_argument('--foo')
858 >>> parser.add_argument('command')
859 >>> parser.add_argument('args', nargs=argparse.REMAINDER)
Sandro Tosi04676862012-02-19 19:54:00 +0100860 >>> print(parser.parse_args('--foo B cmd --arg1 XX ZZ'.split()))
Sandro Tosida8e11a2012-01-19 22:23:00 +0100861 Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')
Sandro Tosi16bd0b42012-01-19 21:59:55 +0100862
Éric Araujod9d7bca2011-08-10 04:19:03 +0200863If the ``nargs`` keyword argument is not provided, the number of arguments consumed
Éric Araujofde92422011-08-19 01:30:26 +0200864is determined by the action_. Generally this means a single command-line argument
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000865will be consumed and a single item (not a list) will be produced.
866
867
868const
869^^^^^
870
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300871The ``const`` argument of :meth:`~ArgumentParser.add_argument` is used to hold
872constant values that are not read from the command line but are required for
873the various :class:`ArgumentParser` actions. The two most common uses of it are:
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000874
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300875* When :meth:`~ArgumentParser.add_argument` is called with
876 ``action='store_const'`` or ``action='append_const'``. These actions add the
Éric Araujoc3ef0372012-02-20 01:44:55 +0100877 ``const`` value to one of the attributes of the object returned by
878 :meth:`~ArgumentParser.parse_args`. See the action_ description for examples.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000879
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300880* When :meth:`~ArgumentParser.add_argument` is called with option strings
881 (like ``-f`` or ``--foo``) and ``nargs='?'``. This creates an optional
Éric Araujod9d7bca2011-08-10 04:19:03 +0200882 argument that can be followed by zero or one command-line arguments.
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300883 When parsing the command line, if the option string is encountered with no
Éric Araujofde92422011-08-19 01:30:26 +0200884 command-line argument following it, the value of ``const`` will be assumed instead.
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300885 See the nargs_ description for examples.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000886
887The ``const`` keyword argument defaults to ``None``.
888
889
890default
891^^^^^^^
892
893All optional arguments and some positional arguments may be omitted at the
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300894command line. The ``default`` keyword argument of
895:meth:`~ArgumentParser.add_argument`, whose value defaults to ``None``,
Éric Araujofde92422011-08-19 01:30:26 +0200896specifies what value should be used if the command-line argument is not present.
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300897For optional arguments, the ``default`` value is used when the option string
898was not present at the command line::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000899
900 >>> parser = argparse.ArgumentParser()
901 >>> parser.add_argument('--foo', default=42)
902 >>> parser.parse_args('--foo 2'.split())
903 Namespace(foo='2')
904 >>> parser.parse_args(''.split())
905 Namespace(foo=42)
906
Barry Warsaw1dedd0a2012-09-25 10:37:58 -0400907If the ``default`` value is a string, the parser parses the value as if it
908were a command-line argument. In particular, the parser applies any type_
909conversion argument, if provided, before setting the attribute on the
910:class:`Namespace` return value. Otherwise, the parser uses the value as is::
911
912 >>> parser = argparse.ArgumentParser()
913 >>> parser.add_argument('--length', default='10', type=int)
914 >>> parser.add_argument('--width', default=10.5, type=int)
915 >>> parser.parse_args()
916 Namespace(length=10, width=10.5)
917
Éric Araujo543edbd2011-08-19 01:45:12 +0200918For positional arguments with nargs_ equal to ``?`` or ``*``, the ``default`` value
Éric Araujofde92422011-08-19 01:30:26 +0200919is used when no command-line argument was present::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000920
921 >>> parser = argparse.ArgumentParser()
922 >>> parser.add_argument('foo', nargs='?', default=42)
923 >>> parser.parse_args('a'.split())
924 Namespace(foo='a')
925 >>> parser.parse_args(''.split())
926 Namespace(foo=42)
927
928
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000929Providing ``default=argparse.SUPPRESS`` causes no attribute to be added if the
930command-line argument was not present.::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000931
932 >>> parser = argparse.ArgumentParser()
933 >>> parser.add_argument('--foo', default=argparse.SUPPRESS)
934 >>> parser.parse_args([])
935 Namespace()
936 >>> parser.parse_args(['--foo', '1'])
937 Namespace(foo='1')
938
939
940type
941^^^^
942
Éric Araujod9d7bca2011-08-10 04:19:03 +0200943By default, :class:`ArgumentParser` objects read command-line arguments in as simple
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300944strings. However, quite often the command-line string should instead be
945interpreted as another type, like a :class:`float` or :class:`int`. The
946``type`` keyword argument of :meth:`~ArgumentParser.add_argument` allows any
Éric Araujod9d7bca2011-08-10 04:19:03 +0200947necessary type-checking and type conversions to be performed. Common built-in
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300948types and functions can be used directly as the value of the ``type`` argument::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000949
950 >>> parser = argparse.ArgumentParser()
951 >>> parser.add_argument('foo', type=int)
Georg Brandl04536b02011-01-09 09:31:01 +0000952 >>> parser.add_argument('bar', type=open)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000953 >>> parser.parse_args('2 temp.txt'.split())
Georg Brandl04536b02011-01-09 09:31:01 +0000954 Namespace(bar=<_io.TextIOWrapper name='temp.txt' encoding='UTF-8'>, foo=2)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000955
Barry Warsaw1dedd0a2012-09-25 10:37:58 -0400956See the section on the default_ keyword argument for information on when the
957``type`` argument is applied to default arguments.
958
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000959To ease the use of various types of files, the argparse module provides the
960factory FileType which takes the ``mode=`` and ``bufsize=`` arguments of the
Georg Brandl04536b02011-01-09 09:31:01 +0000961:func:`open` function. For example, ``FileType('w')`` can be used to create a
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000962writable file::
963
964 >>> parser = argparse.ArgumentParser()
965 >>> parser.add_argument('bar', type=argparse.FileType('w'))
966 >>> parser.parse_args(['out.txt'])
Georg Brandl04536b02011-01-09 09:31:01 +0000967 Namespace(bar=<_io.TextIOWrapper name='out.txt' encoding='UTF-8'>)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000968
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000969``type=`` can take any callable that takes a single string argument and returns
Éric Araujod9d7bca2011-08-10 04:19:03 +0200970the converted value::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000971
972 >>> def perfect_square(string):
973 ... value = int(string)
974 ... sqrt = math.sqrt(value)
975 ... if sqrt != int(sqrt):
976 ... msg = "%r is not a perfect square" % string
977 ... raise argparse.ArgumentTypeError(msg)
978 ... return value
979 ...
980 >>> parser = argparse.ArgumentParser(prog='PROG')
981 >>> parser.add_argument('foo', type=perfect_square)
982 >>> parser.parse_args('9'.split())
983 Namespace(foo=9)
984 >>> parser.parse_args('7'.split())
985 usage: PROG [-h] foo
986 PROG: error: argument foo: '7' is not a perfect square
987
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000988The choices_ keyword argument may be more convenient for type checkers that
989simply check against a range of values::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000990
991 >>> parser = argparse.ArgumentParser(prog='PROG')
Fred Drakec7eb7892011-03-03 05:29:59 +0000992 >>> parser.add_argument('foo', type=int, choices=range(5, 10))
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000993 >>> parser.parse_args('7'.split())
994 Namespace(foo=7)
995 >>> parser.parse_args('11'.split())
996 usage: PROG [-h] {5,6,7,8,9}
997 PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)
998
999See the choices_ section for more details.
1000
1001
1002choices
1003^^^^^^^
1004
Éric Araujod9d7bca2011-08-10 04:19:03 +02001005Some command-line arguments should be selected from a restricted set of values.
Chris Jerdonek174ef672013-01-11 19:26:44 -08001006These can be handled by passing a container object as the *choices* keyword
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001007argument to :meth:`~ArgumentParser.add_argument`. When the command line is
Chris Jerdonek174ef672013-01-11 19:26:44 -08001008parsed, argument values will be checked, and an error message will be displayed
1009if the argument was not one of the acceptable values::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001010
Chris Jerdonek174ef672013-01-11 19:26:44 -08001011 >>> parser = argparse.ArgumentParser(prog='game.py')
1012 >>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])
1013 >>> parser.parse_args(['rock'])
1014 Namespace(move='rock')
1015 >>> parser.parse_args(['fire'])
1016 usage: game.py [-h] {rock,paper,scissors}
1017 game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
1018 'paper', 'scissors')
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001019
Chris Jerdonek174ef672013-01-11 19:26:44 -08001020Note that inclusion in the *choices* container is checked after any type_
1021conversions have been performed, so the type of the objects in the *choices*
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001022container should match the type_ specified::
1023
Chris Jerdonek174ef672013-01-11 19:26:44 -08001024 >>> parser = argparse.ArgumentParser(prog='doors.py')
1025 >>> parser.add_argument('door', type=int, choices=range(1, 4))
1026 >>> print(parser.parse_args(['3']))
1027 Namespace(door=3)
1028 >>> parser.parse_args(['4'])
1029 usage: doors.py [-h] {1,2,3}
1030 doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001031
Chris Jerdonek174ef672013-01-11 19:26:44 -08001032Any object that supports the ``in`` operator can be passed as the *choices*
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001033value, so :class:`dict` objects, :class:`set` objects, custom containers,
1034etc. are all supported.
1035
1036
1037required
1038^^^^^^^^
1039
Ezio Melotti0ee9c1b2011-04-21 16:12:17 +03001040In general, the :mod:`argparse` module assumes that flags like ``-f`` and ``--bar``
Georg Brandl1d827ff2011-04-16 16:44:54 +02001041indicate *optional* arguments, which can always be omitted at the command line.
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001042To make an option *required*, ``True`` can be specified for the ``required=``
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001043keyword argument to :meth:`~ArgumentParser.add_argument`::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001044
1045 >>> parser = argparse.ArgumentParser()
1046 >>> parser.add_argument('--foo', required=True)
1047 >>> parser.parse_args(['--foo', 'BAR'])
1048 Namespace(foo='BAR')
1049 >>> parser.parse_args([])
1050 usage: argparse.py [-h] [--foo FOO]
1051 argparse.py: error: option --foo is required
1052
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001053As the example shows, if an option is marked as ``required``,
1054:meth:`~ArgumentParser.parse_args` will report an error if that option is not
1055present at the command line.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001056
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001057.. note::
1058
1059 Required options are generally considered bad form because users expect
1060 *options* to be *optional*, and thus they should be avoided when possible.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001061
1062
1063help
1064^^^^
1065
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001066The ``help`` value is a string containing a brief description of the argument.
1067When a user requests help (usually by using ``-h`` or ``--help`` at the
Georg Brandl1d827ff2011-04-16 16:44:54 +02001068command line), these ``help`` descriptions will be displayed with each
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001069argument::
1070
1071 >>> parser = argparse.ArgumentParser(prog='frobble')
1072 >>> parser.add_argument('--foo', action='store_true',
1073 ... help='foo the bars before frobbling')
1074 >>> parser.add_argument('bar', nargs='+',
1075 ... help='one of the bars to be frobbled')
1076 >>> parser.parse_args('-h'.split())
1077 usage: frobble [-h] [--foo] bar [bar ...]
1078
1079 positional arguments:
1080 bar one of the bars to be frobbled
1081
1082 optional arguments:
1083 -h, --help show this help message and exit
1084 --foo foo the bars before frobbling
1085
1086The ``help`` strings can include various format specifiers to avoid repetition
1087of things like the program name or the argument default_. The available
1088specifiers include the program name, ``%(prog)s`` and most keyword arguments to
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001089:meth:`~ArgumentParser.add_argument`, e.g. ``%(default)s``, ``%(type)s``, etc.::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001090
1091 >>> parser = argparse.ArgumentParser(prog='frobble')
1092 >>> parser.add_argument('bar', nargs='?', type=int, default=42,
1093 ... help='the bar to %(prog)s (default: %(default)s)')
1094 >>> parser.print_help()
1095 usage: frobble [-h] [bar]
1096
1097 positional arguments:
1098 bar the bar to frobble (default: 42)
1099
1100 optional arguments:
1101 -h, --help show this help message and exit
1102
Senthil Kumaranf21804a2012-06-26 14:17:19 +08001103As the help string supports %-formatting, if you want a literal ``%`` to appear
1104in the help string, you must escape it as ``%%``.
1105
Sandro Tosiea320ab2012-01-03 18:37:03 +01001106:mod:`argparse` supports silencing the help entry for certain options, by
1107setting the ``help`` value to ``argparse.SUPPRESS``::
1108
1109 >>> parser = argparse.ArgumentParser(prog='frobble')
1110 >>> parser.add_argument('--foo', help=argparse.SUPPRESS)
1111 >>> parser.print_help()
1112 usage: frobble [-h]
1113
1114 optional arguments:
1115 -h, --help show this help message and exit
1116
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001117
1118metavar
1119^^^^^^^
1120
Sandro Tosi32587fb2013-01-11 10:49:00 +01001121When :class:`ArgumentParser` generates help messages, it needs some way to refer
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001122to each expected argument. By default, ArgumentParser objects use the dest_
1123value as the "name" of each object. By default, for positional argument
1124actions, the dest_ value is used directly, and for optional argument actions,
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001125the dest_ value is uppercased. So, a single positional argument with
Eli Benderskya7795db2011-11-11 10:57:01 +02001126``dest='bar'`` will be referred to as ``bar``. A single
Éric Araujofde92422011-08-19 01:30:26 +02001127optional argument ``--foo`` that should be followed by a single command-line argument
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001128will be referred to as ``FOO``. An example::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001129
1130 >>> parser = argparse.ArgumentParser()
1131 >>> parser.add_argument('--foo')
1132 >>> parser.add_argument('bar')
1133 >>> parser.parse_args('X --foo Y'.split())
1134 Namespace(bar='X', foo='Y')
1135 >>> parser.print_help()
1136 usage: [-h] [--foo FOO] bar
1137
1138 positional arguments:
1139 bar
1140
1141 optional arguments:
1142 -h, --help show this help message and exit
1143 --foo FOO
1144
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001145An alternative name can be specified with ``metavar``::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001146
1147 >>> parser = argparse.ArgumentParser()
1148 >>> parser.add_argument('--foo', metavar='YYY')
1149 >>> parser.add_argument('bar', metavar='XXX')
1150 >>> parser.parse_args('X --foo Y'.split())
1151 Namespace(bar='X', foo='Y')
1152 >>> parser.print_help()
1153 usage: [-h] [--foo YYY] XXX
1154
1155 positional arguments:
1156 XXX
1157
1158 optional arguments:
1159 -h, --help show this help message and exit
1160 --foo YYY
1161
1162Note that ``metavar`` only changes the *displayed* name - the name of the
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001163attribute on the :meth:`~ArgumentParser.parse_args` object is still determined
1164by the dest_ value.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001165
1166Different values of ``nargs`` may cause the metavar to be used multiple times.
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001167Providing a tuple to ``metavar`` specifies a different display for each of the
1168arguments::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001169
1170 >>> parser = argparse.ArgumentParser(prog='PROG')
1171 >>> parser.add_argument('-x', nargs=2)
1172 >>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))
1173 >>> parser.print_help()
1174 usage: PROG [-h] [-x X X] [--foo bar baz]
1175
1176 optional arguments:
1177 -h, --help show this help message and exit
1178 -x X X
1179 --foo bar baz
1180
1181
1182dest
1183^^^^
1184
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001185Most :class:`ArgumentParser` actions add some value as an attribute of the
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001186object returned by :meth:`~ArgumentParser.parse_args`. The name of this
1187attribute is determined by the ``dest`` keyword argument of
1188:meth:`~ArgumentParser.add_argument`. For positional argument actions,
1189``dest`` is normally supplied as the first argument to
1190:meth:`~ArgumentParser.add_argument`::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001191
1192 >>> parser = argparse.ArgumentParser()
1193 >>> parser.add_argument('bar')
1194 >>> parser.parse_args('XXX'.split())
1195 Namespace(bar='XXX')
1196
1197For optional argument actions, the value of ``dest`` is normally inferred from
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001198the option strings. :class:`ArgumentParser` generates the value of ``dest`` by
Éric Araujo543edbd2011-08-19 01:45:12 +02001199taking the first long option string and stripping away the initial ``--``
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001200string. If no long option strings were supplied, ``dest`` will be derived from
Éric Araujo543edbd2011-08-19 01:45:12 +02001201the first short option string by stripping the initial ``-`` character. Any
1202internal ``-`` characters will be converted to ``_`` characters to make sure
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001203the string is a valid attribute name. The examples below illustrate this
1204behavior::
1205
1206 >>> parser = argparse.ArgumentParser()
1207 >>> parser.add_argument('-f', '--foo-bar', '--foo')
1208 >>> parser.add_argument('-x', '-y')
1209 >>> parser.parse_args('-f 1 -x 2'.split())
1210 Namespace(foo_bar='1', x='2')
1211 >>> parser.parse_args('--foo 1 -y 2'.split())
1212 Namespace(foo_bar='1', x='2')
1213
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001214``dest`` allows a custom attribute name to be provided::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001215
1216 >>> parser = argparse.ArgumentParser()
1217 >>> parser.add_argument('--foo', dest='bar')
1218 >>> parser.parse_args('--foo XXX'.split())
1219 Namespace(bar='XXX')
1220
1221
1222The parse_args() method
1223-----------------------
1224
Georg Brandle0bf91d2010-10-17 10:34:28 +00001225.. method:: ArgumentParser.parse_args(args=None, namespace=None)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001226
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001227 Convert argument strings to objects and assign them as attributes of the
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001228 namespace. Return the populated namespace.
1229
1230 Previous calls to :meth:`add_argument` determine exactly what objects are
1231 created and how they are assigned. See the documentation for
1232 :meth:`add_argument` for details.
1233
Éric Araujofde92422011-08-19 01:30:26 +02001234 By default, the argument strings are taken from :data:`sys.argv`, and a new empty
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001235 :class:`Namespace` object is created for the attributes.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001236
Georg Brandle0bf91d2010-10-17 10:34:28 +00001237
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001238Option value syntax
1239^^^^^^^^^^^^^^^^^^^
1240
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001241The :meth:`~ArgumentParser.parse_args` method supports several ways of
1242specifying the value of an option (if it takes one). In the simplest case, the
1243option and its value are passed as two separate arguments::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001244
1245 >>> parser = argparse.ArgumentParser(prog='PROG')
1246 >>> parser.add_argument('-x')
1247 >>> parser.add_argument('--foo')
1248 >>> parser.parse_args('-x X'.split())
1249 Namespace(foo=None, x='X')
1250 >>> parser.parse_args('--foo FOO'.split())
1251 Namespace(foo='FOO', x=None)
1252
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001253For long options (options with names longer than a single character), the option
Georg Brandl1d827ff2011-04-16 16:44:54 +02001254and value can also be passed as a single command-line argument, using ``=`` to
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001255separate them::
1256
1257 >>> parser.parse_args('--foo=FOO'.split())
1258 Namespace(foo='FOO', x=None)
1259
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001260For short options (options only one character long), the option and its value
1261can be concatenated::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001262
1263 >>> parser.parse_args('-xX'.split())
1264 Namespace(foo=None, x='X')
1265
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001266Several short options can be joined together, using only a single ``-`` prefix,
1267as long as only the last option (or none of them) requires a value::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001268
1269 >>> parser = argparse.ArgumentParser(prog='PROG')
1270 >>> parser.add_argument('-x', action='store_true')
1271 >>> parser.add_argument('-y', action='store_true')
1272 >>> parser.add_argument('-z')
1273 >>> parser.parse_args('-xyzZ'.split())
1274 Namespace(x=True, y=True, z='Z')
1275
1276
1277Invalid arguments
1278^^^^^^^^^^^^^^^^^
1279
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001280While parsing the command line, :meth:`~ArgumentParser.parse_args` checks for a
1281variety of errors, including ambiguous options, invalid types, invalid options,
1282wrong number of positional arguments, etc. When it encounters such an error,
1283it exits and prints the error along with a usage message::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001284
1285 >>> parser = argparse.ArgumentParser(prog='PROG')
1286 >>> parser.add_argument('--foo', type=int)
1287 >>> parser.add_argument('bar', nargs='?')
1288
1289 >>> # invalid type
1290 >>> parser.parse_args(['--foo', 'spam'])
1291 usage: PROG [-h] [--foo FOO] [bar]
1292 PROG: error: argument --foo: invalid int value: 'spam'
1293
1294 >>> # invalid option
1295 >>> parser.parse_args(['--bar'])
1296 usage: PROG [-h] [--foo FOO] [bar]
1297 PROG: error: no such option: --bar
1298
1299 >>> # wrong number of arguments
1300 >>> parser.parse_args(['spam', 'badger'])
1301 usage: PROG [-h] [--foo FOO] [bar]
1302 PROG: error: extra arguments found: badger
1303
1304
Éric Araujo543edbd2011-08-19 01:45:12 +02001305Arguments containing ``-``
1306^^^^^^^^^^^^^^^^^^^^^^^^^^
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001307
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001308The :meth:`~ArgumentParser.parse_args` method attempts to give errors whenever
1309the user has clearly made a mistake, but some situations are inherently
Éric Araujo543edbd2011-08-19 01:45:12 +02001310ambiguous. For example, the command-line argument ``-1`` could either be an
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001311attempt to specify an option or an attempt to provide a positional argument.
1312The :meth:`~ArgumentParser.parse_args` method is cautious here: positional
Éric Araujo543edbd2011-08-19 01:45:12 +02001313arguments may only begin with ``-`` if they look like negative numbers and
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001314there are no options in the parser that look like negative numbers::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001315
1316 >>> parser = argparse.ArgumentParser(prog='PROG')
1317 >>> parser.add_argument('-x')
1318 >>> parser.add_argument('foo', nargs='?')
1319
1320 >>> # no negative number options, so -1 is a positional argument
1321 >>> parser.parse_args(['-x', '-1'])
1322 Namespace(foo=None, x='-1')
1323
1324 >>> # no negative number options, so -1 and -5 are positional arguments
1325 >>> parser.parse_args(['-x', '-1', '-5'])
1326 Namespace(foo='-5', x='-1')
1327
1328 >>> parser = argparse.ArgumentParser(prog='PROG')
1329 >>> parser.add_argument('-1', dest='one')
1330 >>> parser.add_argument('foo', nargs='?')
1331
1332 >>> # negative number options present, so -1 is an option
1333 >>> parser.parse_args(['-1', 'X'])
1334 Namespace(foo=None, one='X')
1335
1336 >>> # negative number options present, so -2 is an option
1337 >>> parser.parse_args(['-2'])
1338 usage: PROG [-h] [-1 ONE] [foo]
1339 PROG: error: no such option: -2
1340
1341 >>> # negative number options present, so both -1s are options
1342 >>> parser.parse_args(['-1', '-1'])
1343 usage: PROG [-h] [-1 ONE] [foo]
1344 PROG: error: argument -1: expected one argument
1345
Éric Araujo543edbd2011-08-19 01:45:12 +02001346If you have positional arguments that must begin with ``-`` and don't look
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001347like negative numbers, you can insert the pseudo-argument ``'--'`` which tells
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001348:meth:`~ArgumentParser.parse_args` that everything after that is a positional
1349argument::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001350
1351 >>> parser.parse_args(['--', '-f'])
1352 Namespace(foo='-f', one=None)
1353
1354
1355Argument abbreviations
1356^^^^^^^^^^^^^^^^^^^^^^
1357
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001358The :meth:`~ArgumentParser.parse_args` method allows long options to be
1359abbreviated if the abbreviation is unambiguous::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001360
1361 >>> parser = argparse.ArgumentParser(prog='PROG')
1362 >>> parser.add_argument('-bacon')
1363 >>> parser.add_argument('-badger')
1364 >>> parser.parse_args('-bac MMM'.split())
1365 Namespace(bacon='MMM', badger=None)
1366 >>> parser.parse_args('-bad WOOD'.split())
1367 Namespace(bacon=None, badger='WOOD')
1368 >>> parser.parse_args('-ba BA'.split())
1369 usage: PROG [-h] [-bacon BACON] [-badger BADGER]
1370 PROG: error: ambiguous option: -ba could match -badger, -bacon
1371
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001372An error is produced for arguments that could produce more than one options.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001373
1374
1375Beyond ``sys.argv``
1376^^^^^^^^^^^^^^^^^^^
1377
Éric Araujod9d7bca2011-08-10 04:19:03 +02001378Sometimes it may be useful to have an ArgumentParser parse arguments other than those
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001379of :data:`sys.argv`. This can be accomplished by passing a list of strings to
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001380:meth:`~ArgumentParser.parse_args`. This is useful for testing at the
1381interactive prompt::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001382
1383 >>> parser = argparse.ArgumentParser()
1384 >>> parser.add_argument(
Fred Drakec7eb7892011-03-03 05:29:59 +00001385 ... 'integers', metavar='int', type=int, choices=range(10),
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001386 ... nargs='+', help='an integer in the range 0..9')
1387 >>> parser.add_argument(
1388 ... '--sum', dest='accumulate', action='store_const', const=sum,
1389 ... default=max, help='sum the integers (default: find the max)')
1390 >>> parser.parse_args(['1', '2', '3', '4'])
1391 Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
1392 >>> parser.parse_args('1 2 3 4 --sum'.split())
1393 Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])
1394
1395
Steven Bethardd8f2d502011-03-26 19:50:06 +01001396The Namespace object
1397^^^^^^^^^^^^^^^^^^^^
1398
Éric Araujo63b18a42011-07-29 17:59:17 +02001399.. class:: Namespace
1400
1401 Simple class used by default by :meth:`~ArgumentParser.parse_args` to create
1402 an object holding attributes and return it.
1403
1404This class is deliberately simple, just an :class:`object` subclass with a
1405readable string representation. If you prefer to have dict-like view of the
1406attributes, you can use the standard Python idiom, :func:`vars`::
Steven Bethardd8f2d502011-03-26 19:50:06 +01001407
1408 >>> parser = argparse.ArgumentParser()
1409 >>> parser.add_argument('--foo')
1410 >>> args = parser.parse_args(['--foo', 'BAR'])
1411 >>> vars(args)
1412 {'foo': 'BAR'}
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001413
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001414It may also be useful to have an :class:`ArgumentParser` assign attributes to an
Steven Bethardd8f2d502011-03-26 19:50:06 +01001415already existing object, rather than a new :class:`Namespace` object. This can
1416be achieved by specifying the ``namespace=`` keyword argument::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001417
Éric Araujo28053fb2010-11-22 03:09:19 +00001418 >>> class C:
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001419 ... pass
1420 ...
1421 >>> c = C()
1422 >>> parser = argparse.ArgumentParser()
1423 >>> parser.add_argument('--foo')
1424 >>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
1425 >>> c.foo
1426 'BAR'
1427
1428
1429Other utilities
1430---------------
1431
1432Sub-commands
1433^^^^^^^^^^^^
1434
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001435.. method:: ArgumentParser.add_subparsers()
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001436
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001437 Many programs split up their functionality into a number of sub-commands,
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001438 for example, the ``svn`` program can invoke sub-commands like ``svn
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001439 checkout``, ``svn update``, and ``svn commit``. Splitting up functionality
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001440 this way can be a particularly good idea when a program performs several
1441 different functions which require different kinds of command-line arguments.
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001442 :class:`ArgumentParser` supports the creation of such sub-commands with the
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001443 :meth:`add_subparsers` method. The :meth:`add_subparsers` method is normally
Ezio Melotti52336f02012-12-28 01:59:24 +02001444 called with no arguments and returns a special action object. This object
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001445 has a single method, :meth:`~ArgumentParser.add_parser`, which takes a
1446 command name and any :class:`ArgumentParser` constructor arguments, and
1447 returns an :class:`ArgumentParser` object that can be modified as usual.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001448
1449 Some example usage::
1450
1451 >>> # create the top-level parser
1452 >>> parser = argparse.ArgumentParser(prog='PROG')
1453 >>> parser.add_argument('--foo', action='store_true', help='foo help')
1454 >>> subparsers = parser.add_subparsers(help='sub-command help')
1455 >>>
1456 >>> # create the parser for the "a" command
1457 >>> parser_a = subparsers.add_parser('a', help='a help')
1458 >>> parser_a.add_argument('bar', type=int, help='bar help')
1459 >>>
1460 >>> # create the parser for the "b" command
1461 >>> parser_b = subparsers.add_parser('b', help='b help')
1462 >>> parser_b.add_argument('--baz', choices='XYZ', help='baz help')
1463 >>>
Éric Araujofde92422011-08-19 01:30:26 +02001464 >>> # parse some argument lists
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001465 >>> parser.parse_args(['a', '12'])
1466 Namespace(bar=12, foo=False)
1467 >>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
1468 Namespace(baz='Z', foo=True)
1469
1470 Note that the object returned by :meth:`parse_args` will only contain
1471 attributes for the main parser and the subparser that was selected by the
1472 command line (and not any other subparsers). So in the example above, when
Éric Araujo543edbd2011-08-19 01:45:12 +02001473 the ``a`` command is specified, only the ``foo`` and ``bar`` attributes are
1474 present, and when the ``b`` command is specified, only the ``foo`` and
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001475 ``baz`` attributes are present.
1476
1477 Similarly, when a help message is requested from a subparser, only the help
1478 for that particular parser will be printed. The help message will not
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001479 include parent parser or sibling parser messages. (A help message for each
1480 subparser command, however, can be given by supplying the ``help=`` argument
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001481 to :meth:`add_parser` as above.)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001482
1483 ::
1484
1485 >>> parser.parse_args(['--help'])
1486 usage: PROG [-h] [--foo] {a,b} ...
1487
1488 positional arguments:
1489 {a,b} sub-command help
Ezio Melotti7128e072013-01-12 10:39:45 +02001490 a a help
1491 b b help
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001492
1493 optional arguments:
1494 -h, --help show this help message and exit
1495 --foo foo help
1496
1497 >>> parser.parse_args(['a', '--help'])
1498 usage: PROG a [-h] bar
1499
1500 positional arguments:
1501 bar bar help
1502
1503 optional arguments:
1504 -h, --help show this help message and exit
1505
1506 >>> parser.parse_args(['b', '--help'])
1507 usage: PROG b [-h] [--baz {X,Y,Z}]
1508
1509 optional arguments:
1510 -h, --help show this help message and exit
1511 --baz {X,Y,Z} baz help
1512
1513 The :meth:`add_subparsers` method also supports ``title`` and ``description``
1514 keyword arguments. When either is present, the subparser's commands will
1515 appear in their own group in the help output. For example::
1516
1517 >>> parser = argparse.ArgumentParser()
1518 >>> subparsers = parser.add_subparsers(title='subcommands',
1519 ... description='valid subcommands',
1520 ... help='additional help')
1521 >>> subparsers.add_parser('foo')
1522 >>> subparsers.add_parser('bar')
1523 >>> parser.parse_args(['-h'])
1524 usage: [-h] {foo,bar} ...
1525
1526 optional arguments:
1527 -h, --help show this help message and exit
1528
1529 subcommands:
1530 valid subcommands
1531
1532 {foo,bar} additional help
1533
Steven Bethardfd311a72010-12-18 11:19:23 +00001534 Furthermore, ``add_parser`` supports an additional ``aliases`` argument,
1535 which allows multiple strings to refer to the same subparser. This example,
1536 like ``svn``, aliases ``co`` as a shorthand for ``checkout``::
1537
1538 >>> parser = argparse.ArgumentParser()
1539 >>> subparsers = parser.add_subparsers()
1540 >>> checkout = subparsers.add_parser('checkout', aliases=['co'])
1541 >>> checkout.add_argument('foo')
1542 >>> parser.parse_args(['co', 'bar'])
1543 Namespace(foo='bar')
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001544
1545 One particularly effective way of handling sub-commands is to combine the use
1546 of the :meth:`add_subparsers` method with calls to :meth:`set_defaults` so
1547 that each subparser knows which Python function it should execute. For
1548 example::
1549
1550 >>> # sub-command functions
1551 >>> def foo(args):
Benjamin Petersonb2deb112010-03-03 02:09:18 +00001552 ... print(args.x * args.y)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001553 ...
1554 >>> def bar(args):
Benjamin Petersonb2deb112010-03-03 02:09:18 +00001555 ... print('((%s))' % args.z)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001556 ...
1557 >>> # create the top-level parser
1558 >>> parser = argparse.ArgumentParser()
1559 >>> subparsers = parser.add_subparsers()
1560 >>>
1561 >>> # create the parser for the "foo" command
1562 >>> parser_foo = subparsers.add_parser('foo')
1563 >>> parser_foo.add_argument('-x', type=int, default=1)
1564 >>> parser_foo.add_argument('y', type=float)
1565 >>> parser_foo.set_defaults(func=foo)
1566 >>>
1567 >>> # create the parser for the "bar" command
1568 >>> parser_bar = subparsers.add_parser('bar')
1569 >>> parser_bar.add_argument('z')
1570 >>> parser_bar.set_defaults(func=bar)
1571 >>>
1572 >>> # parse the args and call whatever function was selected
1573 >>> args = parser.parse_args('foo 1 -x 2'.split())
1574 >>> args.func(args)
1575 2.0
1576 >>>
1577 >>> # parse the args and call whatever function was selected
1578 >>> args = parser.parse_args('bar XYZYX'.split())
1579 >>> args.func(args)
1580 ((XYZYX))
1581
Steven Bethardfd311a72010-12-18 11:19:23 +00001582 This way, you can let :meth:`parse_args` do the job of calling the
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001583 appropriate function after argument parsing is complete. Associating
1584 functions with actions like this is typically the easiest way to handle the
1585 different actions for each of your subparsers. However, if it is necessary
1586 to check the name of the subparser that was invoked, the ``dest`` keyword
1587 argument to the :meth:`add_subparsers` call will work::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001588
1589 >>> parser = argparse.ArgumentParser()
1590 >>> subparsers = parser.add_subparsers(dest='subparser_name')
1591 >>> subparser1 = subparsers.add_parser('1')
1592 >>> subparser1.add_argument('-x')
1593 >>> subparser2 = subparsers.add_parser('2')
1594 >>> subparser2.add_argument('y')
1595 >>> parser.parse_args(['2', 'frobble'])
1596 Namespace(subparser_name='2', y='frobble')
1597
1598
1599FileType objects
1600^^^^^^^^^^^^^^^^
1601
1602.. class:: FileType(mode='r', bufsize=None)
1603
1604 The :class:`FileType` factory creates objects that can be passed to the type
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001605 argument of :meth:`ArgumentParser.add_argument`. Arguments that have
Éric Araujod9d7bca2011-08-10 04:19:03 +02001606 :class:`FileType` objects as their type will open command-line arguments as files
Éric Araujoc3ef0372012-02-20 01:44:55 +01001607 with the requested modes and buffer sizes::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001608
Éric Araujoc3ef0372012-02-20 01:44:55 +01001609 >>> parser = argparse.ArgumentParser()
1610 >>> parser.add_argument('--output', type=argparse.FileType('wb', 0))
1611 >>> parser.parse_args(['--output', 'out'])
1612 Namespace(output=<_io.BufferedWriter name='out'>)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001613
1614 FileType objects understand the pseudo-argument ``'-'`` and automatically
1615 convert this into ``sys.stdin`` for readable :class:`FileType` objects and
Éric Araujoc3ef0372012-02-20 01:44:55 +01001616 ``sys.stdout`` for writable :class:`FileType` objects::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001617
Éric Araujoc3ef0372012-02-20 01:44:55 +01001618 >>> parser = argparse.ArgumentParser()
1619 >>> parser.add_argument('infile', type=argparse.FileType('r'))
1620 >>> parser.parse_args(['-'])
1621 Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001622
1623
1624Argument groups
1625^^^^^^^^^^^^^^^
1626
Georg Brandle0bf91d2010-10-17 10:34:28 +00001627.. method:: ArgumentParser.add_argument_group(title=None, description=None)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001628
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001629 By default, :class:`ArgumentParser` groups command-line arguments into
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001630 "positional arguments" and "optional arguments" when displaying help
1631 messages. When there is a better conceptual grouping of arguments than this
1632 default one, appropriate groups can be created using the
1633 :meth:`add_argument_group` method::
1634
1635 >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
1636 >>> group = parser.add_argument_group('group')
1637 >>> group.add_argument('--foo', help='foo help')
1638 >>> group.add_argument('bar', help='bar help')
1639 >>> parser.print_help()
1640 usage: PROG [--foo FOO] bar
1641
1642 group:
1643 bar bar help
1644 --foo FOO foo help
1645
1646 The :meth:`add_argument_group` method returns an argument group object which
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001647 has an :meth:`~ArgumentParser.add_argument` method just like a regular
1648 :class:`ArgumentParser`. When an argument is added to the group, the parser
1649 treats it just like a normal argument, but displays the argument in a
1650 separate group for help messages. The :meth:`add_argument_group` method
Georg Brandle0bf91d2010-10-17 10:34:28 +00001651 accepts *title* and *description* arguments which can be used to
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001652 customize this display::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001653
1654 >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
1655 >>> group1 = parser.add_argument_group('group1', 'group1 description')
1656 >>> group1.add_argument('foo', help='foo help')
1657 >>> group2 = parser.add_argument_group('group2', 'group2 description')
1658 >>> group2.add_argument('--bar', help='bar help')
1659 >>> parser.print_help()
1660 usage: PROG [--bar BAR] foo
1661
1662 group1:
1663 group1 description
1664
1665 foo foo help
1666
1667 group2:
1668 group2 description
1669
1670 --bar BAR bar help
1671
Sandro Tosi99e7d072012-03-26 19:36:23 +02001672 Note that any arguments not in your user-defined groups will end up back
1673 in the usual "positional arguments" and "optional arguments" sections.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001674
1675
1676Mutual exclusion
1677^^^^^^^^^^^^^^^^
1678
Georg Brandle0bf91d2010-10-17 10:34:28 +00001679.. method:: add_mutually_exclusive_group(required=False)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001680
Ezio Melotti0ee9c1b2011-04-21 16:12:17 +03001681 Create a mutually exclusive group. :mod:`argparse` will make sure that only
1682 one of the arguments in the mutually exclusive group was present on the
1683 command line::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001684
1685 >>> parser = argparse.ArgumentParser(prog='PROG')
1686 >>> group = parser.add_mutually_exclusive_group()
1687 >>> group.add_argument('--foo', action='store_true')
1688 >>> group.add_argument('--bar', action='store_false')
1689 >>> parser.parse_args(['--foo'])
1690 Namespace(bar=True, foo=True)
1691 >>> parser.parse_args(['--bar'])
1692 Namespace(bar=False, foo=False)
1693 >>> parser.parse_args(['--foo', '--bar'])
1694 usage: PROG [-h] [--foo | --bar]
1695 PROG: error: argument --bar: not allowed with argument --foo
1696
Georg Brandle0bf91d2010-10-17 10:34:28 +00001697 The :meth:`add_mutually_exclusive_group` method also accepts a *required*
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001698 argument, to indicate that at least one of the mutually exclusive arguments
1699 is required::
1700
1701 >>> parser = argparse.ArgumentParser(prog='PROG')
1702 >>> group = parser.add_mutually_exclusive_group(required=True)
1703 >>> group.add_argument('--foo', action='store_true')
1704 >>> group.add_argument('--bar', action='store_false')
1705 >>> parser.parse_args([])
1706 usage: PROG [-h] (--foo | --bar)
1707 PROG: error: one of the arguments --foo --bar is required
1708
1709 Note that currently mutually exclusive argument groups do not support the
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001710 *title* and *description* arguments of
1711 :meth:`~ArgumentParser.add_argument_group`.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001712
1713
1714Parser defaults
1715^^^^^^^^^^^^^^^
1716
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001717.. method:: ArgumentParser.set_defaults(**kwargs)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001718
1719 Most of the time, the attributes of the object returned by :meth:`parse_args`
Éric Araujod9d7bca2011-08-10 04:19:03 +02001720 will be fully determined by inspecting the command-line arguments and the argument
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001721 actions. :meth:`set_defaults` allows some additional
Georg Brandl1d827ff2011-04-16 16:44:54 +02001722 attributes that are determined without any inspection of the command line to
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001723 be added::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001724
1725 >>> parser = argparse.ArgumentParser()
1726 >>> parser.add_argument('foo', type=int)
1727 >>> parser.set_defaults(bar=42, baz='badger')
1728 >>> parser.parse_args(['736'])
1729 Namespace(bar=42, baz='badger', foo=736)
1730
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001731 Note that parser-level defaults always override argument-level defaults::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001732
1733 >>> parser = argparse.ArgumentParser()
1734 >>> parser.add_argument('--foo', default='bar')
1735 >>> parser.set_defaults(foo='spam')
1736 >>> parser.parse_args([])
1737 Namespace(foo='spam')
1738
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001739 Parser-level defaults can be particularly useful when working with multiple
1740 parsers. See the :meth:`~ArgumentParser.add_subparsers` method for an
1741 example of this type.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001742
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001743.. method:: ArgumentParser.get_default(dest)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001744
1745 Get the default value for a namespace attribute, as set by either
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001746 :meth:`~ArgumentParser.add_argument` or by
1747 :meth:`~ArgumentParser.set_defaults`::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001748
1749 >>> parser = argparse.ArgumentParser()
1750 >>> parser.add_argument('--foo', default='badger')
1751 >>> parser.get_default('foo')
1752 'badger'
1753
1754
1755Printing help
1756^^^^^^^^^^^^^
1757
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001758In most typical applications, :meth:`~ArgumentParser.parse_args` will take
1759care of formatting and printing any usage or error messages. However, several
1760formatting methods are available:
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001761
Georg Brandle0bf91d2010-10-17 10:34:28 +00001762.. method:: ArgumentParser.print_usage(file=None)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001763
1764 Print a brief description of how the :class:`ArgumentParser` should be
R. David Murray32e17712010-12-18 16:39:06 +00001765 invoked on the command line. If *file* is ``None``, :data:`sys.stdout` is
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001766 assumed.
1767
Georg Brandle0bf91d2010-10-17 10:34:28 +00001768.. method:: ArgumentParser.print_help(file=None)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001769
1770 Print a help message, including the program usage and information about the
Georg Brandle0bf91d2010-10-17 10:34:28 +00001771 arguments registered with the :class:`ArgumentParser`. If *file* is
R. David Murray32e17712010-12-18 16:39:06 +00001772 ``None``, :data:`sys.stdout` is assumed.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001773
1774There are also variants of these methods that simply return a string instead of
1775printing it:
1776
Georg Brandle0bf91d2010-10-17 10:34:28 +00001777.. method:: ArgumentParser.format_usage()
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001778
1779 Return a string containing a brief description of how the
1780 :class:`ArgumentParser` should be invoked on the command line.
1781
Georg Brandle0bf91d2010-10-17 10:34:28 +00001782.. method:: ArgumentParser.format_help()
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001783
1784 Return a string containing a help message, including the program usage and
1785 information about the arguments registered with the :class:`ArgumentParser`.
1786
1787
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001788Partial parsing
1789^^^^^^^^^^^^^^^
1790
Georg Brandle0bf91d2010-10-17 10:34:28 +00001791.. method:: ArgumentParser.parse_known_args(args=None, namespace=None)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001792
Georg Brandl1d827ff2011-04-16 16:44:54 +02001793Sometimes a script may only parse a few of the command-line arguments, passing
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001794the remaining arguments on to another script or program. In these cases, the
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001795:meth:`~ArgumentParser.parse_known_args` method can be useful. It works much like
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001796:meth:`~ArgumentParser.parse_args` except that it does not produce an error when
1797extra arguments are present. Instead, it returns a two item tuple containing
1798the populated namespace and the list of remaining argument strings.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001799
1800::
1801
1802 >>> parser = argparse.ArgumentParser()
1803 >>> parser.add_argument('--foo', action='store_true')
1804 >>> parser.add_argument('bar')
1805 >>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
1806 (Namespace(bar='BAR', foo=True), ['--badger', 'spam'])
1807
1808
1809Customizing file parsing
1810^^^^^^^^^^^^^^^^^^^^^^^^
1811
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001812.. method:: ArgumentParser.convert_arg_line_to_args(arg_line)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001813
Georg Brandle0bf91d2010-10-17 10:34:28 +00001814 Arguments that are read from a file (see the *fromfile_prefix_chars*
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001815 keyword argument to the :class:`ArgumentParser` constructor) are read one
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001816 argument per line. :meth:`convert_arg_line_to_args` can be overriden for
1817 fancier reading.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001818
Georg Brandle0bf91d2010-10-17 10:34:28 +00001819 This method takes a single argument *arg_line* which is a string read from
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001820 the argument file. It returns a list of arguments parsed from this string.
1821 The method is called once per line read from the argument file, in order.
1822
1823 A useful override of this method is one that treats each space-separated word
1824 as an argument::
1825
1826 def convert_arg_line_to_args(self, arg_line):
1827 for arg in arg_line.split():
1828 if not arg.strip():
1829 continue
1830 yield arg
1831
1832
Georg Brandl93754922010-10-17 10:28:04 +00001833Exiting methods
1834^^^^^^^^^^^^^^^
1835
1836.. method:: ArgumentParser.exit(status=0, message=None)
1837
1838 This method terminates the program, exiting with the specified *status*
1839 and, if given, it prints a *message* before that.
1840
1841.. method:: ArgumentParser.error(message)
1842
1843 This method prints a usage message including the *message* to the
Senthil Kumaran86a1a892011-08-03 07:42:18 +08001844 standard error and terminates the program with a status code of 2.
Georg Brandl93754922010-10-17 10:28:04 +00001845
Raymond Hettinger677e10a2010-12-07 06:45:30 +00001846.. _upgrading-optparse-code:
Georg Brandl93754922010-10-17 10:28:04 +00001847
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001848Upgrading optparse code
1849-----------------------
1850
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001851Originally, the :mod:`argparse` module had attempted to maintain compatibility
Ezio Melotti0ee9c1b2011-04-21 16:12:17 +03001852with :mod:`optparse`. However, :mod:`optparse` was difficult to extend
1853transparently, particularly with the changes required to support the new
1854``nargs=`` specifiers and better usage messages. When most everything in
1855:mod:`optparse` had either been copy-pasted over or monkey-patched, it no
1856longer seemed practical to try to maintain the backwards compatibility.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001857
Ezio Melotti0ee9c1b2011-04-21 16:12:17 +03001858A partial upgrade path from :mod:`optparse` to :mod:`argparse`:
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001859
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001860* Replace all :meth:`optparse.OptionParser.add_option` calls with
1861 :meth:`ArgumentParser.add_argument` calls.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001862
R David Murray5e0c5712012-03-30 18:07:42 -04001863* Replace ``(options, args) = parser.parse_args()`` with ``args =
Georg Brandlc9007082011-01-09 09:04:08 +00001864 parser.parse_args()`` and add additional :meth:`ArgumentParser.add_argument`
R David Murray5e0c5712012-03-30 18:07:42 -04001865 calls for the positional arguments. Keep in mind that what was previously
1866 called ``options``, now in :mod:`argparse` context is called ``args``.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001867
1868* Replace callback actions and the ``callback_*`` keyword arguments with
1869 ``type`` or ``action`` arguments.
1870
1871* Replace string names for ``type`` keyword arguments with the corresponding
1872 type objects (e.g. int, float, complex, etc).
1873
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001874* Replace :class:`optparse.Values` with :class:`Namespace` and
1875 :exc:`optparse.OptionError` and :exc:`optparse.OptionValueError` with
1876 :exc:`ArgumentError`.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001877
1878* Replace strings with implicit arguments such as ``%default`` or ``%prog`` with
Ezio Melotticca4ef82011-04-21 15:26:46 +03001879 the standard Python syntax to use dictionaries to format strings, that is,
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001880 ``%(default)s`` and ``%(prog)s``.
Steven Bethard59710962010-05-24 03:21:08 +00001881
1882* Replace the OptionParser constructor ``version`` argument with a call to
1883 ``parser.add_argument('--version', action='version', version='<the version>')``