blob: d64f8a28759c3d4a7d2d9e3bcde2e2a4ea327898 [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
Georg Brandlc9007082011-01-09 09:04:08 +0000133.. class:: ArgumentParser([description], [epilog], [prog], [usage], [add_help], \
134 [argument_default], [parents], [prefix_chars], \
135 [conflict_handler], [formatter_class])
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000136
137 Create a new :class:`ArgumentParser` object. Each parameter has its own more
138 detailed description below, but in short they are:
139
140 * description_ - Text to display before the argument help.
141
142 * epilog_ - Text to display after the argument help.
143
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000144 * add_help_ - Add a -h/--help option to the parser. (default: ``True``)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000145
146 * argument_default_ - Set the global default value for arguments.
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000147 (default: ``None``)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000148
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000149 * parents_ - A list of :class:`ArgumentParser` objects whose arguments should
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000150 also be included.
151
152 * prefix_chars_ - The set of characters that prefix optional arguments.
153 (default: '-')
154
155 * fromfile_prefix_chars_ - The set of characters that prefix files from
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000156 which additional arguments should be read. (default: ``None``)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000157
158 * formatter_class_ - A class for customizing the help output.
159
160 * conflict_handler_ - Usually unnecessary, defines strategy for resolving
161 conflicting optionals.
162
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000163 * prog_ - The name of the program (default:
Éric Araujo37b5f9e2011-09-01 03:19:30 +0200164 ``sys.argv[0]``)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000165
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000166 * usage_ - The string describing the program usage (default: generated)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000167
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000168The following sections describe how each of these are used.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000169
170
171description
172^^^^^^^^^^^
173
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000174Most calls to the :class:`ArgumentParser` constructor will use the
175``description=`` keyword argument. This argument gives a brief description of
176what the program does and how it works. In help messages, the description is
177displayed between the command-line usage string and the help messages for the
178various arguments::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000179
180 >>> parser = argparse.ArgumentParser(description='A foo that bars')
181 >>> parser.print_help()
182 usage: argparse.py [-h]
183
184 A foo that bars
185
186 optional arguments:
187 -h, --help show this help message and exit
188
189By default, the description will be line-wrapped so that it fits within the
190given space. To change this behavior, see the formatter_class_ argument.
191
192
193epilog
194^^^^^^
195
196Some programs like to display additional description of the program after the
197description of the arguments. Such text can be specified using the ``epilog=``
198argument to :class:`ArgumentParser`::
199
200 >>> parser = argparse.ArgumentParser(
201 ... description='A foo that bars',
202 ... epilog="And that's how you'd foo a bar")
203 >>> parser.print_help()
204 usage: argparse.py [-h]
205
206 A foo that bars
207
208 optional arguments:
209 -h, --help show this help message and exit
210
211 And that's how you'd foo a bar
212
213As with the description_ argument, the ``epilog=`` text is by default
214line-wrapped, but this behavior can be adjusted with the formatter_class_
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000215argument to :class:`ArgumentParser`.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000216
217
218add_help
219^^^^^^^^
220
R. David Murray88c49fe2010-08-03 17:56:09 +0000221By default, ArgumentParser objects add an option which simply displays
222the parser's help message. For example, consider a file named
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000223``myprogram.py`` containing the following code::
224
225 import argparse
226 parser = argparse.ArgumentParser()
227 parser.add_argument('--foo', help='foo help')
228 args = parser.parse_args()
229
Georg Brandl1d827ff2011-04-16 16:44:54 +0200230If ``-h`` or ``--help`` is supplied at the command line, the ArgumentParser
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000231help will be printed::
232
233 $ python myprogram.py --help
234 usage: myprogram.py [-h] [--foo FOO]
235
236 optional arguments:
237 -h, --help show this help message and exit
238 --foo FOO foo help
239
240Occasionally, it may be useful to disable the addition of this help option.
241This can be achieved by passing ``False`` as the ``add_help=`` argument to
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000242:class:`ArgumentParser`::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000243
244 >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
245 >>> parser.add_argument('--foo', help='foo help')
246 >>> parser.print_help()
247 usage: PROG [--foo FOO]
248
249 optional arguments:
250 --foo FOO foo help
251
R. David Murray88c49fe2010-08-03 17:56:09 +0000252The help option is typically ``-h/--help``. The exception to this is
Éric Araujo543edbd2011-08-19 01:45:12 +0200253if the ``prefix_chars=`` is specified and does not include ``-``, in
R. David Murray88c49fe2010-08-03 17:56:09 +0000254which case ``-h`` and ``--help`` are not valid options. In
255this case, the first character in ``prefix_chars`` is used to prefix
256the help options::
257
258 >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
259 >>> parser.print_help()
260 usage: PROG [+h]
261
262 optional arguments:
263 +h, ++help show this help message and exit
264
265
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000266prefix_chars
267^^^^^^^^^^^^
268
Éric Araujo543edbd2011-08-19 01:45:12 +0200269Most command-line options will use ``-`` as the prefix, e.g. ``-f/--foo``.
R. David Murray88c49fe2010-08-03 17:56:09 +0000270Parsers that need to support different or additional prefix
271characters, e.g. for options
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000272like ``+f`` or ``/foo``, may specify them using the ``prefix_chars=`` argument
273to the ArgumentParser constructor::
274
275 >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
276 >>> parser.add_argument('+f')
277 >>> parser.add_argument('++bar')
278 >>> parser.parse_args('+f X ++bar Y'.split())
279 Namespace(bar='Y', f='X')
280
281The ``prefix_chars=`` argument defaults to ``'-'``. Supplying a set of
Éric Araujo543edbd2011-08-19 01:45:12 +0200282characters that does not include ``-`` will cause ``-f/--foo`` options to be
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000283disallowed.
284
285
286fromfile_prefix_chars
287^^^^^^^^^^^^^^^^^^^^^
288
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000289Sometimes, for example when dealing with a particularly long argument lists, it
290may make sense to keep the list of arguments in a file rather than typing it out
291at the command line. If the ``fromfile_prefix_chars=`` argument is given to the
292:class:`ArgumentParser` constructor, then arguments that start with any of the
293specified characters will be treated as files, and will be replaced by the
294arguments they contain. For example::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000295
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000296 >>> with open('args.txt', 'w') as fp:
297 ... fp.write('-f\nbar')
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000298 >>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
299 >>> parser.add_argument('-f')
300 >>> parser.parse_args(['-f', 'foo', '@args.txt'])
301 Namespace(f='bar')
302
303Arguments read from a file must by default be one per line (but see also
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300304:meth:`~ArgumentParser.convert_arg_line_to_args`) and are treated as if they
305were in the same place as the original file referencing argument on the command
306line. So in the example above, the expression ``['-f', 'foo', '@args.txt']``
307is considered equivalent to the expression ``['-f', 'foo', '-f', 'bar']``.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000308
309The ``fromfile_prefix_chars=`` argument defaults to ``None``, meaning that
310arguments will never be treated as file references.
311
Georg Brandle0bf91d2010-10-17 10:34:28 +0000312
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000313argument_default
314^^^^^^^^^^^^^^^^
315
316Generally, argument defaults are specified either by passing a default to
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300317:meth:`~ArgumentParser.add_argument` or by calling the
318:meth:`~ArgumentParser.set_defaults` methods with a specific set of name-value
319pairs. Sometimes however, it may be useful to specify a single parser-wide
320default for arguments. This can be accomplished by passing the
321``argument_default=`` keyword argument to :class:`ArgumentParser`. For example,
322to globally suppress attribute creation on :meth:`~ArgumentParser.parse_args`
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000323calls, we supply ``argument_default=SUPPRESS``::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000324
325 >>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
326 >>> parser.add_argument('--foo')
327 >>> parser.add_argument('bar', nargs='?')
328 >>> parser.parse_args(['--foo', '1', 'BAR'])
329 Namespace(bar='BAR', foo='1')
330 >>> parser.parse_args([])
331 Namespace()
332
333
334parents
335^^^^^^^
336
337Sometimes, several parsers share a common set of arguments. Rather than
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000338repeating the definitions of these arguments, a single parser with all the
339shared arguments and passed to ``parents=`` argument to :class:`ArgumentParser`
340can be used. The ``parents=`` argument takes a list of :class:`ArgumentParser`
341objects, collects all the positional and optional actions from them, and adds
342these actions to the :class:`ArgumentParser` object being constructed::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000343
344 >>> parent_parser = argparse.ArgumentParser(add_help=False)
345 >>> parent_parser.add_argument('--parent', type=int)
346
347 >>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
348 >>> foo_parser.add_argument('foo')
349 >>> foo_parser.parse_args(['--parent', '2', 'XXX'])
350 Namespace(foo='XXX', parent=2)
351
352 >>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
353 >>> bar_parser.add_argument('--bar')
354 >>> bar_parser.parse_args(['--bar', 'YYY'])
355 Namespace(bar='YYY', parent=None)
356
357Note that most parent parsers will specify ``add_help=False``. Otherwise, the
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000358:class:`ArgumentParser` will see two ``-h/--help`` options (one in the parent
359and one in the child) and raise an error.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000360
Steven Bethardd186f992011-03-26 21:49:00 +0100361.. note::
362 You must fully initialize the parsers before passing them via ``parents=``.
363 If you change the parent parsers after the child parser, those changes will
364 not be reflected in the child.
365
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000366
367formatter_class
368^^^^^^^^^^^^^^^
369
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000370:class:`ArgumentParser` objects allow the help formatting to be customized by
371specifying an alternate formatting class. Currently, there are three such
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300372classes:
373
374.. class:: RawDescriptionHelpFormatter
375 RawTextHelpFormatter
376 ArgumentDefaultsHelpFormatter
377
378The first two allow more control over how textual descriptions are displayed,
379while the last automatically adds information about argument default values.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000380
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000381By default, :class:`ArgumentParser` objects line-wrap the description_ and
382epilog_ texts in command-line help messages::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000383
384 >>> parser = argparse.ArgumentParser(
385 ... prog='PROG',
386 ... description='''this description
387 ... was indented weird
388 ... but that is okay''',
389 ... epilog='''
390 ... likewise for this epilog whose whitespace will
391 ... be cleaned up and whose words will be wrapped
392 ... across a couple lines''')
393 >>> parser.print_help()
394 usage: PROG [-h]
395
396 this description was indented weird but that is okay
397
398 optional arguments:
399 -h, --help show this help message and exit
400
401 likewise for this epilog whose whitespace will be cleaned up and whose words
402 will be wrapped across a couple lines
403
Éric Araujo543edbd2011-08-19 01:45:12 +0200404Passing :class:`RawDescriptionHelpFormatter` as ``formatter_class=``
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000405indicates that description_ and epilog_ are already correctly formatted and
406should not be line-wrapped::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000407
408 >>> parser = argparse.ArgumentParser(
409 ... prog='PROG',
410 ... formatter_class=argparse.RawDescriptionHelpFormatter,
411 ... description=textwrap.dedent('''\
412 ... Please do not mess up this text!
413 ... --------------------------------
414 ... I have indented it
415 ... exactly the way
416 ... I want it
417 ... '''))
418 >>> parser.print_help()
419 usage: PROG [-h]
420
421 Please do not mess up this text!
422 --------------------------------
423 I have indented it
424 exactly the way
425 I want it
426
427 optional arguments:
428 -h, --help show this help message and exit
429
Éric Araujo543edbd2011-08-19 01:45:12 +0200430:class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text,
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000431including argument descriptions.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000432
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000433The other formatter class available, :class:`ArgumentDefaultsHelpFormatter`,
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000434will add information about the default value of each of the arguments::
435
436 >>> parser = argparse.ArgumentParser(
437 ... prog='PROG',
438 ... formatter_class=argparse.ArgumentDefaultsHelpFormatter)
439 >>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
440 >>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
441 >>> parser.print_help()
442 usage: PROG [-h] [--foo FOO] [bar [bar ...]]
443
444 positional arguments:
445 bar BAR! (default: [1, 2, 3])
446
447 optional arguments:
448 -h, --help show this help message and exit
449 --foo FOO FOO! (default: 42)
450
451
452conflict_handler
453^^^^^^^^^^^^^^^^
454
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000455:class:`ArgumentParser` objects do not allow two actions with the same option
456string. By default, :class:`ArgumentParser` objects raises an exception if an
457attempt is made to create an argument with an option string that is already in
458use::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000459
460 >>> parser = argparse.ArgumentParser(prog='PROG')
461 >>> parser.add_argument('-f', '--foo', help='old foo help')
462 >>> parser.add_argument('--foo', help='new foo help')
463 Traceback (most recent call last):
464 ..
465 ArgumentError: argument --foo: conflicting option string(s): --foo
466
467Sometimes (e.g. when using parents_) it may be useful to simply override any
468older arguments with the same option string. To get this behavior, the value
469``'resolve'`` can be supplied to the ``conflict_handler=`` argument of
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000470:class:`ArgumentParser`::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000471
472 >>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
473 >>> parser.add_argument('-f', '--foo', help='old foo help')
474 >>> parser.add_argument('--foo', help='new foo help')
475 >>> parser.print_help()
476 usage: PROG [-h] [-f FOO] [--foo FOO]
477
478 optional arguments:
479 -h, --help show this help message and exit
480 -f FOO old foo help
481 --foo FOO new foo help
482
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000483Note that :class:`ArgumentParser` objects only remove an action if all of its
484option strings are overridden. So, in the example above, the old ``-f/--foo``
485action is retained as the ``-f`` action, because only the ``--foo`` option
486string was overridden.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000487
488
489prog
490^^^^
491
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000492By default, :class:`ArgumentParser` objects uses ``sys.argv[0]`` to determine
493how to display the name of the program in help messages. This default is almost
Ezio Melottif82340d2010-05-27 22:38:16 +0000494always desirable because it will make the help messages match how the program was
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000495invoked on the command line. For example, consider a file named
496``myprogram.py`` with the following code::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000497
498 import argparse
499 parser = argparse.ArgumentParser()
500 parser.add_argument('--foo', help='foo help')
501 args = parser.parse_args()
502
503The help for this program will display ``myprogram.py`` as the program name
504(regardless of where the program was invoked from)::
505
506 $ python myprogram.py --help
507 usage: myprogram.py [-h] [--foo FOO]
508
509 optional arguments:
510 -h, --help show this help message and exit
511 --foo FOO foo help
512 $ cd ..
513 $ python subdir\myprogram.py --help
514 usage: myprogram.py [-h] [--foo FOO]
515
516 optional arguments:
517 -h, --help show this help message and exit
518 --foo FOO foo help
519
520To change this default behavior, another value can be supplied using the
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000521``prog=`` argument to :class:`ArgumentParser`::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000522
523 >>> parser = argparse.ArgumentParser(prog='myprogram')
524 >>> parser.print_help()
525 usage: myprogram [-h]
526
527 optional arguments:
528 -h, --help show this help message and exit
529
530Note that the program name, whether determined from ``sys.argv[0]`` or from the
531``prog=`` argument, is available to help messages using the ``%(prog)s`` format
532specifier.
533
534::
535
536 >>> parser = argparse.ArgumentParser(prog='myprogram')
537 >>> parser.add_argument('--foo', help='foo of the %(prog)s program')
538 >>> parser.print_help()
539 usage: myprogram [-h] [--foo FOO]
540
541 optional arguments:
542 -h, --help show this help message and exit
543 --foo FOO foo of the myprogram program
544
545
546usage
547^^^^^
548
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000549By default, :class:`ArgumentParser` calculates the usage message from the
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000550arguments it contains::
551
552 >>> parser = argparse.ArgumentParser(prog='PROG')
553 >>> parser.add_argument('--foo', nargs='?', help='foo help')
554 >>> parser.add_argument('bar', nargs='+', help='bar help')
555 >>> parser.print_help()
556 usage: PROG [-h] [--foo [FOO]] bar [bar ...]
557
558 positional arguments:
559 bar bar help
560
561 optional arguments:
562 -h, --help show this help message and exit
563 --foo [FOO] foo help
564
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000565The default message can be overridden with the ``usage=`` keyword argument::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000566
567 >>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
568 >>> parser.add_argument('--foo', nargs='?', help='foo help')
569 >>> parser.add_argument('bar', nargs='+', help='bar help')
570 >>> parser.print_help()
571 usage: PROG [options]
572
573 positional arguments:
574 bar bar help
575
576 optional arguments:
577 -h, --help show this help message and exit
578 --foo [FOO] foo help
579
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000580The ``%(prog)s`` format specifier is available to fill in the program name in
581your usage messages.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000582
583
584The add_argument() method
585-------------------------
586
Georg Brandlc9007082011-01-09 09:04:08 +0000587.. method:: ArgumentParser.add_argument(name or flags..., [action], [nargs], \
588 [const], [default], [type], [choices], [required], \
589 [help], [metavar], [dest])
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000590
Georg Brandl1d827ff2011-04-16 16:44:54 +0200591 Define how a single command-line argument should be parsed. Each parameter
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000592 has its own more detailed description below, but in short they are:
593
594 * `name or flags`_ - Either a name or a list of option strings, e.g. ``foo``
Ezio Melottidca309d2011-04-21 23:09:27 +0300595 or ``-f, --foo``.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000596
597 * action_ - The basic type of action to be taken when this argument is
Georg Brandl1d827ff2011-04-16 16:44:54 +0200598 encountered at the command line.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000599
600 * nargs_ - The number of command-line arguments that should be consumed.
601
602 * const_ - A constant value required by some action_ and nargs_ selections.
603
604 * default_ - The value produced if the argument is absent from the
Georg Brandl1d827ff2011-04-16 16:44:54 +0200605 command line.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000606
Ezio Melotti2409d772011-04-16 23:13:50 +0300607 * type_ - The type to which the command-line argument should be converted.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000608
609 * choices_ - A container of the allowable values for the argument.
610
611 * required_ - Whether or not the command-line option may be omitted
612 (optionals only).
613
614 * help_ - A brief description of what the argument does.
615
616 * metavar_ - A name for the argument in usage messages.
617
618 * dest_ - The name of the attribute to be added to the object returned by
619 :meth:`parse_args`.
620
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000621The following sections describe how each of these are used.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000622
Georg Brandle0bf91d2010-10-17 10:34:28 +0000623
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000624name or flags
625^^^^^^^^^^^^^
626
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300627The :meth:`~ArgumentParser.add_argument` method must know whether an optional
628argument, like ``-f`` or ``--foo``, or a positional argument, like a list of
629filenames, is expected. The first arguments passed to
630:meth:`~ArgumentParser.add_argument` must therefore be either a series of
631flags, or a simple argument name. For example, an optional argument could
632be created like::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000633
634 >>> parser.add_argument('-f', '--foo')
635
636while a positional argument could be created like::
637
638 >>> parser.add_argument('bar')
639
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300640When :meth:`~ArgumentParser.parse_args` is called, optional arguments will be
641identified by the ``-`` prefix, and the remaining arguments will be assumed to
642be positional::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000643
644 >>> parser = argparse.ArgumentParser(prog='PROG')
645 >>> parser.add_argument('-f', '--foo')
646 >>> parser.add_argument('bar')
647 >>> parser.parse_args(['BAR'])
648 Namespace(bar='BAR', foo=None)
649 >>> parser.parse_args(['BAR', '--foo', 'FOO'])
650 Namespace(bar='BAR', foo='FOO')
651 >>> parser.parse_args(['--foo', 'FOO'])
652 usage: PROG [-h] [-f FOO] bar
653 PROG: error: too few arguments
654
Georg Brandle0bf91d2010-10-17 10:34:28 +0000655
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000656action
657^^^^^^
658
Éric Araujod9d7bca2011-08-10 04:19:03 +0200659:class:`ArgumentParser` objects associate command-line arguments with actions. These
660actions can do just about anything with the command-line arguments associated with
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000661them, though most actions simply add an attribute to the object returned by
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300662:meth:`~ArgumentParser.parse_args`. The ``action`` keyword argument specifies
Éric Araujod9d7bca2011-08-10 04:19:03 +0200663how the command-line arguments should be handled. The supported actions are:
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000664
665* ``'store'`` - This just stores the argument's value. This is the default
Ezio Melotti2f1db7d2011-04-21 23:06:48 +0300666 action. For example::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000667
668 >>> parser = argparse.ArgumentParser()
669 >>> parser.add_argument('--foo')
670 >>> parser.parse_args('--foo 1'.split())
671 Namespace(foo='1')
672
673* ``'store_const'`` - This stores the value specified by the const_ keyword
Ezio Melotti2f1db7d2011-04-21 23:06:48 +0300674 argument. (Note that the const_ keyword argument defaults to the rather
675 unhelpful ``None``.) The ``'store_const'`` action is most commonly used with
676 optional arguments that specify some sort of flag. For example::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000677
678 >>> parser = argparse.ArgumentParser()
679 >>> parser.add_argument('--foo', action='store_const', const=42)
680 >>> parser.parse_args('--foo'.split())
681 Namespace(foo=42)
682
683* ``'store_true'`` and ``'store_false'`` - These store the values ``True`` and
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000684 ``False`` respectively. These are special cases of ``'store_const'``. For
685 example::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000686
687 >>> parser = argparse.ArgumentParser()
688 >>> parser.add_argument('--foo', action='store_true')
689 >>> parser.add_argument('--bar', action='store_false')
690 >>> parser.parse_args('--foo --bar'.split())
691 Namespace(bar=False, foo=True)
692
693* ``'append'`` - This stores a list, and appends each argument value to the
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000694 list. This is useful to allow an option to be specified multiple times.
695 Example usage::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000696
697 >>> parser = argparse.ArgumentParser()
698 >>> parser.add_argument('--foo', action='append')
699 >>> parser.parse_args('--foo 1 --foo 2'.split())
700 Namespace(foo=['1', '2'])
701
702* ``'append_const'`` - This stores a list, and appends the value specified by
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000703 the const_ keyword argument to the list. (Note that the const_ keyword
704 argument defaults to ``None``.) The ``'append_const'`` action is typically
705 useful when multiple arguments need to store constants to the same list. For
706 example::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000707
708 >>> parser = argparse.ArgumentParser()
709 >>> parser.add_argument('--str', dest='types', action='append_const', const=str)
710 >>> parser.add_argument('--int', dest='types', action='append_const', const=int)
711 >>> parser.parse_args('--str --int'.split())
Florent Xicluna74e64952011-10-28 11:21:19 +0200712 Namespace(types=[<class 'str'>, <class 'int'>])
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000713
Sandro Tosi98492a52012-01-04 23:25:04 +0100714* ``'count'`` - This counts the number of times a keyword argument occurs. For
715 example, this is useful for increasing verbosity levels::
716
717 >>> parser = argparse.ArgumentParser()
718 >>> parser.add_argument('--verbose', '-v', action='count')
719 >>> parser.parse_args('-vvv'.split())
720 Namespace(verbose=3)
721
722* ``'help'`` - This prints a complete help message for all the options in the
723 current parser and then exits. By default a help action is automatically
724 added to the parser. See :class:`ArgumentParser` for details of how the
725 output is created.
726
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000727* ``'version'`` - This expects a ``version=`` keyword argument in the
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300728 :meth:`~ArgumentParser.add_argument` call, and prints version information
Éric Araujoc3ef0372012-02-20 01:44:55 +0100729 and exits when invoked::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000730
731 >>> import argparse
732 >>> parser = argparse.ArgumentParser(prog='PROG')
Steven Bethard59710962010-05-24 03:21:08 +0000733 >>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')
734 >>> parser.parse_args(['--version'])
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000735 PROG 2.0
736
737You can also specify an arbitrary action by passing an object that implements
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000738the Action API. The easiest way to do this is to extend
739:class:`argparse.Action`, supplying an appropriate ``__call__`` method. The
740``__call__`` method should accept four parameters:
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000741
742* ``parser`` - The ArgumentParser object which contains this action.
743
Éric Araujo63b18a42011-07-29 17:59:17 +0200744* ``namespace`` - The :class:`Namespace` object that will be returned by
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300745 :meth:`~ArgumentParser.parse_args`. Most actions add an attribute to this
746 object.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000747
Éric Araujod9d7bca2011-08-10 04:19:03 +0200748* ``values`` - The associated command-line arguments, with any type conversions
749 applied. (Type conversions are specified with the type_ keyword argument to
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300750 :meth:`~ArgumentParser.add_argument`.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000751
752* ``option_string`` - The option string that was used to invoke this action.
753 The ``option_string`` argument is optional, and will be absent if the action
754 is associated with a positional argument.
755
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000756An example of a custom action::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000757
758 >>> class FooAction(argparse.Action):
759 ... def __call__(self, parser, namespace, values, option_string=None):
Georg Brandl571a9532010-07-26 17:00:20 +0000760 ... print('%r %r %r' % (namespace, values, option_string))
761 ... setattr(namespace, self.dest, values)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000762 ...
763 >>> parser = argparse.ArgumentParser()
764 >>> parser.add_argument('--foo', action=FooAction)
765 >>> parser.add_argument('bar', action=FooAction)
766 >>> args = parser.parse_args('1 --foo 2'.split())
767 Namespace(bar=None, foo=None) '1' None
768 Namespace(bar='1', foo=None) '2' '--foo'
769 >>> args
770 Namespace(bar='1', foo='2')
771
772
773nargs
774^^^^^
775
776ArgumentParser objects usually associate a single command-line argument with a
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000777single action to be taken. The ``nargs`` keyword argument associates a
Ezio Melotti00f53af2011-04-21 22:56:51 +0300778different number of command-line arguments with a single action. The supported
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000779values are:
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000780
Éric Araujoc3ef0372012-02-20 01:44:55 +0100781* ``N`` (an integer). ``N`` arguments from the command line will be gathered
782 together into a list. For example::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000783
Georg Brandl682d7e02010-10-06 10:26:05 +0000784 >>> parser = argparse.ArgumentParser()
785 >>> parser.add_argument('--foo', nargs=2)
786 >>> parser.add_argument('bar', nargs=1)
787 >>> parser.parse_args('c --foo a b'.split())
788 Namespace(bar=['c'], foo=['a', 'b'])
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000789
Georg Brandl682d7e02010-10-06 10:26:05 +0000790 Note that ``nargs=1`` produces a list of one item. This is different from
791 the default, in which the item is produced by itself.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000792
Éric Araujofde92422011-08-19 01:30:26 +0200793* ``'?'``. One argument will be consumed from the command line if possible, and
794 produced as a single item. If no command-line argument is present, the value from
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000795 default_ will be produced. Note that for optional arguments, there is an
796 additional case - the option string is present but not followed by a
Éric Araujofde92422011-08-19 01:30:26 +0200797 command-line argument. In this case the value from const_ will be produced. Some
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000798 examples to illustrate this::
799
800 >>> parser = argparse.ArgumentParser()
801 >>> parser.add_argument('--foo', nargs='?', const='c', default='d')
802 >>> parser.add_argument('bar', nargs='?', default='d')
803 >>> parser.parse_args('XX --foo YY'.split())
804 Namespace(bar='XX', foo='YY')
805 >>> parser.parse_args('XX --foo'.split())
806 Namespace(bar='XX', foo='c')
807 >>> parser.parse_args(''.split())
808 Namespace(bar='d', foo='d')
809
810 One of the more common uses of ``nargs='?'`` is to allow optional input and
811 output files::
812
813 >>> parser = argparse.ArgumentParser()
Georg Brandle0bf91d2010-10-17 10:34:28 +0000814 >>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
815 ... default=sys.stdin)
816 >>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
817 ... default=sys.stdout)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000818 >>> parser.parse_args(['input.txt', 'output.txt'])
Georg Brandl04536b02011-01-09 09:31:01 +0000819 Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,
820 outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000821 >>> parser.parse_args([])
Georg Brandl04536b02011-01-09 09:31:01 +0000822 Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>,
823 outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000824
Éric Araujod9d7bca2011-08-10 04:19:03 +0200825* ``'*'``. All command-line arguments present are gathered into a list. Note that
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000826 it generally doesn't make much sense to have more than one positional argument
827 with ``nargs='*'``, but multiple optional arguments with ``nargs='*'`` is
828 possible. For example::
829
830 >>> parser = argparse.ArgumentParser()
831 >>> parser.add_argument('--foo', nargs='*')
832 >>> parser.add_argument('--bar', nargs='*')
833 >>> parser.add_argument('baz', nargs='*')
834 >>> parser.parse_args('a b --foo x y --bar 1 2'.split())
835 Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])
836
837* ``'+'``. Just like ``'*'``, all command-line args present are gathered into a
838 list. Additionally, an error message will be generated if there wasn't at
Éric Araujofde92422011-08-19 01:30:26 +0200839 least one command-line argument present. For example::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000840
841 >>> parser = argparse.ArgumentParser(prog='PROG')
842 >>> parser.add_argument('foo', nargs='+')
843 >>> parser.parse_args('a b'.split())
844 Namespace(foo=['a', 'b'])
845 >>> parser.parse_args(''.split())
846 usage: PROG [-h] foo [foo ...]
847 PROG: error: too few arguments
848
Sandro Tosida8e11a2012-01-19 22:23:00 +0100849* ``argparse.REMAINDER``. All the remaining command-line arguments are gathered
850 into a list. This is commonly useful for command line utilities that dispatch
Éric Araujoc3ef0372012-02-20 01:44:55 +0100851 to other command line utilities::
Sandro Tosi16bd0b42012-01-19 21:59:55 +0100852
853 >>> parser = argparse.ArgumentParser(prog='PROG')
854 >>> parser.add_argument('--foo')
855 >>> parser.add_argument('command')
856 >>> parser.add_argument('args', nargs=argparse.REMAINDER)
Sandro Tosi04676862012-02-19 19:54:00 +0100857 >>> print(parser.parse_args('--foo B cmd --arg1 XX ZZ'.split()))
Sandro Tosida8e11a2012-01-19 22:23:00 +0100858 Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')
Sandro Tosi16bd0b42012-01-19 21:59:55 +0100859
Éric Araujod9d7bca2011-08-10 04:19:03 +0200860If the ``nargs`` keyword argument is not provided, the number of arguments consumed
Éric Araujofde92422011-08-19 01:30:26 +0200861is determined by the action_. Generally this means a single command-line argument
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000862will be consumed and a single item (not a list) will be produced.
863
864
865const
866^^^^^
867
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300868The ``const`` argument of :meth:`~ArgumentParser.add_argument` is used to hold
869constant values that are not read from the command line but are required for
870the various :class:`ArgumentParser` actions. The two most common uses of it are:
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000871
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300872* When :meth:`~ArgumentParser.add_argument` is called with
873 ``action='store_const'`` or ``action='append_const'``. These actions add the
Éric Araujoc3ef0372012-02-20 01:44:55 +0100874 ``const`` value to one of the attributes of the object returned by
875 :meth:`~ArgumentParser.parse_args`. See the action_ description for examples.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000876
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300877* When :meth:`~ArgumentParser.add_argument` is called with option strings
878 (like ``-f`` or ``--foo``) and ``nargs='?'``. This creates an optional
Éric Araujod9d7bca2011-08-10 04:19:03 +0200879 argument that can be followed by zero or one command-line arguments.
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300880 When parsing the command line, if the option string is encountered with no
Éric Araujofde92422011-08-19 01:30:26 +0200881 command-line argument following it, the value of ``const`` will be assumed instead.
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300882 See the nargs_ description for examples.
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000883
884The ``const`` keyword argument defaults to ``None``.
885
886
887default
888^^^^^^^
889
890All optional arguments and some positional arguments may be omitted at the
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300891command line. The ``default`` keyword argument of
892:meth:`~ArgumentParser.add_argument`, whose value defaults to ``None``,
Éric Araujofde92422011-08-19 01:30:26 +0200893specifies what value should be used if the command-line argument is not present.
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300894For optional arguments, the ``default`` value is used when the option string
895was not present at the command line::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000896
897 >>> parser = argparse.ArgumentParser()
898 >>> parser.add_argument('--foo', default=42)
899 >>> parser.parse_args('--foo 2'.split())
900 Namespace(foo='2')
901 >>> parser.parse_args(''.split())
902 Namespace(foo=42)
903
Éric Araujo543edbd2011-08-19 01:45:12 +0200904For positional arguments with nargs_ equal to ``?`` or ``*``, the ``default`` value
Éric Araujofde92422011-08-19 01:30:26 +0200905is used when no command-line argument was present::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000906
907 >>> parser = argparse.ArgumentParser()
908 >>> parser.add_argument('foo', nargs='?', default=42)
909 >>> parser.parse_args('a'.split())
910 Namespace(foo='a')
911 >>> parser.parse_args(''.split())
912 Namespace(foo=42)
913
914
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000915Providing ``default=argparse.SUPPRESS`` causes no attribute to be added if the
916command-line argument was not present.::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000917
918 >>> parser = argparse.ArgumentParser()
919 >>> parser.add_argument('--foo', default=argparse.SUPPRESS)
920 >>> parser.parse_args([])
921 Namespace()
922 >>> parser.parse_args(['--foo', '1'])
923 Namespace(foo='1')
924
925
926type
927^^^^
928
Éric Araujod9d7bca2011-08-10 04:19:03 +0200929By default, :class:`ArgumentParser` objects read command-line arguments in as simple
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300930strings. However, quite often the command-line string should instead be
931interpreted as another type, like a :class:`float` or :class:`int`. The
932``type`` keyword argument of :meth:`~ArgumentParser.add_argument` allows any
Éric Araujod9d7bca2011-08-10 04:19:03 +0200933necessary type-checking and type conversions to be performed. Common built-in
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300934types and functions can be used directly as the value of the ``type`` argument::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000935
936 >>> parser = argparse.ArgumentParser()
937 >>> parser.add_argument('foo', type=int)
Georg Brandl04536b02011-01-09 09:31:01 +0000938 >>> parser.add_argument('bar', type=open)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000939 >>> parser.parse_args('2 temp.txt'.split())
Georg Brandl04536b02011-01-09 09:31:01 +0000940 Namespace(bar=<_io.TextIOWrapper name='temp.txt' encoding='UTF-8'>, foo=2)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000941
942To ease the use of various types of files, the argparse module provides the
943factory FileType which takes the ``mode=`` and ``bufsize=`` arguments of the
Georg Brandl04536b02011-01-09 09:31:01 +0000944:func:`open` function. For example, ``FileType('w')`` can be used to create a
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000945writable file::
946
947 >>> parser = argparse.ArgumentParser()
948 >>> parser.add_argument('bar', type=argparse.FileType('w'))
949 >>> parser.parse_args(['out.txt'])
Georg Brandl04536b02011-01-09 09:31:01 +0000950 Namespace(bar=<_io.TextIOWrapper name='out.txt' encoding='UTF-8'>)
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000951
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000952``type=`` can take any callable that takes a single string argument and returns
Éric Araujod9d7bca2011-08-10 04:19:03 +0200953the converted value::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000954
955 >>> def perfect_square(string):
956 ... value = int(string)
957 ... sqrt = math.sqrt(value)
958 ... if sqrt != int(sqrt):
959 ... msg = "%r is not a perfect square" % string
960 ... raise argparse.ArgumentTypeError(msg)
961 ... return value
962 ...
963 >>> parser = argparse.ArgumentParser(prog='PROG')
964 >>> parser.add_argument('foo', type=perfect_square)
965 >>> parser.parse_args('9'.split())
966 Namespace(foo=9)
967 >>> parser.parse_args('7'.split())
968 usage: PROG [-h] foo
969 PROG: error: argument foo: '7' is not a perfect square
970
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000971The choices_ keyword argument may be more convenient for type checkers that
972simply check against a range of values::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000973
974 >>> parser = argparse.ArgumentParser(prog='PROG')
Fred Drakec7eb7892011-03-03 05:29:59 +0000975 >>> parser.add_argument('foo', type=int, choices=range(5, 10))
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000976 >>> parser.parse_args('7'.split())
977 Namespace(foo=7)
978 >>> parser.parse_args('11'.split())
979 usage: PROG [-h] {5,6,7,8,9}
980 PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)
981
982See the choices_ section for more details.
983
984
985choices
986^^^^^^^
987
Éric Araujod9d7bca2011-08-10 04:19:03 +0200988Some command-line arguments should be selected from a restricted set of values.
Benjamin Peterson98047eb2010-03-03 02:07:08 +0000989These can be handled by passing a container object as the ``choices`` keyword
Ezio Melotti5569e9b2011-04-22 01:42:10 +0300990argument to :meth:`~ArgumentParser.add_argument`. When the command line is
Éric Araujofde92422011-08-19 01:30:26 +0200991parsed, argument values will be checked, and an error message will be displayed if
992the argument was not one of the acceptable values::
Benjamin Peterson698a18a2010-03-02 22:34:37 +0000993
994 >>> parser = argparse.ArgumentParser(prog='PROG')
995 >>> parser.add_argument('foo', choices='abc')
996 >>> parser.parse_args('c'.split())
997 Namespace(foo='c')
998 >>> parser.parse_args('X'.split())
999 usage: PROG [-h] {a,b,c}
1000 PROG: error: argument foo: invalid choice: 'X' (choose from 'a', 'b', 'c')
1001
1002Note that inclusion in the ``choices`` container is checked after any type_
1003conversions have been performed, so the type of the objects in the ``choices``
1004container should match the type_ specified::
1005
1006 >>> parser = argparse.ArgumentParser(prog='PROG')
1007 >>> parser.add_argument('foo', type=complex, choices=[1, 1j])
1008 >>> parser.parse_args('1j'.split())
1009 Namespace(foo=1j)
1010 >>> parser.parse_args('-- -4'.split())
1011 usage: PROG [-h] {1,1j}
1012 PROG: error: argument foo: invalid choice: (-4+0j) (choose from 1, 1j)
1013
1014Any object that supports the ``in`` operator can be passed as the ``choices``
1015value, so :class:`dict` objects, :class:`set` objects, custom containers,
1016etc. are all supported.
1017
1018
1019required
1020^^^^^^^^
1021
Ezio Melotti0ee9c1b2011-04-21 16:12:17 +03001022In general, the :mod:`argparse` module assumes that flags like ``-f`` and ``--bar``
Georg Brandl1d827ff2011-04-16 16:44:54 +02001023indicate *optional* arguments, which can always be omitted at the command line.
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001024To make an option *required*, ``True`` can be specified for the ``required=``
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001025keyword argument to :meth:`~ArgumentParser.add_argument`::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001026
1027 >>> parser = argparse.ArgumentParser()
1028 >>> parser.add_argument('--foo', required=True)
1029 >>> parser.parse_args(['--foo', 'BAR'])
1030 Namespace(foo='BAR')
1031 >>> parser.parse_args([])
1032 usage: argparse.py [-h] [--foo FOO]
1033 argparse.py: error: option --foo is required
1034
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001035As the example shows, if an option is marked as ``required``,
1036:meth:`~ArgumentParser.parse_args` will report an error if that option is not
1037present at the command line.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001038
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001039.. note::
1040
1041 Required options are generally considered bad form because users expect
1042 *options* to be *optional*, and thus they should be avoided when possible.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001043
1044
1045help
1046^^^^
1047
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001048The ``help`` value is a string containing a brief description of the argument.
1049When a user requests help (usually by using ``-h`` or ``--help`` at the
Georg Brandl1d827ff2011-04-16 16:44:54 +02001050command line), these ``help`` descriptions will be displayed with each
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001051argument::
1052
1053 >>> parser = argparse.ArgumentParser(prog='frobble')
1054 >>> parser.add_argument('--foo', action='store_true',
1055 ... help='foo the bars before frobbling')
1056 >>> parser.add_argument('bar', nargs='+',
1057 ... help='one of the bars to be frobbled')
1058 >>> parser.parse_args('-h'.split())
1059 usage: frobble [-h] [--foo] bar [bar ...]
1060
1061 positional arguments:
1062 bar one of the bars to be frobbled
1063
1064 optional arguments:
1065 -h, --help show this help message and exit
1066 --foo foo the bars before frobbling
1067
1068The ``help`` strings can include various format specifiers to avoid repetition
1069of things like the program name or the argument default_. The available
1070specifiers include the program name, ``%(prog)s`` and most keyword arguments to
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001071:meth:`~ArgumentParser.add_argument`, e.g. ``%(default)s``, ``%(type)s``, etc.::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001072
1073 >>> parser = argparse.ArgumentParser(prog='frobble')
1074 >>> parser.add_argument('bar', nargs='?', type=int, default=42,
1075 ... help='the bar to %(prog)s (default: %(default)s)')
1076 >>> parser.print_help()
1077 usage: frobble [-h] [bar]
1078
1079 positional arguments:
1080 bar the bar to frobble (default: 42)
1081
1082 optional arguments:
1083 -h, --help show this help message and exit
1084
Senthil Kumaranf21804a2012-06-26 14:17:19 +08001085As the help string supports %-formatting, if you want a literal ``%`` to appear
1086in the help string, you must escape it as ``%%``.
1087
Sandro Tosiea320ab2012-01-03 18:37:03 +01001088:mod:`argparse` supports silencing the help entry for certain options, by
1089setting the ``help`` value to ``argparse.SUPPRESS``::
1090
1091 >>> parser = argparse.ArgumentParser(prog='frobble')
1092 >>> parser.add_argument('--foo', help=argparse.SUPPRESS)
1093 >>> parser.print_help()
1094 usage: frobble [-h]
1095
1096 optional arguments:
1097 -h, --help show this help message and exit
1098
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001099
1100metavar
1101^^^^^^^
1102
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001103When :class:`ArgumentParser` generates help messages, it need some way to refer
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001104to each expected argument. By default, ArgumentParser objects use the dest_
1105value as the "name" of each object. By default, for positional argument
1106actions, the dest_ value is used directly, and for optional argument actions,
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001107the dest_ value is uppercased. So, a single positional argument with
Eli Benderskya7795db2011-11-11 10:57:01 +02001108``dest='bar'`` will be referred to as ``bar``. A single
Éric Araujofde92422011-08-19 01:30:26 +02001109optional argument ``--foo`` that should be followed by a single command-line argument
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001110will be referred to as ``FOO``. An example::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001111
1112 >>> parser = argparse.ArgumentParser()
1113 >>> parser.add_argument('--foo')
1114 >>> parser.add_argument('bar')
1115 >>> parser.parse_args('X --foo Y'.split())
1116 Namespace(bar='X', foo='Y')
1117 >>> parser.print_help()
1118 usage: [-h] [--foo FOO] bar
1119
1120 positional arguments:
1121 bar
1122
1123 optional arguments:
1124 -h, --help show this help message and exit
1125 --foo FOO
1126
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001127An alternative name can be specified with ``metavar``::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001128
1129 >>> parser = argparse.ArgumentParser()
1130 >>> parser.add_argument('--foo', metavar='YYY')
1131 >>> parser.add_argument('bar', metavar='XXX')
1132 >>> parser.parse_args('X --foo Y'.split())
1133 Namespace(bar='X', foo='Y')
1134 >>> parser.print_help()
1135 usage: [-h] [--foo YYY] XXX
1136
1137 positional arguments:
1138 XXX
1139
1140 optional arguments:
1141 -h, --help show this help message and exit
1142 --foo YYY
1143
1144Note that ``metavar`` only changes the *displayed* name - the name of the
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001145attribute on the :meth:`~ArgumentParser.parse_args` object is still determined
1146by the dest_ value.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001147
1148Different values of ``nargs`` may cause the metavar to be used multiple times.
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001149Providing a tuple to ``metavar`` specifies a different display for each of the
1150arguments::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001151
1152 >>> parser = argparse.ArgumentParser(prog='PROG')
1153 >>> parser.add_argument('-x', nargs=2)
1154 >>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))
1155 >>> parser.print_help()
1156 usage: PROG [-h] [-x X X] [--foo bar baz]
1157
1158 optional arguments:
1159 -h, --help show this help message and exit
1160 -x X X
1161 --foo bar baz
1162
1163
1164dest
1165^^^^
1166
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001167Most :class:`ArgumentParser` actions add some value as an attribute of the
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001168object returned by :meth:`~ArgumentParser.parse_args`. The name of this
1169attribute is determined by the ``dest`` keyword argument of
1170:meth:`~ArgumentParser.add_argument`. For positional argument actions,
1171``dest`` is normally supplied as the first argument to
1172:meth:`~ArgumentParser.add_argument`::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001173
1174 >>> parser = argparse.ArgumentParser()
1175 >>> parser.add_argument('bar')
1176 >>> parser.parse_args('XXX'.split())
1177 Namespace(bar='XXX')
1178
1179For optional argument actions, the value of ``dest`` is normally inferred from
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001180the option strings. :class:`ArgumentParser` generates the value of ``dest`` by
Éric Araujo543edbd2011-08-19 01:45:12 +02001181taking the first long option string and stripping away the initial ``--``
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001182string. If no long option strings were supplied, ``dest`` will be derived from
Éric Araujo543edbd2011-08-19 01:45:12 +02001183the first short option string by stripping the initial ``-`` character. Any
1184internal ``-`` characters will be converted to ``_`` characters to make sure
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001185the string is a valid attribute name. The examples below illustrate this
1186behavior::
1187
1188 >>> parser = argparse.ArgumentParser()
1189 >>> parser.add_argument('-f', '--foo-bar', '--foo')
1190 >>> parser.add_argument('-x', '-y')
1191 >>> parser.parse_args('-f 1 -x 2'.split())
1192 Namespace(foo_bar='1', x='2')
1193 >>> parser.parse_args('--foo 1 -y 2'.split())
1194 Namespace(foo_bar='1', x='2')
1195
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001196``dest`` allows a custom attribute name to be provided::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001197
1198 >>> parser = argparse.ArgumentParser()
1199 >>> parser.add_argument('--foo', dest='bar')
1200 >>> parser.parse_args('--foo XXX'.split())
1201 Namespace(bar='XXX')
1202
1203
1204The parse_args() method
1205-----------------------
1206
Georg Brandle0bf91d2010-10-17 10:34:28 +00001207.. method:: ArgumentParser.parse_args(args=None, namespace=None)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001208
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001209 Convert argument strings to objects and assign them as attributes of the
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001210 namespace. Return the populated namespace.
1211
1212 Previous calls to :meth:`add_argument` determine exactly what objects are
1213 created and how they are assigned. See the documentation for
1214 :meth:`add_argument` for details.
1215
Éric Araujofde92422011-08-19 01:30:26 +02001216 By default, the argument strings are taken from :data:`sys.argv`, and a new empty
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001217 :class:`Namespace` object is created for the attributes.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001218
Georg Brandle0bf91d2010-10-17 10:34:28 +00001219
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001220Option value syntax
1221^^^^^^^^^^^^^^^^^^^
1222
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001223The :meth:`~ArgumentParser.parse_args` method supports several ways of
1224specifying the value of an option (if it takes one). In the simplest case, the
1225option and its value are passed as two separate arguments::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001226
1227 >>> parser = argparse.ArgumentParser(prog='PROG')
1228 >>> parser.add_argument('-x')
1229 >>> parser.add_argument('--foo')
1230 >>> parser.parse_args('-x X'.split())
1231 Namespace(foo=None, x='X')
1232 >>> parser.parse_args('--foo FOO'.split())
1233 Namespace(foo='FOO', x=None)
1234
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001235For long options (options with names longer than a single character), the option
Georg Brandl1d827ff2011-04-16 16:44:54 +02001236and value can also be passed as a single command-line argument, using ``=`` to
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001237separate them::
1238
1239 >>> parser.parse_args('--foo=FOO'.split())
1240 Namespace(foo='FOO', x=None)
1241
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001242For short options (options only one character long), the option and its value
1243can be concatenated::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001244
1245 >>> parser.parse_args('-xX'.split())
1246 Namespace(foo=None, x='X')
1247
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001248Several short options can be joined together, using only a single ``-`` prefix,
1249as long as only the last option (or none of them) requires a value::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001250
1251 >>> parser = argparse.ArgumentParser(prog='PROG')
1252 >>> parser.add_argument('-x', action='store_true')
1253 >>> parser.add_argument('-y', action='store_true')
1254 >>> parser.add_argument('-z')
1255 >>> parser.parse_args('-xyzZ'.split())
1256 Namespace(x=True, y=True, z='Z')
1257
1258
1259Invalid arguments
1260^^^^^^^^^^^^^^^^^
1261
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001262While parsing the command line, :meth:`~ArgumentParser.parse_args` checks for a
1263variety of errors, including ambiguous options, invalid types, invalid options,
1264wrong number of positional arguments, etc. When it encounters such an error,
1265it exits and prints the error along with a usage message::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001266
1267 >>> parser = argparse.ArgumentParser(prog='PROG')
1268 >>> parser.add_argument('--foo', type=int)
1269 >>> parser.add_argument('bar', nargs='?')
1270
1271 >>> # invalid type
1272 >>> parser.parse_args(['--foo', 'spam'])
1273 usage: PROG [-h] [--foo FOO] [bar]
1274 PROG: error: argument --foo: invalid int value: 'spam'
1275
1276 >>> # invalid option
1277 >>> parser.parse_args(['--bar'])
1278 usage: PROG [-h] [--foo FOO] [bar]
1279 PROG: error: no such option: --bar
1280
1281 >>> # wrong number of arguments
1282 >>> parser.parse_args(['spam', 'badger'])
1283 usage: PROG [-h] [--foo FOO] [bar]
1284 PROG: error: extra arguments found: badger
1285
1286
Éric Araujo543edbd2011-08-19 01:45:12 +02001287Arguments containing ``-``
1288^^^^^^^^^^^^^^^^^^^^^^^^^^
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001289
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001290The :meth:`~ArgumentParser.parse_args` method attempts to give errors whenever
1291the user has clearly made a mistake, but some situations are inherently
Éric Araujo543edbd2011-08-19 01:45:12 +02001292ambiguous. For example, the command-line argument ``-1`` could either be an
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001293attempt to specify an option or an attempt to provide a positional argument.
1294The :meth:`~ArgumentParser.parse_args` method is cautious here: positional
Éric Araujo543edbd2011-08-19 01:45:12 +02001295arguments may only begin with ``-`` if they look like negative numbers and
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001296there are no options in the parser that look like negative numbers::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001297
1298 >>> parser = argparse.ArgumentParser(prog='PROG')
1299 >>> parser.add_argument('-x')
1300 >>> parser.add_argument('foo', nargs='?')
1301
1302 >>> # no negative number options, so -1 is a positional argument
1303 >>> parser.parse_args(['-x', '-1'])
1304 Namespace(foo=None, x='-1')
1305
1306 >>> # no negative number options, so -1 and -5 are positional arguments
1307 >>> parser.parse_args(['-x', '-1', '-5'])
1308 Namespace(foo='-5', x='-1')
1309
1310 >>> parser = argparse.ArgumentParser(prog='PROG')
1311 >>> parser.add_argument('-1', dest='one')
1312 >>> parser.add_argument('foo', nargs='?')
1313
1314 >>> # negative number options present, so -1 is an option
1315 >>> parser.parse_args(['-1', 'X'])
1316 Namespace(foo=None, one='X')
1317
1318 >>> # negative number options present, so -2 is an option
1319 >>> parser.parse_args(['-2'])
1320 usage: PROG [-h] [-1 ONE] [foo]
1321 PROG: error: no such option: -2
1322
1323 >>> # negative number options present, so both -1s are options
1324 >>> parser.parse_args(['-1', '-1'])
1325 usage: PROG [-h] [-1 ONE] [foo]
1326 PROG: error: argument -1: expected one argument
1327
Éric Araujo543edbd2011-08-19 01:45:12 +02001328If you have positional arguments that must begin with ``-`` and don't look
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001329like negative numbers, you can insert the pseudo-argument ``'--'`` which tells
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001330:meth:`~ArgumentParser.parse_args` that everything after that is a positional
1331argument::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001332
1333 >>> parser.parse_args(['--', '-f'])
1334 Namespace(foo='-f', one=None)
1335
1336
1337Argument abbreviations
1338^^^^^^^^^^^^^^^^^^^^^^
1339
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001340The :meth:`~ArgumentParser.parse_args` method allows long options to be
1341abbreviated if the abbreviation is unambiguous::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001342
1343 >>> parser = argparse.ArgumentParser(prog='PROG')
1344 >>> parser.add_argument('-bacon')
1345 >>> parser.add_argument('-badger')
1346 >>> parser.parse_args('-bac MMM'.split())
1347 Namespace(bacon='MMM', badger=None)
1348 >>> parser.parse_args('-bad WOOD'.split())
1349 Namespace(bacon=None, badger='WOOD')
1350 >>> parser.parse_args('-ba BA'.split())
1351 usage: PROG [-h] [-bacon BACON] [-badger BADGER]
1352 PROG: error: ambiguous option: -ba could match -badger, -bacon
1353
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001354An error is produced for arguments that could produce more than one options.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001355
1356
1357Beyond ``sys.argv``
1358^^^^^^^^^^^^^^^^^^^
1359
Éric Araujod9d7bca2011-08-10 04:19:03 +02001360Sometimes it may be useful to have an ArgumentParser parse arguments other than those
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001361of :data:`sys.argv`. This can be accomplished by passing a list of strings to
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001362:meth:`~ArgumentParser.parse_args`. This is useful for testing at the
1363interactive prompt::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001364
1365 >>> parser = argparse.ArgumentParser()
1366 >>> parser.add_argument(
Fred Drakec7eb7892011-03-03 05:29:59 +00001367 ... 'integers', metavar='int', type=int, choices=range(10),
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001368 ... nargs='+', help='an integer in the range 0..9')
1369 >>> parser.add_argument(
1370 ... '--sum', dest='accumulate', action='store_const', const=sum,
1371 ... default=max, help='sum the integers (default: find the max)')
1372 >>> parser.parse_args(['1', '2', '3', '4'])
1373 Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
1374 >>> parser.parse_args('1 2 3 4 --sum'.split())
1375 Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])
1376
1377
Steven Bethardd8f2d502011-03-26 19:50:06 +01001378The Namespace object
1379^^^^^^^^^^^^^^^^^^^^
1380
Éric Araujo63b18a42011-07-29 17:59:17 +02001381.. class:: Namespace
1382
1383 Simple class used by default by :meth:`~ArgumentParser.parse_args` to create
1384 an object holding attributes and return it.
1385
1386This class is deliberately simple, just an :class:`object` subclass with a
1387readable string representation. If you prefer to have dict-like view of the
1388attributes, you can use the standard Python idiom, :func:`vars`::
Steven Bethardd8f2d502011-03-26 19:50:06 +01001389
1390 >>> parser = argparse.ArgumentParser()
1391 >>> parser.add_argument('--foo')
1392 >>> args = parser.parse_args(['--foo', 'BAR'])
1393 >>> vars(args)
1394 {'foo': 'BAR'}
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001395
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001396It may also be useful to have an :class:`ArgumentParser` assign attributes to an
Steven Bethardd8f2d502011-03-26 19:50:06 +01001397already existing object, rather than a new :class:`Namespace` object. This can
1398be achieved by specifying the ``namespace=`` keyword argument::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001399
Éric Araujo28053fb2010-11-22 03:09:19 +00001400 >>> class C:
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001401 ... pass
1402 ...
1403 >>> c = C()
1404 >>> parser = argparse.ArgumentParser()
1405 >>> parser.add_argument('--foo')
1406 >>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
1407 >>> c.foo
1408 'BAR'
1409
1410
1411Other utilities
1412---------------
1413
1414Sub-commands
1415^^^^^^^^^^^^
1416
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001417.. method:: ArgumentParser.add_subparsers()
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001418
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001419 Many programs split up their functionality into a number of sub-commands,
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001420 for example, the ``svn`` program can invoke sub-commands like ``svn
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001421 checkout``, ``svn update``, and ``svn commit``. Splitting up functionality
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001422 this way can be a particularly good idea when a program performs several
1423 different functions which require different kinds of command-line arguments.
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001424 :class:`ArgumentParser` supports the creation of such sub-commands with the
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001425 :meth:`add_subparsers` method. The :meth:`add_subparsers` method is normally
1426 called with no arguments and returns an special action object. This object
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001427 has a single method, :meth:`~ArgumentParser.add_parser`, which takes a
1428 command name and any :class:`ArgumentParser` constructor arguments, and
1429 returns an :class:`ArgumentParser` object that can be modified as usual.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001430
1431 Some example usage::
1432
1433 >>> # create the top-level parser
1434 >>> parser = argparse.ArgumentParser(prog='PROG')
1435 >>> parser.add_argument('--foo', action='store_true', help='foo help')
1436 >>> subparsers = parser.add_subparsers(help='sub-command help')
1437 >>>
1438 >>> # create the parser for the "a" command
1439 >>> parser_a = subparsers.add_parser('a', help='a help')
1440 >>> parser_a.add_argument('bar', type=int, help='bar help')
1441 >>>
1442 >>> # create the parser for the "b" command
1443 >>> parser_b = subparsers.add_parser('b', help='b help')
1444 >>> parser_b.add_argument('--baz', choices='XYZ', help='baz help')
1445 >>>
Éric Araujofde92422011-08-19 01:30:26 +02001446 >>> # parse some argument lists
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001447 >>> parser.parse_args(['a', '12'])
1448 Namespace(bar=12, foo=False)
1449 >>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
1450 Namespace(baz='Z', foo=True)
1451
1452 Note that the object returned by :meth:`parse_args` will only contain
1453 attributes for the main parser and the subparser that was selected by the
1454 command line (and not any other subparsers). So in the example above, when
Éric Araujo543edbd2011-08-19 01:45:12 +02001455 the ``a`` command is specified, only the ``foo`` and ``bar`` attributes are
1456 present, and when the ``b`` command is specified, only the ``foo`` and
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001457 ``baz`` attributes are present.
1458
1459 Similarly, when a help message is requested from a subparser, only the help
1460 for that particular parser will be printed. The help message will not
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001461 include parent parser or sibling parser messages. (A help message for each
1462 subparser command, however, can be given by supplying the ``help=`` argument
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001463 to :meth:`add_parser` as above.)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001464
1465 ::
1466
1467 >>> parser.parse_args(['--help'])
1468 usage: PROG [-h] [--foo] {a,b} ...
1469
1470 positional arguments:
1471 {a,b} sub-command help
1472 a a help
1473 b b help
1474
1475 optional arguments:
1476 -h, --help show this help message and exit
1477 --foo foo help
1478
1479 >>> parser.parse_args(['a', '--help'])
1480 usage: PROG a [-h] bar
1481
1482 positional arguments:
1483 bar bar help
1484
1485 optional arguments:
1486 -h, --help show this help message and exit
1487
1488 >>> parser.parse_args(['b', '--help'])
1489 usage: PROG b [-h] [--baz {X,Y,Z}]
1490
1491 optional arguments:
1492 -h, --help show this help message and exit
1493 --baz {X,Y,Z} baz help
1494
1495 The :meth:`add_subparsers` method also supports ``title`` and ``description``
1496 keyword arguments. When either is present, the subparser's commands will
1497 appear in their own group in the help output. For example::
1498
1499 >>> parser = argparse.ArgumentParser()
1500 >>> subparsers = parser.add_subparsers(title='subcommands',
1501 ... description='valid subcommands',
1502 ... help='additional help')
1503 >>> subparsers.add_parser('foo')
1504 >>> subparsers.add_parser('bar')
1505 >>> parser.parse_args(['-h'])
1506 usage: [-h] {foo,bar} ...
1507
1508 optional arguments:
1509 -h, --help show this help message and exit
1510
1511 subcommands:
1512 valid subcommands
1513
1514 {foo,bar} additional help
1515
Steven Bethardfd311a72010-12-18 11:19:23 +00001516 Furthermore, ``add_parser`` supports an additional ``aliases`` argument,
1517 which allows multiple strings to refer to the same subparser. This example,
1518 like ``svn``, aliases ``co`` as a shorthand for ``checkout``::
1519
1520 >>> parser = argparse.ArgumentParser()
1521 >>> subparsers = parser.add_subparsers()
1522 >>> checkout = subparsers.add_parser('checkout', aliases=['co'])
1523 >>> checkout.add_argument('foo')
1524 >>> parser.parse_args(['co', 'bar'])
1525 Namespace(foo='bar')
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001526
1527 One particularly effective way of handling sub-commands is to combine the use
1528 of the :meth:`add_subparsers` method with calls to :meth:`set_defaults` so
1529 that each subparser knows which Python function it should execute. For
1530 example::
1531
1532 >>> # sub-command functions
1533 >>> def foo(args):
Benjamin Petersonb2deb112010-03-03 02:09:18 +00001534 ... print(args.x * args.y)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001535 ...
1536 >>> def bar(args):
Benjamin Petersonb2deb112010-03-03 02:09:18 +00001537 ... print('((%s))' % args.z)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001538 ...
1539 >>> # create the top-level parser
1540 >>> parser = argparse.ArgumentParser()
1541 >>> subparsers = parser.add_subparsers()
1542 >>>
1543 >>> # create the parser for the "foo" command
1544 >>> parser_foo = subparsers.add_parser('foo')
1545 >>> parser_foo.add_argument('-x', type=int, default=1)
1546 >>> parser_foo.add_argument('y', type=float)
1547 >>> parser_foo.set_defaults(func=foo)
1548 >>>
1549 >>> # create the parser for the "bar" command
1550 >>> parser_bar = subparsers.add_parser('bar')
1551 >>> parser_bar.add_argument('z')
1552 >>> parser_bar.set_defaults(func=bar)
1553 >>>
1554 >>> # parse the args and call whatever function was selected
1555 >>> args = parser.parse_args('foo 1 -x 2'.split())
1556 >>> args.func(args)
1557 2.0
1558 >>>
1559 >>> # parse the args and call whatever function was selected
1560 >>> args = parser.parse_args('bar XYZYX'.split())
1561 >>> args.func(args)
1562 ((XYZYX))
1563
Steven Bethardfd311a72010-12-18 11:19:23 +00001564 This way, you can let :meth:`parse_args` do the job of calling the
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001565 appropriate function after argument parsing is complete. Associating
1566 functions with actions like this is typically the easiest way to handle the
1567 different actions for each of your subparsers. However, if it is necessary
1568 to check the name of the subparser that was invoked, the ``dest`` keyword
1569 argument to the :meth:`add_subparsers` call will work::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001570
1571 >>> parser = argparse.ArgumentParser()
1572 >>> subparsers = parser.add_subparsers(dest='subparser_name')
1573 >>> subparser1 = subparsers.add_parser('1')
1574 >>> subparser1.add_argument('-x')
1575 >>> subparser2 = subparsers.add_parser('2')
1576 >>> subparser2.add_argument('y')
1577 >>> parser.parse_args(['2', 'frobble'])
1578 Namespace(subparser_name='2', y='frobble')
1579
1580
1581FileType objects
1582^^^^^^^^^^^^^^^^
1583
1584.. class:: FileType(mode='r', bufsize=None)
1585
1586 The :class:`FileType` factory creates objects that can be passed to the type
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001587 argument of :meth:`ArgumentParser.add_argument`. Arguments that have
Éric Araujod9d7bca2011-08-10 04:19:03 +02001588 :class:`FileType` objects as their type will open command-line arguments as files
Éric Araujoc3ef0372012-02-20 01:44:55 +01001589 with the requested modes and buffer sizes::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001590
Éric Araujoc3ef0372012-02-20 01:44:55 +01001591 >>> parser = argparse.ArgumentParser()
1592 >>> parser.add_argument('--output', type=argparse.FileType('wb', 0))
1593 >>> parser.parse_args(['--output', 'out'])
1594 Namespace(output=<_io.BufferedWriter name='out'>)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001595
1596 FileType objects understand the pseudo-argument ``'-'`` and automatically
1597 convert this into ``sys.stdin`` for readable :class:`FileType` objects and
Éric Araujoc3ef0372012-02-20 01:44:55 +01001598 ``sys.stdout`` for writable :class:`FileType` objects::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001599
Éric Araujoc3ef0372012-02-20 01:44:55 +01001600 >>> parser = argparse.ArgumentParser()
1601 >>> parser.add_argument('infile', type=argparse.FileType('r'))
1602 >>> parser.parse_args(['-'])
1603 Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001604
1605
1606Argument groups
1607^^^^^^^^^^^^^^^
1608
Georg Brandle0bf91d2010-10-17 10:34:28 +00001609.. method:: ArgumentParser.add_argument_group(title=None, description=None)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001610
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001611 By default, :class:`ArgumentParser` groups command-line arguments into
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001612 "positional arguments" and "optional arguments" when displaying help
1613 messages. When there is a better conceptual grouping of arguments than this
1614 default one, appropriate groups can be created using the
1615 :meth:`add_argument_group` method::
1616
1617 >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
1618 >>> group = parser.add_argument_group('group')
1619 >>> group.add_argument('--foo', help='foo help')
1620 >>> group.add_argument('bar', help='bar help')
1621 >>> parser.print_help()
1622 usage: PROG [--foo FOO] bar
1623
1624 group:
1625 bar bar help
1626 --foo FOO foo help
1627
1628 The :meth:`add_argument_group` method returns an argument group object which
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001629 has an :meth:`~ArgumentParser.add_argument` method just like a regular
1630 :class:`ArgumentParser`. When an argument is added to the group, the parser
1631 treats it just like a normal argument, but displays the argument in a
1632 separate group for help messages. The :meth:`add_argument_group` method
Georg Brandle0bf91d2010-10-17 10:34:28 +00001633 accepts *title* and *description* arguments which can be used to
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001634 customize this display::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001635
1636 >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
1637 >>> group1 = parser.add_argument_group('group1', 'group1 description')
1638 >>> group1.add_argument('foo', help='foo help')
1639 >>> group2 = parser.add_argument_group('group2', 'group2 description')
1640 >>> group2.add_argument('--bar', help='bar help')
1641 >>> parser.print_help()
1642 usage: PROG [--bar BAR] foo
1643
1644 group1:
1645 group1 description
1646
1647 foo foo help
1648
1649 group2:
1650 group2 description
1651
1652 --bar BAR bar help
1653
Sandro Tosi99e7d072012-03-26 19:36:23 +02001654 Note that any arguments not in your user-defined groups will end up back
1655 in the usual "positional arguments" and "optional arguments" sections.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001656
1657
1658Mutual exclusion
1659^^^^^^^^^^^^^^^^
1660
Georg Brandle0bf91d2010-10-17 10:34:28 +00001661.. method:: add_mutually_exclusive_group(required=False)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001662
Ezio Melotti0ee9c1b2011-04-21 16:12:17 +03001663 Create a mutually exclusive group. :mod:`argparse` will make sure that only
1664 one of the arguments in the mutually exclusive group was present on the
1665 command line::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001666
1667 >>> parser = argparse.ArgumentParser(prog='PROG')
1668 >>> group = parser.add_mutually_exclusive_group()
1669 >>> group.add_argument('--foo', action='store_true')
1670 >>> group.add_argument('--bar', action='store_false')
1671 >>> parser.parse_args(['--foo'])
1672 Namespace(bar=True, foo=True)
1673 >>> parser.parse_args(['--bar'])
1674 Namespace(bar=False, foo=False)
1675 >>> parser.parse_args(['--foo', '--bar'])
1676 usage: PROG [-h] [--foo | --bar]
1677 PROG: error: argument --bar: not allowed with argument --foo
1678
Georg Brandle0bf91d2010-10-17 10:34:28 +00001679 The :meth:`add_mutually_exclusive_group` method also accepts a *required*
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001680 argument, to indicate that at least one of the mutually exclusive arguments
1681 is required::
1682
1683 >>> parser = argparse.ArgumentParser(prog='PROG')
1684 >>> group = parser.add_mutually_exclusive_group(required=True)
1685 >>> group.add_argument('--foo', action='store_true')
1686 >>> group.add_argument('--bar', action='store_false')
1687 >>> parser.parse_args([])
1688 usage: PROG [-h] (--foo | --bar)
1689 PROG: error: one of the arguments --foo --bar is required
1690
1691 Note that currently mutually exclusive argument groups do not support the
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001692 *title* and *description* arguments of
1693 :meth:`~ArgumentParser.add_argument_group`.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001694
1695
1696Parser defaults
1697^^^^^^^^^^^^^^^
1698
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001699.. method:: ArgumentParser.set_defaults(**kwargs)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001700
1701 Most of the time, the attributes of the object returned by :meth:`parse_args`
Éric Araujod9d7bca2011-08-10 04:19:03 +02001702 will be fully determined by inspecting the command-line arguments and the argument
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001703 actions. :meth:`set_defaults` allows some additional
Georg Brandl1d827ff2011-04-16 16:44:54 +02001704 attributes that are determined without any inspection of the command line to
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001705 be added::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001706
1707 >>> parser = argparse.ArgumentParser()
1708 >>> parser.add_argument('foo', type=int)
1709 >>> parser.set_defaults(bar=42, baz='badger')
1710 >>> parser.parse_args(['736'])
1711 Namespace(bar=42, baz='badger', foo=736)
1712
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001713 Note that parser-level defaults always override argument-level defaults::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001714
1715 >>> parser = argparse.ArgumentParser()
1716 >>> parser.add_argument('--foo', default='bar')
1717 >>> parser.set_defaults(foo='spam')
1718 >>> parser.parse_args([])
1719 Namespace(foo='spam')
1720
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001721 Parser-level defaults can be particularly useful when working with multiple
1722 parsers. See the :meth:`~ArgumentParser.add_subparsers` method for an
1723 example of this type.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001724
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001725.. method:: ArgumentParser.get_default(dest)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001726
1727 Get the default value for a namespace attribute, as set by either
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001728 :meth:`~ArgumentParser.add_argument` or by
1729 :meth:`~ArgumentParser.set_defaults`::
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001730
1731 >>> parser = argparse.ArgumentParser()
1732 >>> parser.add_argument('--foo', default='badger')
1733 >>> parser.get_default('foo')
1734 'badger'
1735
1736
1737Printing help
1738^^^^^^^^^^^^^
1739
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001740In most typical applications, :meth:`~ArgumentParser.parse_args` will take
1741care of formatting and printing any usage or error messages. However, several
1742formatting methods are available:
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001743
Georg Brandle0bf91d2010-10-17 10:34:28 +00001744.. method:: ArgumentParser.print_usage(file=None)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001745
1746 Print a brief description of how the :class:`ArgumentParser` should be
R. David Murray32e17712010-12-18 16:39:06 +00001747 invoked on the command line. If *file* is ``None``, :data:`sys.stdout` is
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001748 assumed.
1749
Georg Brandle0bf91d2010-10-17 10:34:28 +00001750.. method:: ArgumentParser.print_help(file=None)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001751
1752 Print a help message, including the program usage and information about the
Georg Brandle0bf91d2010-10-17 10:34:28 +00001753 arguments registered with the :class:`ArgumentParser`. If *file* is
R. David Murray32e17712010-12-18 16:39:06 +00001754 ``None``, :data:`sys.stdout` is assumed.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001755
1756There are also variants of these methods that simply return a string instead of
1757printing it:
1758
Georg Brandle0bf91d2010-10-17 10:34:28 +00001759.. method:: ArgumentParser.format_usage()
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001760
1761 Return a string containing a brief description of how the
1762 :class:`ArgumentParser` should be invoked on the command line.
1763
Georg Brandle0bf91d2010-10-17 10:34:28 +00001764.. method:: ArgumentParser.format_help()
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001765
1766 Return a string containing a help message, including the program usage and
1767 information about the arguments registered with the :class:`ArgumentParser`.
1768
1769
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001770Partial parsing
1771^^^^^^^^^^^^^^^
1772
Georg Brandle0bf91d2010-10-17 10:34:28 +00001773.. method:: ArgumentParser.parse_known_args(args=None, namespace=None)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001774
Georg Brandl1d827ff2011-04-16 16:44:54 +02001775Sometimes a script may only parse a few of the command-line arguments, passing
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001776the remaining arguments on to another script or program. In these cases, the
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001777:meth:`~ArgumentParser.parse_known_args` method can be useful. It works much like
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001778:meth:`~ArgumentParser.parse_args` except that it does not produce an error when
1779extra arguments are present. Instead, it returns a two item tuple containing
1780the populated namespace and the list of remaining argument strings.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001781
1782::
1783
1784 >>> parser = argparse.ArgumentParser()
1785 >>> parser.add_argument('--foo', action='store_true')
1786 >>> parser.add_argument('bar')
1787 >>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
1788 (Namespace(bar='BAR', foo=True), ['--badger', 'spam'])
1789
1790
1791Customizing file parsing
1792^^^^^^^^^^^^^^^^^^^^^^^^
1793
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001794.. method:: ArgumentParser.convert_arg_line_to_args(arg_line)
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001795
Georg Brandle0bf91d2010-10-17 10:34:28 +00001796 Arguments that are read from a file (see the *fromfile_prefix_chars*
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001797 keyword argument to the :class:`ArgumentParser` constructor) are read one
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001798 argument per line. :meth:`convert_arg_line_to_args` can be overriden for
1799 fancier reading.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001800
Georg Brandle0bf91d2010-10-17 10:34:28 +00001801 This method takes a single argument *arg_line* which is a string read from
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001802 the argument file. It returns a list of arguments parsed from this string.
1803 The method is called once per line read from the argument file, in order.
1804
1805 A useful override of this method is one that treats each space-separated word
1806 as an argument::
1807
1808 def convert_arg_line_to_args(self, arg_line):
1809 for arg in arg_line.split():
1810 if not arg.strip():
1811 continue
1812 yield arg
1813
1814
Georg Brandl93754922010-10-17 10:28:04 +00001815Exiting methods
1816^^^^^^^^^^^^^^^
1817
1818.. method:: ArgumentParser.exit(status=0, message=None)
1819
1820 This method terminates the program, exiting with the specified *status*
1821 and, if given, it prints a *message* before that.
1822
1823.. method:: ArgumentParser.error(message)
1824
1825 This method prints a usage message including the *message* to the
Senthil Kumaran86a1a892011-08-03 07:42:18 +08001826 standard error and terminates the program with a status code of 2.
Georg Brandl93754922010-10-17 10:28:04 +00001827
Raymond Hettinger677e10a2010-12-07 06:45:30 +00001828.. _upgrading-optparse-code:
Georg Brandl93754922010-10-17 10:28:04 +00001829
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001830Upgrading optparse code
1831-----------------------
1832
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001833Originally, the :mod:`argparse` module had attempted to maintain compatibility
Ezio Melotti0ee9c1b2011-04-21 16:12:17 +03001834with :mod:`optparse`. However, :mod:`optparse` was difficult to extend
1835transparently, particularly with the changes required to support the new
1836``nargs=`` specifiers and better usage messages. When most everything in
1837:mod:`optparse` had either been copy-pasted over or monkey-patched, it no
1838longer seemed practical to try to maintain the backwards compatibility.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001839
Ezio Melotti0ee9c1b2011-04-21 16:12:17 +03001840A partial upgrade path from :mod:`optparse` to :mod:`argparse`:
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001841
Ezio Melotti5569e9b2011-04-22 01:42:10 +03001842* Replace all :meth:`optparse.OptionParser.add_option` calls with
1843 :meth:`ArgumentParser.add_argument` calls.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001844
R David Murray5e0c5712012-03-30 18:07:42 -04001845* Replace ``(options, args) = parser.parse_args()`` with ``args =
Georg Brandlc9007082011-01-09 09:04:08 +00001846 parser.parse_args()`` and add additional :meth:`ArgumentParser.add_argument`
R David Murray5e0c5712012-03-30 18:07:42 -04001847 calls for the positional arguments. Keep in mind that what was previously
1848 called ``options``, now in :mod:`argparse` context is called ``args``.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001849
1850* Replace callback actions and the ``callback_*`` keyword arguments with
1851 ``type`` or ``action`` arguments.
1852
1853* Replace string names for ``type`` keyword arguments with the corresponding
1854 type objects (e.g. int, float, complex, etc).
1855
Benjamin Peterson98047eb2010-03-03 02:07:08 +00001856* Replace :class:`optparse.Values` with :class:`Namespace` and
1857 :exc:`optparse.OptionError` and :exc:`optparse.OptionValueError` with
1858 :exc:`ArgumentError`.
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001859
1860* Replace strings with implicit arguments such as ``%default`` or ``%prog`` with
Ezio Melotticca4ef82011-04-21 15:26:46 +03001861 the standard Python syntax to use dictionaries to format strings, that is,
Benjamin Peterson698a18a2010-03-02 22:34:37 +00001862 ``%(default)s`` and ``%(prog)s``.
Steven Bethard59710962010-05-24 03:21:08 +00001863
1864* Replace the OptionParser constructor ``version`` argument with a call to
1865 ``parser.add_argument('--version', action='version', version='<the version>')``