Mercurial > cpython-lru_cache-weakref
annotate Doc/library/argparse.rst @ 79675:c0a2294de787 2.7
Issue #16199: Backport 2to3 typo fix from 3.2.
| author | Chris Jerdonek <chris.jerdonek@gmail.com> |
|---|---|
| date | Thu, 11 Oct 2012 16:15:46 -0700 |
| parents | b624059a8dac |
| children | c1623a032adf |
| rev | line source |
|---|---|
|
69406
cc65cf9a9ce5
Fix a few hyphens in argparse.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
68987
diff
changeset
|
1 :mod:`argparse` --- Parser for command-line options, arguments and sub-commands |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
2 =============================================================================== |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
3 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
4 .. module:: argparse |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
5 :synopsis: Command-line option and argument parsing library. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
6 .. moduleauthor:: Steven Bethard <steven.bethard@gmail.com> |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
7 .. sectionauthor:: Steven Bethard <steven.bethard@gmail.com> |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
8 |
|
71952
b5674229d0f9
Backport source links from 3.x.
Éric Araujo <merwok@netwok.org>
parents:
71950
diff
changeset
|
9 .. versionadded:: 2.7 |
|
b5674229d0f9
Backport source links from 3.x.
Éric Araujo <merwok@netwok.org>
parents:
71950
diff
changeset
|
10 |
|
b5674229d0f9
Backport source links from 3.x.
Éric Araujo <merwok@netwok.org>
parents:
71950
diff
changeset
|
11 **Source code:** :source:`Lib/argparse.py` |
|
b5674229d0f9
Backport source links from 3.x.
Éric Araujo <merwok@netwok.org>
parents:
71950
diff
changeset
|
12 |
|
b5674229d0f9
Backport source links from 3.x.
Éric Araujo <merwok@netwok.org>
parents:
71950
diff
changeset
|
13 -------------- |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
14 |
|
76791
48385618525b
#14034: added the argparse tutorial. Patch by Tshepang Lekhonkhobe.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
76001
diff
changeset
|
15 .. sidebar:: Tutorial |
|
48385618525b
#14034: added the argparse tutorial. Patch by Tshepang Lekhonkhobe.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
76001
diff
changeset
|
16 |
|
48385618525b
#14034: added the argparse tutorial. Patch by Tshepang Lekhonkhobe.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
76001
diff
changeset
|
17 This page contains the API reference information. For a more gentle |
|
48385618525b
#14034: added the argparse tutorial. Patch by Tshepang Lekhonkhobe.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
76001
diff
changeset
|
18 introduction to Python command-line parsing, have a look at the |
|
48385618525b
#14034: added the argparse tutorial. Patch by Tshepang Lekhonkhobe.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
76001
diff
changeset
|
19 :ref:`argparse tutorial <argparse-tutorial>`. |
|
48385618525b
#14034: added the argparse tutorial. Patch by Tshepang Lekhonkhobe.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
76001
diff
changeset
|
20 |
|
69406
cc65cf9a9ce5
Fix a few hyphens in argparse.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
68987
diff
changeset
|
21 The :mod:`argparse` module makes it easy to write user-friendly command-line |
| 59293 | 22 interfaces. The program defines what arguments it requires, and :mod:`argparse` |
| 59269 | 23 will figure out how to parse those out of :data:`sys.argv`. The :mod:`argparse` |
| 59293 | 24 module also automatically generates help and usage messages and issues errors |
| 25 when users give the program invalid arguments. | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
26 |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
27 |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
28 Example |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
29 ------- |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
30 |
| 59293 | 31 The following code is a Python program that takes a list of integers and |
| 32 produces either the sum or the max:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
33 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
34 import argparse |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
35 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
36 parser = argparse.ArgumentParser(description='Process some integers.') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
37 parser.add_argument('integers', metavar='N', type=int, nargs='+', |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
38 help='an integer for the accumulator') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
39 parser.add_argument('--sum', dest='accumulate', action='store_const', |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
40 const=sum, default=max, |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
41 help='sum the integers (default: find the max)') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
42 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
43 args = parser.parse_args() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
44 print args.accumulate(args.integers) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
45 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
46 Assuming the Python code above is saved into a file called ``prog.py``, it can |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
47 be run at the command line and provides useful help messages:: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
48 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
49 $ prog.py -h |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
50 usage: prog.py [-h] [--sum] N [N ...] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
51 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
52 Process some integers. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
53 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
54 positional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
55 N an integer for the accumulator |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
56 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
57 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
58 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
59 --sum sum the integers (default: find the max) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
60 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
61 When run with the appropriate arguments, it prints either the sum or the max of |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
62 the command-line integers:: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
63 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
64 $ prog.py 1 2 3 4 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
65 4 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
66 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
67 $ prog.py 1 2 3 4 --sum |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
68 10 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
69 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
70 If invalid arguments are passed in, it will issue an error:: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
71 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
72 $ prog.py a b c |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
73 usage: prog.py [-h] [--sum] N [N ...] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
74 prog.py: error: argument N: invalid int value: 'a' |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
75 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
76 The following sections walk you through this example. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
77 |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
78 |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
79 Creating a parser |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
80 ^^^^^^^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
81 |
| 59311 | 82 The first step in using the :mod:`argparse` is creating an |
| 59293 | 83 :class:`ArgumentParser` object:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
84 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
85 >>> parser = argparse.ArgumentParser(description='Process some integers.') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
86 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
87 The :class:`ArgumentParser` object will hold all the information necessary to |
|
69509
0f084f150198
#11885: capitalize Python.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69406
diff
changeset
|
88 parse the command line into Python data types. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
89 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
90 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
91 Adding arguments |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
92 ^^^^^^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
93 |
| 59293 | 94 Filling an :class:`ArgumentParser` with information about program arguments is |
| 95 done by making calls to the :meth:`~ArgumentParser.add_argument` method. | |
| 96 Generally, these calls tell the :class:`ArgumentParser` how to take the strings | |
| 97 on the command line and turn them into objects. This information is stored and | |
| 98 used when :meth:`~ArgumentParser.parse_args` is called. For example:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
99 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
100 >>> parser.add_argument('integers', metavar='N', type=int, nargs='+', |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
101 ... help='an integer for the accumulator') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
102 >>> parser.add_argument('--sum', dest='accumulate', action='store_const', |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
103 ... const=sum, default=max, |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
104 ... help='sum the integers (default: find the max)') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
105 |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
106 Later, calling :meth:`~ArgumentParser.parse_args` will return an object with |
| 59269 | 107 two attributes, ``integers`` and ``accumulate``. The ``integers`` attribute |
| 108 will be a list of one or more ints, and the ``accumulate`` attribute will be | |
| 109 either the :func:`sum` function, if ``--sum`` was specified at the command line, | |
| 110 or the :func:`max` function if it was not. | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
111 |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
112 |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
113 Parsing arguments |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
114 ^^^^^^^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
115 |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
116 :class:`ArgumentParser` parses arguments through the |
|
69406
cc65cf9a9ce5
Fix a few hyphens in argparse.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
68987
diff
changeset
|
117 :meth:`~ArgumentParser.parse_args` method. This will inspect the command line, |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
118 convert each argument to the appropriate type and then invoke the appropriate action. |
|
71606
01722022f88d
Add a link target for argparse.Namespace (#8982)
Éric Araujo <merwok@netwok.org>
parents:
69525
diff
changeset
|
119 In most cases, this means a simple :class:`Namespace` object will be built up from |
|
69406
cc65cf9a9ce5
Fix a few hyphens in argparse.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
68987
diff
changeset
|
120 attributes parsed out of the command line:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
121 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
122 >>> parser.parse_args(['--sum', '7', '-1', '42']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
123 Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42]) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
124 |
| 59293 | 125 In a script, :meth:`~ArgumentParser.parse_args` will typically be called with no |
| 126 arguments, and the :class:`ArgumentParser` will automatically determine the | |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
127 command-line arguments from :data:`sys.argv`. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
128 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
129 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
130 ArgumentParser objects |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
131 ---------------------- |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
132 |
|
79025
2291aff20a05
#15831: document multiple signatures on different lines. Patch by Chris Jerdonek.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
78515
diff
changeset
|
133 .. class:: ArgumentParser(prog=None, usage=None, description=None, \ |
|
2291aff20a05
#15831: document multiple signatures on different lines. Patch by Chris Jerdonek.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
78515
diff
changeset
|
134 epilog=None, parents=[], \ |
|
2291aff20a05
#15831: document multiple signatures on different lines. Patch by Chris Jerdonek.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
78515
diff
changeset
|
135 formatter_class=argparse.HelpFormatter, \ |
|
2291aff20a05
#15831: document multiple signatures on different lines. Patch by Chris Jerdonek.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
78515
diff
changeset
|
136 prefix_chars='-', fromfile_prefix_chars=None, \ |
|
2291aff20a05
#15831: document multiple signatures on different lines. Patch by Chris Jerdonek.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
78515
diff
changeset
|
137 argument_default=None, conflict_handler='error', \ |
|
2291aff20a05
#15831: document multiple signatures on different lines. Patch by Chris Jerdonek.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
78515
diff
changeset
|
138 add_help=True) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
139 |
| 59269 | 140 Create a new :class:`ArgumentParser` object. Each parameter has its own more |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
141 detailed description below, but in short they are: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
142 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
143 * description_ - Text to display before the argument help. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
144 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
145 * epilog_ - Text to display after the argument help. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
146 |
| 59293 | 147 * add_help_ - Add a -h/--help option to the parser. (default: ``True``) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
148 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
149 * argument_default_ - Set the global default value for arguments. |
| 59293 | 150 (default: ``None``) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
151 |
| 59293 | 152 * parents_ - A list of :class:`ArgumentParser` objects whose arguments should |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
153 also be included. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
154 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
155 * prefix_chars_ - The set of characters that prefix optional arguments. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
156 (default: '-') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
157 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
158 * fromfile_prefix_chars_ - The set of characters that prefix files from |
| 59293 | 159 which additional arguments should be read. (default: ``None``) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
160 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
161 * formatter_class_ - A class for customizing the help output. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
162 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
163 * conflict_handler_ - Usually unnecessary, defines strategy for resolving |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
164 conflicting optionals. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
165 |
| 59293 | 166 * prog_ - The name of the program (default: |
|
72197
af04764ed7e4
Fix some markup and one typo
Éric Araujo <merwok@netwok.org>
parents:
71952
diff
changeset
|
167 ``sys.argv[0]``) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
168 |
| 59293 | 169 * usage_ - The string describing the program usage (default: generated) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
170 |
| 59293 | 171 The following sections describe how each of these are used. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
172 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
173 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
174 description |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
175 ^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
176 |
| 59293 | 177 Most calls to the :class:`ArgumentParser` constructor will use the |
| 178 ``description=`` keyword argument. This argument gives a brief description of | |
| 179 what the program does and how it works. In help messages, the description is | |
| 180 displayed between the command-line usage string and the help messages for the | |
| 181 various arguments:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
182 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
183 >>> parser = argparse.ArgumentParser(description='A foo that bars') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
184 >>> parser.print_help() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
185 usage: argparse.py [-h] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
186 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
187 A foo that bars |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
188 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
189 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
190 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
191 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
192 By default, the description will be line-wrapped so that it fits within the |
| 59269 | 193 given space. To change this behavior, see the formatter_class_ argument. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
194 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
195 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
196 epilog |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
197 ^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
198 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
199 Some programs like to display additional description of the program after the |
| 59269 | 200 description of the arguments. Such text can be specified using the ``epilog=`` |
| 201 argument to :class:`ArgumentParser`:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
202 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
203 >>> parser = argparse.ArgumentParser( |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
204 ... description='A foo that bars', |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
205 ... epilog="And that's how you'd foo a bar") |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
206 >>> parser.print_help() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
207 usage: argparse.py [-h] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
208 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
209 A foo that bars |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
210 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
211 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
212 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
213 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
214 And that's how you'd foo a bar |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
215 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
216 As with the description_ argument, the ``epilog=`` text is by default |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
217 line-wrapped, but this behavior can be adjusted with the formatter_class_ |
| 59293 | 218 argument to :class:`ArgumentParser`. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
219 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
220 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
221 add_help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
222 ^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
223 |
|
63691
23c089dc5cff
Merged revisions 83675 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents:
63482
diff
changeset
|
224 By default, ArgumentParser objects add an option which simply displays |
|
23c089dc5cff
Merged revisions 83675 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents:
63482
diff
changeset
|
225 the parser's help message. For example, consider a file named |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
226 ``myprogram.py`` containing the following code:: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
227 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
228 import argparse |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
229 parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
230 parser.add_argument('--foo', help='foo help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
231 args = parser.parse_args() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
232 |
|
69406
cc65cf9a9ce5
Fix a few hyphens in argparse.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
68987
diff
changeset
|
233 If ``-h`` or ``--help`` is supplied at the command line, the ArgumentParser |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
234 help will be printed:: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
235 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
236 $ python myprogram.py --help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
237 usage: myprogram.py [-h] [--foo FOO] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
238 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
239 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
240 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
241 --foo FOO foo help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
242 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
243 Occasionally, it may be useful to disable the addition of this help option. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
244 This can be achieved by passing ``False`` as the ``add_help=`` argument to |
| 59293 | 245 :class:`ArgumentParser`:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
246 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
247 >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
248 >>> parser.add_argument('--foo', help='foo help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
249 >>> parser.print_help() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
250 usage: PROG [--foo FOO] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
251 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
252 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
253 --foo FOO foo help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
254 |
|
63691
23c089dc5cff
Merged revisions 83675 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents:
63482
diff
changeset
|
255 The help option is typically ``-h/--help``. The exception to this is |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
256 if the ``prefix_chars=`` is specified and does not include ``-``, in |
|
63691
23c089dc5cff
Merged revisions 83675 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents:
63482
diff
changeset
|
257 which case ``-h`` and ``--help`` are not valid options. In |
|
23c089dc5cff
Merged revisions 83675 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents:
63482
diff
changeset
|
258 this case, the first character in ``prefix_chars`` is used to prefix |
|
23c089dc5cff
Merged revisions 83675 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents:
63482
diff
changeset
|
259 the help options:: |
|
23c089dc5cff
Merged revisions 83675 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents:
63482
diff
changeset
|
260 |
|
23c089dc5cff
Merged revisions 83675 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents:
63482
diff
changeset
|
261 >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/') |
|
23c089dc5cff
Merged revisions 83675 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents:
63482
diff
changeset
|
262 >>> parser.print_help() |
|
23c089dc5cff
Merged revisions 83675 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents:
63482
diff
changeset
|
263 usage: PROG [+h] |
|
23c089dc5cff
Merged revisions 83675 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents:
63482
diff
changeset
|
264 |
|
23c089dc5cff
Merged revisions 83675 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents:
63482
diff
changeset
|
265 optional arguments: |
|
23c089dc5cff
Merged revisions 83675 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents:
63482
diff
changeset
|
266 +h, ++help show this help message and exit |
|
23c089dc5cff
Merged revisions 83675 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents:
63482
diff
changeset
|
267 |
|
23c089dc5cff
Merged revisions 83675 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents:
63482
diff
changeset
|
268 |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
269 prefix_chars |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
270 ^^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
271 |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
272 Most command-line options will use ``-`` as the prefix, e.g. ``-f/--foo``. |
|
63691
23c089dc5cff
Merged revisions 83675 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents:
63482
diff
changeset
|
273 Parsers that need to support different or additional prefix |
|
23c089dc5cff
Merged revisions 83675 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents:
63482
diff
changeset
|
274 characters, e.g. for options |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
275 like ``+f`` or ``/foo``, may specify them using the ``prefix_chars=`` argument |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
276 to the ArgumentParser constructor:: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
277 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
278 >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
279 >>> parser.add_argument('+f') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
280 >>> parser.add_argument('++bar') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
281 >>> parser.parse_args('+f X ++bar Y'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
282 Namespace(bar='Y', f='X') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
283 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
284 The ``prefix_chars=`` argument defaults to ``'-'``. Supplying a set of |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
285 characters that does not include ``-`` will cause ``-f/--foo`` options to be |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
286 disallowed. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
287 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
288 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
289 fromfile_prefix_chars |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
290 ^^^^^^^^^^^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
291 |
| 59293 | 292 Sometimes, for example when dealing with a particularly long argument lists, it |
| 293 may make sense to keep the list of arguments in a file rather than typing it out | |
| 294 at the command line. If the ``fromfile_prefix_chars=`` argument is given to the | |
| 295 :class:`ArgumentParser` constructor, then arguments that start with any of the | |
| 296 specified characters will be treated as files, and will be replaced by the | |
| 297 arguments they contain. For example:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
298 |
| 59293 | 299 >>> with open('args.txt', 'w') as fp: |
| 300 ... fp.write('-f\nbar') | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
301 >>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
302 >>> parser.add_argument('-f') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
303 >>> parser.parse_args(['-f', 'foo', '@args.txt']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
304 Namespace(f='bar') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
305 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
306 Arguments read from a file must by default be one per line (but see also |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
307 :meth:`~ArgumentParser.convert_arg_line_to_args`) and are treated as if they |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
308 were in the same place as the original file referencing argument on the command |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
309 line. So in the example above, the expression ``['-f', 'foo', '@args.txt']`` |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
310 is considered equivalent to the expression ``['-f', 'foo', '-f', 'bar']``. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
311 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
312 The ``fromfile_prefix_chars=`` argument defaults to ``None``, meaning that |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
313 arguments will never be treated as file references. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
314 |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
315 |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
316 argument_default |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
317 ^^^^^^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
318 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
319 Generally, argument defaults are specified either by passing a default to |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
320 :meth:`~ArgumentParser.add_argument` or by calling the |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
321 :meth:`~ArgumentParser.set_defaults` methods with a specific set of name-value |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
322 pairs. Sometimes however, it may be useful to specify a single parser-wide |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
323 default for arguments. This can be accomplished by passing the |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
324 ``argument_default=`` keyword argument to :class:`ArgumentParser`. For example, |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
325 to globally suppress attribute creation on :meth:`~ArgumentParser.parse_args` |
| 59293 | 326 calls, we supply ``argument_default=SUPPRESS``:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
327 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
328 >>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
329 >>> parser.add_argument('--foo') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
330 >>> parser.add_argument('bar', nargs='?') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
331 >>> parser.parse_args(['--foo', '1', 'BAR']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
332 Namespace(bar='BAR', foo='1') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
333 >>> parser.parse_args([]) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
334 Namespace() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
335 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
336 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
337 parents |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
338 ^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
339 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
340 Sometimes, several parsers share a common set of arguments. Rather than |
| 59293 | 341 repeating the definitions of these arguments, a single parser with all the |
| 342 shared arguments and passed to ``parents=`` argument to :class:`ArgumentParser` | |
| 343 can be used. The ``parents=`` argument takes a list of :class:`ArgumentParser` | |
| 344 objects, collects all the positional and optional actions from them, and adds | |
| 345 these actions to the :class:`ArgumentParser` object being constructed:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
346 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
347 >>> parent_parser = argparse.ArgumentParser(add_help=False) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
348 >>> parent_parser.add_argument('--parent', type=int) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
349 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
350 >>> foo_parser = argparse.ArgumentParser(parents=[parent_parser]) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
351 >>> foo_parser.add_argument('foo') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
352 >>> foo_parser.parse_args(['--parent', '2', 'XXX']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
353 Namespace(foo='XXX', parent=2) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
354 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
355 >>> bar_parser = argparse.ArgumentParser(parents=[parent_parser]) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
356 >>> bar_parser.add_argument('--bar') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
357 >>> bar_parser.parse_args(['--bar', 'YYY']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
358 Namespace(bar='YYY', parent=None) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
359 |
| 59269 | 360 Note that most parent parsers will specify ``add_help=False``. Otherwise, the |
| 59293 | 361 :class:`ArgumentParser` will see two ``-h/--help`` options (one in the parent |
| 362 and one in the child) and raise an error. | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
363 |
|
68987
15e98607555d
Issue #9343: Document that argparse parent parsers must be configured before their children. (Merge from 3.2.)
Steven Bethard <steven.bethard@gmail.com>
parents:
68979
diff
changeset
|
364 .. note:: |
|
15e98607555d
Issue #9343: Document that argparse parent parsers must be configured before their children. (Merge from 3.2.)
Steven Bethard <steven.bethard@gmail.com>
parents:
68979
diff
changeset
|
365 You must fully initialize the parsers before passing them via ``parents=``. |
|
15e98607555d
Issue #9343: Document that argparse parent parsers must be configured before their children. (Merge from 3.2.)
Steven Bethard <steven.bethard@gmail.com>
parents:
68979
diff
changeset
|
366 If you change the parent parsers after the child parser, those changes will |
|
15e98607555d
Issue #9343: Document that argparse parent parsers must be configured before their children. (Merge from 3.2.)
Steven Bethard <steven.bethard@gmail.com>
parents:
68979
diff
changeset
|
367 not be reflected in the child. |
|
15e98607555d
Issue #9343: Document that argparse parent parsers must be configured before their children. (Merge from 3.2.)
Steven Bethard <steven.bethard@gmail.com>
parents:
68979
diff
changeset
|
368 |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
369 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
370 formatter_class |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
371 ^^^^^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
372 |
| 59293 | 373 :class:`ArgumentParser` objects allow the help formatting to be customized by |
| 374 specifying an alternate formatting class. Currently, there are three such | |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
375 classes: |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
376 |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
377 .. class:: RawDescriptionHelpFormatter |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
378 RawTextHelpFormatter |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
379 ArgumentDefaultsHelpFormatter |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
380 |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
381 The first two allow more control over how textual descriptions are displayed, |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
382 while the last automatically adds information about argument default values. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
383 |
| 59293 | 384 By default, :class:`ArgumentParser` objects line-wrap the description_ and |
| 385 epilog_ texts in command-line help messages:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
386 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
387 >>> parser = argparse.ArgumentParser( |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
388 ... prog='PROG', |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
389 ... description='''this description |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
390 ... was indented weird |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
391 ... but that is okay''', |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
392 ... epilog=''' |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
393 ... likewise for this epilog whose whitespace will |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
394 ... be cleaned up and whose words will be wrapped |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
395 ... across a couple lines''') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
396 >>> parser.print_help() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
397 usage: PROG [-h] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
398 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
399 this description was indented weird but that is okay |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
400 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
401 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
402 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
403 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
404 likewise for this epilog whose whitespace will be cleaned up and whose words |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
405 will be wrapped across a couple lines |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
406 |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
407 Passing :class:`RawDescriptionHelpFormatter` as ``formatter_class=`` |
|
59294
38cef8deae22
fix Sphinx warnings
Benjamin Peterson <benjamin@python.org>
parents:
59293
diff
changeset
|
408 indicates that description_ and epilog_ are already correctly formatted and |
| 59293 | 409 should not be line-wrapped:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
410 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
411 >>> parser = argparse.ArgumentParser( |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
412 ... prog='PROG', |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
413 ... formatter_class=argparse.RawDescriptionHelpFormatter, |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
414 ... description=textwrap.dedent('''\ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
415 ... Please do not mess up this text! |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
416 ... -------------------------------- |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
417 ... I have indented it |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
418 ... exactly the way |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
419 ... I want it |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
420 ... ''')) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
421 >>> parser.print_help() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
422 usage: PROG [-h] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
423 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
424 Please do not mess up this text! |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
425 -------------------------------- |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
426 I have indented it |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
427 exactly the way |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
428 I want it |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
429 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
430 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
431 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
432 |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
433 :class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text, |
| 59293 | 434 including argument descriptions. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
435 |
| 59293 | 436 The other formatter class available, :class:`ArgumentDefaultsHelpFormatter`, |
| 59269 | 437 will add information about the default value of each of the arguments:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
438 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
439 >>> parser = argparse.ArgumentParser( |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
440 ... prog='PROG', |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
441 ... formatter_class=argparse.ArgumentDefaultsHelpFormatter) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
442 >>> parser.add_argument('--foo', type=int, default=42, help='FOO!') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
443 >>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
444 >>> parser.print_help() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
445 usage: PROG [-h] [--foo FOO] [bar [bar ...]] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
446 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
447 positional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
448 bar BAR! (default: [1, 2, 3]) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
449 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
450 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
451 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
452 --foo FOO FOO! (default: 42) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
453 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
454 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
455 conflict_handler |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
456 ^^^^^^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
457 |
| 59293 | 458 :class:`ArgumentParser` objects do not allow two actions with the same option |
| 459 string. By default, :class:`ArgumentParser` objects raises an exception if an | |
| 460 attempt is made to create an argument with an option string that is already in | |
| 461 use:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
462 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
463 >>> parser = argparse.ArgumentParser(prog='PROG') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
464 >>> parser.add_argument('-f', '--foo', help='old foo help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
465 >>> parser.add_argument('--foo', help='new foo help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
466 Traceback (most recent call last): |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
467 .. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
468 ArgumentError: argument --foo: conflicting option string(s): --foo |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
469 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
470 Sometimes (e.g. when using parents_) it may be useful to simply override any |
| 59269 | 471 older arguments with the same option string. To get this behavior, the value |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
472 ``'resolve'`` can be supplied to the ``conflict_handler=`` argument of |
| 59293 | 473 :class:`ArgumentParser`:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
474 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
475 >>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
476 >>> parser.add_argument('-f', '--foo', help='old foo help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
477 >>> parser.add_argument('--foo', help='new foo help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
478 >>> parser.print_help() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
479 usage: PROG [-h] [-f FOO] [--foo FOO] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
480 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
481 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
482 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
483 -f FOO old foo help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
484 --foo FOO new foo help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
485 |
| 59293 | 486 Note that :class:`ArgumentParser` objects only remove an action if all of its |
| 487 option strings are overridden. So, in the example above, the old ``-f/--foo`` | |
| 488 action is retained as the ``-f`` action, because only the ``--foo`` option | |
| 489 string was overridden. | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
490 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
491 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
492 prog |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
493 ^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
494 |
| 59293 | 495 By default, :class:`ArgumentParser` objects uses ``sys.argv[0]`` to determine |
| 496 how to display the name of the program in help messages. This default is almost | |
|
61715
75d7396556fd
Fix typo in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
60941
diff
changeset
|
497 always desirable because it will make the help messages match how the program was |
| 59293 | 498 invoked on the command line. For example, consider a file named |
| 499 ``myprogram.py`` with the following code:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
500 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
501 import argparse |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
502 parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
503 parser.add_argument('--foo', help='foo help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
504 args = parser.parse_args() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
505 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
506 The help for this program will display ``myprogram.py`` as the program name |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
507 (regardless of where the program was invoked from):: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
508 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
509 $ python myprogram.py --help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
510 usage: myprogram.py [-h] [--foo FOO] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
511 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
512 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
513 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
514 --foo FOO foo help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
515 $ cd .. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
516 $ python subdir\myprogram.py --help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
517 usage: myprogram.py [-h] [--foo FOO] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
518 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
519 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
520 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
521 --foo FOO foo help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
522 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
523 To change this default behavior, another value can be supplied using the |
| 59293 | 524 ``prog=`` argument to :class:`ArgumentParser`:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
525 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
526 >>> parser = argparse.ArgumentParser(prog='myprogram') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
527 >>> parser.print_help() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
528 usage: myprogram [-h] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
529 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
530 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
531 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
532 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
533 Note that the program name, whether determined from ``sys.argv[0]`` or from the |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
534 ``prog=`` argument, is available to help messages using the ``%(prog)s`` format |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
535 specifier. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
536 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
537 :: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
538 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
539 >>> parser = argparse.ArgumentParser(prog='myprogram') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
540 >>> parser.add_argument('--foo', help='foo of the %(prog)s program') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
541 >>> parser.print_help() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
542 usage: myprogram [-h] [--foo FOO] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
543 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
544 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
545 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
546 --foo FOO foo of the myprogram program |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
547 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
548 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
549 usage |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
550 ^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
551 |
| 59293 | 552 By default, :class:`ArgumentParser` calculates the usage message from the |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
553 arguments it contains:: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
554 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
555 >>> parser = argparse.ArgumentParser(prog='PROG') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
556 >>> parser.add_argument('--foo', nargs='?', help='foo help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
557 >>> parser.add_argument('bar', nargs='+', help='bar help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
558 >>> parser.print_help() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
559 usage: PROG [-h] [--foo [FOO]] bar [bar ...] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
560 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
561 positional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
562 bar bar help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
563 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
564 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
565 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
566 --foo [FOO] foo help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
567 |
| 59293 | 568 The default message can be overridden with the ``usage=`` keyword argument:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
569 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
570 >>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
571 >>> parser.add_argument('--foo', nargs='?', help='foo help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
572 >>> parser.add_argument('bar', nargs='+', help='bar help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
573 >>> parser.print_help() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
574 usage: PROG [options] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
575 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
576 positional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
577 bar bar help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
578 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
579 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
580 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
581 --foo [FOO] foo help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
582 |
| 59293 | 583 The ``%(prog)s`` format specifier is available to fill in the program name in |
| 584 your usage messages. | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
585 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
586 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
587 The add_argument() method |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
588 ------------------------- |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
589 |
|
75053
7ff4731853e2
Add missing “::” markup and wrap overlong lines
Éric Araujo <merwok@netwok.org>
parents:
74529
diff
changeset
|
590 .. method:: ArgumentParser.add_argument(name or flags..., [action], [nargs], \ |
|
7ff4731853e2
Add missing “::” markup and wrap overlong lines
Éric Araujo <merwok@netwok.org>
parents:
74529
diff
changeset
|
591 [const], [default], [type], [choices], [required], \ |
|
7ff4731853e2
Add missing “::” markup and wrap overlong lines
Éric Araujo <merwok@netwok.org>
parents:
74529
diff
changeset
|
592 [help], [metavar], [dest]) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
593 |
|
69406
cc65cf9a9ce5
Fix a few hyphens in argparse.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
68987
diff
changeset
|
594 Define how a single command-line argument should be parsed. Each parameter |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
595 has its own more detailed description below, but in short they are: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
596 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
597 * `name or flags`_ - Either a name or a list of option strings, e.g. ``foo`` |
|
69520
f6ea7abc4eb2
#11905: fix missing full stop in argparse doc. Noticed by Vladimir Rutsky.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69519
diff
changeset
|
598 or ``-f, --foo``. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
599 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
600 * action_ - The basic type of action to be taken when this argument is |
|
69406
cc65cf9a9ce5
Fix a few hyphens in argparse.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
68987
diff
changeset
|
601 encountered at the command line. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
602 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
603 * nargs_ - The number of command-line arguments that should be consumed. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
604 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
605 * const_ - A constant value required by some action_ and nargs_ selections. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
606 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
607 * default_ - The value produced if the argument is absent from the |
|
69406
cc65cf9a9ce5
Fix a few hyphens in argparse.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
68987
diff
changeset
|
608 command line. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
609 |
|
69406
cc65cf9a9ce5
Fix a few hyphens in argparse.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
68987
diff
changeset
|
610 * type_ - The type to which the command-line argument should be converted. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
611 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
612 * choices_ - A container of the allowable values for the argument. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
613 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
614 * required_ - Whether or not the command-line option may be omitted |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
615 (optionals only). |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
616 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
617 * help_ - A brief description of what the argument does. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
618 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
619 * metavar_ - A name for the argument in usage messages. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
620 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
621 * dest_ - The name of the attribute to be added to the object returned by |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
622 :meth:`parse_args`. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
623 |
| 59293 | 624 The following sections describe how each of these are used. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
625 |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
626 |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
627 name or flags |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
628 ^^^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
629 |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
630 The :meth:`~ArgumentParser.add_argument` method must know whether an optional |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
631 argument, like ``-f`` or ``--foo``, or a positional argument, like a list of |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
632 filenames, is expected. The first arguments passed to |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
633 :meth:`~ArgumentParser.add_argument` must therefore be either a series of |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
634 flags, or a simple argument name. For example, an optional argument could |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
635 be created like:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
636 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
637 >>> parser.add_argument('-f', '--foo') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
638 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
639 while a positional argument could be created like:: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
640 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
641 >>> parser.add_argument('bar') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
642 |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
643 When :meth:`~ArgumentParser.parse_args` is called, optional arguments will be |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
644 identified by the ``-`` prefix, and the remaining arguments will be assumed to |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
645 be positional:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
646 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
647 >>> parser = argparse.ArgumentParser(prog='PROG') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
648 >>> parser.add_argument('-f', '--foo') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
649 >>> parser.add_argument('bar') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
650 >>> parser.parse_args(['BAR']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
651 Namespace(bar='BAR', foo=None) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
652 >>> parser.parse_args(['BAR', '--foo', 'FOO']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
653 Namespace(bar='BAR', foo='FOO') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
654 >>> parser.parse_args(['--foo', 'FOO']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
655 usage: PROG [-h] [-f FOO] bar |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
656 PROG: error: too few arguments |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
657 |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
658 |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
659 action |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
660 ^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
661 |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
662 :class:`ArgumentParser` objects associate command-line arguments with actions. These |
|
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
663 actions can do just about anything with the command-line arguments associated with |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
664 them, though most actions simply add an attribute to the object returned by |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
665 :meth:`~ArgumentParser.parse_args`. The ``action`` keyword argument specifies |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
666 how the command-line arguments should be handled. The supported actions are: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
667 |
| 59269 | 668 * ``'store'`` - This just stores the argument's value. This is the default |
|
69519
79f3ae389dae
#11904: fix indentation in argparse doc. Noticed by Vladimir Rutsky.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69516
diff
changeset
|
669 action. For example:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
670 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
671 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
672 >>> parser.add_argument('--foo') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
673 >>> parser.parse_args('--foo 1'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
674 Namespace(foo='1') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
675 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
676 * ``'store_const'`` - This stores the value specified by the const_ keyword |
|
69519
79f3ae389dae
#11904: fix indentation in argparse doc. Noticed by Vladimir Rutsky.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69516
diff
changeset
|
677 argument. (Note that the const_ keyword argument defaults to the rather |
|
79f3ae389dae
#11904: fix indentation in argparse doc. Noticed by Vladimir Rutsky.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69516
diff
changeset
|
678 unhelpful ``None``.) The ``'store_const'`` action is most commonly used with |
|
79f3ae389dae
#11904: fix indentation in argparse doc. Noticed by Vladimir Rutsky.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69516
diff
changeset
|
679 optional arguments that specify some sort of flag. For example:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
680 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
681 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
682 >>> parser.add_argument('--foo', action='store_const', const=42) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
683 >>> parser.parse_args('--foo'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
684 Namespace(foo=42) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
685 |
|
73628
49677cc6d83a
Note the store_true and store_false also create the appropriate defaults.
Raymond Hettinger <python@rcn.com>
parents:
73498
diff
changeset
|
686 * ``'store_true'`` and ``'store_false'`` - These are special cases of |
|
49677cc6d83a
Note the store_true and store_false also create the appropriate defaults.
Raymond Hettinger <python@rcn.com>
parents:
73498
diff
changeset
|
687 ``'store_const'`` using for storing the values ``True`` and ``False`` |
|
49677cc6d83a
Note the store_true and store_false also create the appropriate defaults.
Raymond Hettinger <python@rcn.com>
parents:
73498
diff
changeset
|
688 respectively. In addition, they create default values of *False* and *True* |
|
49677cc6d83a
Note the store_true and store_false also create the appropriate defaults.
Raymond Hettinger <python@rcn.com>
parents:
73498
diff
changeset
|
689 respectively. For example:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
690 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
691 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
692 >>> parser.add_argument('--foo', action='store_true') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
693 >>> parser.add_argument('--bar', action='store_false') |
|
73628
49677cc6d83a
Note the store_true and store_false also create the appropriate defaults.
Raymond Hettinger <python@rcn.com>
parents:
73498
diff
changeset
|
694 >>> parser.add_argument('--baz', action='store_false') |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
695 >>> parser.parse_args('--foo --bar'.split()) |
|
73628
49677cc6d83a
Note the store_true and store_false also create the appropriate defaults.
Raymond Hettinger <python@rcn.com>
parents:
73498
diff
changeset
|
696 Namespace(bar=False, baz=True, foo=True) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
697 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
698 * ``'append'`` - This stores a list, and appends each argument value to the |
| 59293 | 699 list. This is useful to allow an option to be specified multiple times. |
| 700 Example usage:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
701 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
702 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
703 >>> parser.add_argument('--foo', action='append') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
704 >>> parser.parse_args('--foo 1 --foo 2'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
705 Namespace(foo=['1', '2']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
706 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
707 * ``'append_const'`` - This stores a list, and appends the value specified by |
| 59293 | 708 the const_ keyword argument to the list. (Note that the const_ keyword |
| 709 argument defaults to ``None``.) The ``'append_const'`` action is typically | |
| 710 useful when multiple arguments need to store constants to the same list. For | |
| 711 example:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
712 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
713 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
714 >>> parser.add_argument('--str', dest='types', action='append_const', const=str) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
715 >>> parser.add_argument('--int', dest='types', action='append_const', const=int) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
716 >>> parser.parse_args('--str --int'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
717 Namespace(types=[<type 'str'>, <type 'int'>]) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
718 |
|
74272
278fbd7b9608
Issue #10772: add count and help argparse action; patch by Marc Sibson
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74243
diff
changeset
|
719 * ``'count'`` - This counts the number of times a keyword argument occurs. For |
|
278fbd7b9608
Issue #10772: add count and help argparse action; patch by Marc Sibson
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74243
diff
changeset
|
720 example, this is useful for increasing verbosity levels:: |
|
278fbd7b9608
Issue #10772: add count and help argparse action; patch by Marc Sibson
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74243
diff
changeset
|
721 |
|
278fbd7b9608
Issue #10772: add count and help argparse action; patch by Marc Sibson
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74243
diff
changeset
|
722 >>> parser = argparse.ArgumentParser() |
|
278fbd7b9608
Issue #10772: add count and help argparse action; patch by Marc Sibson
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74243
diff
changeset
|
723 >>> parser.add_argument('--verbose', '-v', action='count') |
|
278fbd7b9608
Issue #10772: add count and help argparse action; patch by Marc Sibson
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74243
diff
changeset
|
724 >>> parser.parse_args('-vvv'.split()) |
|
278fbd7b9608
Issue #10772: add count and help argparse action; patch by Marc Sibson
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74243
diff
changeset
|
725 Namespace(verbose=3) |
|
278fbd7b9608
Issue #10772: add count and help argparse action; patch by Marc Sibson
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74243
diff
changeset
|
726 |
|
278fbd7b9608
Issue #10772: add count and help argparse action; patch by Marc Sibson
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74243
diff
changeset
|
727 * ``'help'`` - This prints a complete help message for all the options in the |
|
278fbd7b9608
Issue #10772: add count and help argparse action; patch by Marc Sibson
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74243
diff
changeset
|
728 current parser and then exits. By default a help action is automatically |
|
278fbd7b9608
Issue #10772: add count and help argparse action; patch by Marc Sibson
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74243
diff
changeset
|
729 added to the parser. See :class:`ArgumentParser` for details of how the |
|
278fbd7b9608
Issue #10772: add count and help argparse action; patch by Marc Sibson
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74243
diff
changeset
|
730 output is created. |
|
278fbd7b9608
Issue #10772: add count and help argparse action; patch by Marc Sibson
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74243
diff
changeset
|
731 |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
732 * ``'version'`` - This expects a ``version=`` keyword argument in the |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
733 :meth:`~ArgumentParser.add_argument` call, and prints version information |
|
75053
7ff4731853e2
Add missing “::” markup and wrap overlong lines
Éric Araujo <merwok@netwok.org>
parents:
74529
diff
changeset
|
734 and exits when invoked:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
735 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
736 >>> import argparse |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
737 >>> parser = argparse.ArgumentParser(prog='PROG') |
|
61877
40cad759a355
argparse documentation updates (including updates to optparse and getopt documentation that were promised in the PEP)
Steven Bethard <steven.bethard@gmail.com>
parents:
61715
diff
changeset
|
738 >>> parser.add_argument('--version', action='version', version='%(prog)s 2.0') |
|
40cad759a355
argparse documentation updates (including updates to optparse and getopt documentation that were promised in the PEP)
Steven Bethard <steven.bethard@gmail.com>
parents:
61715
diff
changeset
|
739 >>> parser.parse_args(['--version']) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
740 PROG 2.0 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
741 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
742 You can also specify an arbitrary action by passing an object that implements |
| 59293 | 743 the Action API. The easiest way to do this is to extend |
| 744 :class:`argparse.Action`, supplying an appropriate ``__call__`` method. The | |
| 745 ``__call__`` method should accept four parameters: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
746 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
747 * ``parser`` - The ArgumentParser object which contains this action. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
748 |
|
71606
01722022f88d
Add a link target for argparse.Namespace (#8982)
Éric Araujo <merwok@netwok.org>
parents:
69525
diff
changeset
|
749 * ``namespace`` - The :class:`Namespace` object that will be returned by |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
750 :meth:`~ArgumentParser.parse_args`. Most actions add an attribute to this |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
751 object. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
752 |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
753 * ``values`` - The associated command-line arguments, with any type conversions |
|
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
754 applied. (Type conversions are specified with the type_ keyword argument to |
|
78515
a13f99dc91b3
add missing parenthesis to 'action' argparse doc; thanks to kishkin from docs@
Sandro Tosi <sandro.tosi@gmail.com>
parents:
76791
diff
changeset
|
755 :meth:`~ArgumentParser.add_argument`.) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
756 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
757 * ``option_string`` - The option string that was used to invoke this action. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
758 The ``option_string`` argument is optional, and will be absent if the action |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
759 is associated with a positional argument. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
760 |
| 59293 | 761 An example of a custom action:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
762 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
763 >>> class FooAction(argparse.Action): |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
764 ... def __call__(self, parser, namespace, values, option_string=None): |
|
63482
198b2cd3a6d1
Merged revisions 83160-83161,83166,83168-83169,83171 via svnmerge from
Georg Brandl <georg@python.org>
parents:
62723
diff
changeset
|
765 ... print '%r %r %r' % (namespace, values, option_string) |
|
198b2cd3a6d1
Merged revisions 83160-83161,83166,83168-83169,83171 via svnmerge from
Georg Brandl <georg@python.org>
parents:
62723
diff
changeset
|
766 ... setattr(namespace, self.dest, values) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
767 ... |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
768 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
769 >>> parser.add_argument('--foo', action=FooAction) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
770 >>> parser.add_argument('bar', action=FooAction) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
771 >>> args = parser.parse_args('1 --foo 2'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
772 Namespace(bar=None, foo=None) '1' None |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
773 Namespace(bar='1', foo=None) '2' '--foo' |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
774 >>> args |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
775 Namespace(bar='1', foo='2') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
776 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
777 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
778 nargs |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
779 ^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
780 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
781 ArgumentParser objects usually associate a single command-line argument with a |
| 59293 | 782 single action to be taken. The ``nargs`` keyword argument associates a |
|
69516
e8464256b4d7
#11902: Fix typo in argparse doc. Noticed by Vladimir Rutsky.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69512
diff
changeset
|
783 different number of command-line arguments with a single action. The supported |
| 59293 | 784 values are: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
785 |
|
75053
7ff4731853e2
Add missing “::” markup and wrap overlong lines
Éric Araujo <merwok@netwok.org>
parents:
74529
diff
changeset
|
786 * ``N`` (an integer). ``N`` arguments from the command line will be gathered |
|
7ff4731853e2
Add missing “::” markup and wrap overlong lines
Éric Araujo <merwok@netwok.org>
parents:
74529
diff
changeset
|
787 together into a list. For example:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
788 |
|
65144
7018261f2ac1
Merged revisions 85274 via svnmerge from
Georg Brandl <georg@python.org>
parents:
63691
diff
changeset
|
789 >>> parser = argparse.ArgumentParser() |
|
7018261f2ac1
Merged revisions 85274 via svnmerge from
Georg Brandl <georg@python.org>
parents:
63691
diff
changeset
|
790 >>> parser.add_argument('--foo', nargs=2) |
|
7018261f2ac1
Merged revisions 85274 via svnmerge from
Georg Brandl <georg@python.org>
parents:
63691
diff
changeset
|
791 >>> parser.add_argument('bar', nargs=1) |
|
7018261f2ac1
Merged revisions 85274 via svnmerge from
Georg Brandl <georg@python.org>
parents:
63691
diff
changeset
|
792 >>> parser.parse_args('c --foo a b'.split()) |
|
7018261f2ac1
Merged revisions 85274 via svnmerge from
Georg Brandl <georg@python.org>
parents:
63691
diff
changeset
|
793 Namespace(bar=['c'], foo=['a', 'b']) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
794 |
|
65144
7018261f2ac1
Merged revisions 85274 via svnmerge from
Georg Brandl <georg@python.org>
parents:
63691
diff
changeset
|
795 Note that ``nargs=1`` produces a list of one item. This is different from |
|
7018261f2ac1
Merged revisions 85274 via svnmerge from
Georg Brandl <georg@python.org>
parents:
63691
diff
changeset
|
796 the default, in which the item is produced by itself. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
797 |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
798 * ``'?'``. One argument will be consumed from the command line if possible, and |
|
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
799 produced as a single item. If no command-line argument is present, the value from |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
800 default_ will be produced. Note that for optional arguments, there is an |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
801 additional case - the option string is present but not followed by a |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
802 command-line argument. In this case the value from const_ will be produced. Some |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
803 examples to illustrate this:: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
804 |
| 59269 | 805 >>> parser = argparse.ArgumentParser() |
| 806 >>> parser.add_argument('--foo', nargs='?', const='c', default='d') | |
| 807 >>> parser.add_argument('bar', nargs='?', default='d') | |
| 808 >>> parser.parse_args('XX --foo YY'.split()) | |
| 809 Namespace(bar='XX', foo='YY') | |
| 810 >>> parser.parse_args('XX --foo'.split()) | |
| 811 Namespace(bar='XX', foo='c') | |
| 812 >>> parser.parse_args(''.split()) | |
| 813 Namespace(bar='d', foo='d') | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
814 |
| 59269 | 815 One of the more common uses of ``nargs='?'`` is to allow optional input and |
| 816 output files:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
817 |
| 59269 | 818 >>> parser = argparse.ArgumentParser() |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
819 >>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'), |
|
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
820 ... default=sys.stdin) |
|
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
821 >>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'), |
|
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
822 ... default=sys.stdout) |
| 59269 | 823 >>> parser.parse_args(['input.txt', 'output.txt']) |
|
67495
681d0542bbbd
Merged revisions 87890 via svnmerge from
Georg Brandl <georg@python.org>
parents:
66457
diff
changeset
|
824 Namespace(infile=<open file 'input.txt', mode 'r' at 0x...>, |
|
681d0542bbbd
Merged revisions 87890 via svnmerge from
Georg Brandl <georg@python.org>
parents:
66457
diff
changeset
|
825 outfile=<open file 'output.txt', mode 'w' at 0x...>) |
| 59269 | 826 >>> parser.parse_args([]) |
|
67495
681d0542bbbd
Merged revisions 87890 via svnmerge from
Georg Brandl <georg@python.org>
parents:
66457
diff
changeset
|
827 Namespace(infile=<open file '<stdin>', mode 'r' at 0x...>, |
|
681d0542bbbd
Merged revisions 87890 via svnmerge from
Georg Brandl <georg@python.org>
parents:
66457
diff
changeset
|
828 outfile=<open file '<stdout>', mode 'w' at 0x...>) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
829 |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
830 * ``'*'``. All command-line arguments present are gathered into a list. Note that |
| 59269 | 831 it generally doesn't make much sense to have more than one positional argument |
| 832 with ``nargs='*'``, but multiple optional arguments with ``nargs='*'`` is | |
| 833 possible. For example:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
834 |
| 59269 | 835 >>> parser = argparse.ArgumentParser() |
| 836 >>> parser.add_argument('--foo', nargs='*') | |
| 837 >>> parser.add_argument('--bar', nargs='*') | |
| 838 >>> parser.add_argument('baz', nargs='*') | |
| 839 >>> parser.parse_args('a b --foo x y --bar 1 2'.split()) | |
| 840 Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y']) | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
841 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
842 * ``'+'``. Just like ``'*'``, all command-line args present are gathered into a |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
843 list. Additionally, an error message will be generated if there wasn't at |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
844 least one command-line argument present. For example:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
845 |
| 59269 | 846 >>> parser = argparse.ArgumentParser(prog='PROG') |
| 847 >>> parser.add_argument('foo', nargs='+') | |
| 848 >>> parser.parse_args('a b'.split()) | |
| 849 Namespace(foo=['a', 'b']) | |
| 850 >>> parser.parse_args(''.split()) | |
| 851 usage: PROG [-h] foo [foo ...] | |
| 852 PROG: error: too few arguments | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
853 |
|
74529
1b481e76cd16
Issue #13605: more meaningful example + fixes
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74526
diff
changeset
|
854 * ``argparse.REMAINDER``. All the remaining command-line arguments are gathered |
|
1b481e76cd16
Issue #13605: more meaningful example + fixes
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74526
diff
changeset
|
855 into a list. This is commonly useful for command line utilities that dispatch |
|
75053
7ff4731853e2
Add missing “::” markup and wrap overlong lines
Éric Araujo <merwok@netwok.org>
parents:
74529
diff
changeset
|
856 to other command line utilities:: |
|
74526
35665f6f3674
Issue #13605: add documentation for nargs=argparse.REMAINDER
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74272
diff
changeset
|
857 |
|
35665f6f3674
Issue #13605: add documentation for nargs=argparse.REMAINDER
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74272
diff
changeset
|
858 >>> parser = argparse.ArgumentParser(prog='PROG') |
|
35665f6f3674
Issue #13605: add documentation for nargs=argparse.REMAINDER
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74272
diff
changeset
|
859 >>> parser.add_argument('--foo') |
|
35665f6f3674
Issue #13605: add documentation for nargs=argparse.REMAINDER
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74272
diff
changeset
|
860 >>> parser.add_argument('command') |
|
35665f6f3674
Issue #13605: add documentation for nargs=argparse.REMAINDER
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74272
diff
changeset
|
861 >>> parser.add_argument('args', nargs=argparse.REMAINDER) |
|
74529
1b481e76cd16
Issue #13605: more meaningful example + fixes
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74526
diff
changeset
|
862 >>> print parser.parse_args('--foo B cmd --arg1 XX ZZ'.split()) |
|
1b481e76cd16
Issue #13605: more meaningful example + fixes
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74526
diff
changeset
|
863 Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B') |
|
74526
35665f6f3674
Issue #13605: add documentation for nargs=argparse.REMAINDER
Sandro Tosi <sandro.tosi@gmail.com>
parents:
74272
diff
changeset
|
864 |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
865 If the ``nargs`` keyword argument is not provided, the number of arguments consumed |
|
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
866 is determined by the action_. Generally this means a single command-line argument |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
867 will be consumed and a single item (not a list) will be produced. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
868 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
869 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
870 const |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
871 ^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
872 |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
873 The ``const`` argument of :meth:`~ArgumentParser.add_argument` is used to hold |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
874 constant values that are not read from the command line but are required for |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
875 the various :class:`ArgumentParser` actions. The two most common uses of it are: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
876 |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
877 * When :meth:`~ArgumentParser.add_argument` is called with |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
878 ``action='store_const'`` or ``action='append_const'``. These actions add the |
|
75053
7ff4731853e2
Add missing “::” markup and wrap overlong lines
Éric Araujo <merwok@netwok.org>
parents:
74529
diff
changeset
|
879 ``const`` value to one of the attributes of the object returned by |
|
7ff4731853e2
Add missing “::” markup and wrap overlong lines
Éric Araujo <merwok@netwok.org>
parents:
74529
diff
changeset
|
880 :meth:`~ArgumentParser.parse_args`. See the action_ description for examples. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
881 |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
882 * When :meth:`~ArgumentParser.add_argument` is called with option strings |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
883 (like ``-f`` or ``--foo``) and ``nargs='?'``. This creates an optional |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
884 argument that can be followed by zero or one command-line arguments. |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
885 When parsing the command line, if the option string is encountered with no |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
886 command-line argument following it, the value of ``const`` will be assumed instead. |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
887 See the nargs_ description for examples. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
888 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
889 The ``const`` keyword argument defaults to ``None``. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
890 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
891 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
892 default |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
893 ^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
894 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
895 All optional arguments and some positional arguments may be omitted at the |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
896 command line. The ``default`` keyword argument of |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
897 :meth:`~ArgumentParser.add_argument`, whose value defaults to ``None``, |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
898 specifies what value should be used if the command-line argument is not present. |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
899 For optional arguments, the ``default`` value is used when the option string |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
900 was not present at the command line:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
901 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
902 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
903 >>> parser.add_argument('--foo', default=42) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
904 >>> parser.parse_args('--foo 2'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
905 Namespace(foo='2') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
906 >>> parser.parse_args(''.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
907 Namespace(foo=42) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
908 |
|
79165
b624059a8dac
- Issue #15935: Clarification of argparse docs, re: add_argument() type and
Barry Warsaw <barry@python.org>
parents:
79025
diff
changeset
|
909 If the ``default`` value is a string, the parser parses the value as if it |
|
b624059a8dac
- Issue #15935: Clarification of argparse docs, re: add_argument() type and
Barry Warsaw <barry@python.org>
parents:
79025
diff
changeset
|
910 were a command-line argument. In particular, the parser applies any type_ |
|
b624059a8dac
- Issue #15935: Clarification of argparse docs, re: add_argument() type and
Barry Warsaw <barry@python.org>
parents:
79025
diff
changeset
|
911 conversion argument, if provided, before setting the attribute on the |
|
b624059a8dac
- Issue #15935: Clarification of argparse docs, re: add_argument() type and
Barry Warsaw <barry@python.org>
parents:
79025
diff
changeset
|
912 :class:`Namespace` return value. Otherwise, the parser uses the value as is:: |
|
b624059a8dac
- Issue #15935: Clarification of argparse docs, re: add_argument() type and
Barry Warsaw <barry@python.org>
parents:
79025
diff
changeset
|
913 |
|
b624059a8dac
- Issue #15935: Clarification of argparse docs, re: add_argument() type and
Barry Warsaw <barry@python.org>
parents:
79025
diff
changeset
|
914 >>> parser = argparse.ArgumentParser() |
|
b624059a8dac
- Issue #15935: Clarification of argparse docs, re: add_argument() type and
Barry Warsaw <barry@python.org>
parents:
79025
diff
changeset
|
915 >>> parser.add_argument('--length', default='10', type=int) |
|
b624059a8dac
- Issue #15935: Clarification of argparse docs, re: add_argument() type and
Barry Warsaw <barry@python.org>
parents:
79025
diff
changeset
|
916 >>> parser.add_argument('--width', default=10.5, type=int) |
|
b624059a8dac
- Issue #15935: Clarification of argparse docs, re: add_argument() type and
Barry Warsaw <barry@python.org>
parents:
79025
diff
changeset
|
917 >>> parser.parse_args() |
|
b624059a8dac
- Issue #15935: Clarification of argparse docs, re: add_argument() type and
Barry Warsaw <barry@python.org>
parents:
79025
diff
changeset
|
918 Namespace(length=10, width=10.5) |
|
b624059a8dac
- Issue #15935: Clarification of argparse docs, re: add_argument() type and
Barry Warsaw <barry@python.org>
parents:
79025
diff
changeset
|
919 |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
920 For positional arguments with nargs_ equal to ``?`` or ``*``, the ``default`` value |
|
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
921 is used when no command-line argument was present:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
922 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
923 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
924 >>> parser.add_argument('foo', nargs='?', default=42) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
925 >>> parser.parse_args('a'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
926 Namespace(foo='a') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
927 >>> parser.parse_args(''.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
928 Namespace(foo=42) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
929 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
930 |
| 59293 | 931 Providing ``default=argparse.SUPPRESS`` causes no attribute to be added if the |
| 932 command-line argument was not present.:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
933 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
934 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
935 >>> parser.add_argument('--foo', default=argparse.SUPPRESS) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
936 >>> parser.parse_args([]) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
937 Namespace() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
938 >>> parser.parse_args(['--foo', '1']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
939 Namespace(foo='1') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
940 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
941 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
942 type |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
943 ^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
944 |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
945 By default, :class:`ArgumentParser` objects read command-line arguments in as simple |
|
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
946 strings. However, quite often the command-line string should instead be |
|
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
947 interpreted as another type, like a :class:`float` or :class:`int`. The |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
948 ``type`` keyword argument of :meth:`~ArgumentParser.add_argument` allows any |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
949 necessary type-checking and type conversions to be performed. Common built-in |
|
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
950 types and functions can be used directly as the value of the ``type`` argument:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
951 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
952 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
953 >>> parser.add_argument('foo', type=int) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
954 >>> parser.add_argument('bar', type=file) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
955 >>> parser.parse_args('2 temp.txt'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
956 Namespace(bar=<open file 'temp.txt', mode 'r' at 0x...>, foo=2) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
957 |
|
79165
b624059a8dac
- Issue #15935: Clarification of argparse docs, re: add_argument() type and
Barry Warsaw <barry@python.org>
parents:
79025
diff
changeset
|
958 See the section on the default_ keyword argument for information on when the |
|
b624059a8dac
- Issue #15935: Clarification of argparse docs, re: add_argument() type and
Barry Warsaw <barry@python.org>
parents:
79025
diff
changeset
|
959 ``type`` argument is applied to default arguments. |
|
b624059a8dac
- Issue #15935: Clarification of argparse docs, re: add_argument() type and
Barry Warsaw <barry@python.org>
parents:
79025
diff
changeset
|
960 |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
961 To ease the use of various types of files, the argparse module provides the |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
962 factory FileType which takes the ``mode=`` and ``bufsize=`` arguments of the |
| 59269 | 963 ``file`` object. For example, ``FileType('w')`` can be used to create a |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
964 writable file:: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
965 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
966 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
967 >>> parser.add_argument('bar', type=argparse.FileType('w')) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
968 >>> parser.parse_args(['out.txt']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
969 Namespace(bar=<open file 'out.txt', mode 'w' at 0x...>) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
970 |
| 59293 | 971 ``type=`` can take any callable that takes a single string argument and returns |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
972 the converted value:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
973 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
974 >>> def perfect_square(string): |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
975 ... value = int(string) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
976 ... sqrt = math.sqrt(value) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
977 ... if sqrt != int(sqrt): |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
978 ... msg = "%r is not a perfect square" % string |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
979 ... raise argparse.ArgumentTypeError(msg) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
980 ... return value |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
981 ... |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
982 >>> parser = argparse.ArgumentParser(prog='PROG') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
983 >>> parser.add_argument('foo', type=perfect_square) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
984 >>> parser.parse_args('9'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
985 Namespace(foo=9) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
986 >>> parser.parse_args('7'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
987 usage: PROG [-h] foo |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
988 PROG: error: argument foo: '7' is not a perfect square |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
989 |
| 59293 | 990 The choices_ keyword argument may be more convenient for type checkers that |
| 991 simply check against a range of values:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
992 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
993 >>> parser = argparse.ArgumentParser(prog='PROG') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
994 >>> parser.add_argument('foo', type=int, choices=xrange(5, 10)) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
995 >>> parser.parse_args('7'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
996 Namespace(foo=7) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
997 >>> parser.parse_args('11'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
998 usage: PROG [-h] {5,6,7,8,9} |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
999 PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1000 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1001 See the choices_ section for more details. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1002 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1003 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1004 choices |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1005 ^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1006 |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
1007 Some command-line arguments should be selected from a restricted set of values. |
| 59293 | 1008 These can be handled by passing a container object as the ``choices`` keyword |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1009 argument to :meth:`~ArgumentParser.add_argument`. When the command line is |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
1010 parsed, argument values will be checked, and an error message will be displayed if |
|
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
1011 the argument was not one of the acceptable values:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1012 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1013 >>> parser = argparse.ArgumentParser(prog='PROG') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1014 >>> parser.add_argument('foo', choices='abc') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1015 >>> parser.parse_args('c'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1016 Namespace(foo='c') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1017 >>> parser.parse_args('X'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1018 usage: PROG [-h] {a,b,c} |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1019 PROG: error: argument foo: invalid choice: 'X' (choose from 'a', 'b', 'c') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1020 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1021 Note that inclusion in the ``choices`` container is checked after any type_ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1022 conversions have been performed, so the type of the objects in the ``choices`` |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1023 container should match the type_ specified:: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1024 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1025 >>> parser = argparse.ArgumentParser(prog='PROG') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1026 >>> parser.add_argument('foo', type=complex, choices=[1, 1j]) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1027 >>> parser.parse_args('1j'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1028 Namespace(foo=1j) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1029 >>> parser.parse_args('-- -4'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1030 usage: PROG [-h] {1,1j} |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1031 PROG: error: argument foo: invalid choice: (-4+0j) (choose from 1, 1j) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1032 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1033 Any object that supports the ``in`` operator can be passed as the ``choices`` |
| 59269 | 1034 value, so :class:`dict` objects, :class:`set` objects, custom containers, |
| 1035 etc. are all supported. | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1036 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1037 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1038 required |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1039 ^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1040 |
|
69512
6f27baeecf4c
Add the :mod: role where it was missing.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69509
diff
changeset
|
1041 In general, the :mod:`argparse` module assumes that flags like ``-f`` and ``--bar`` |
|
69406
cc65cf9a9ce5
Fix a few hyphens in argparse.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
68987
diff
changeset
|
1042 indicate *optional* arguments, which can always be omitted at the command line. |
| 59293 | 1043 To make an option *required*, ``True`` can be specified for the ``required=`` |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1044 keyword argument to :meth:`~ArgumentParser.add_argument`:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1045 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1046 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1047 >>> parser.add_argument('--foo', required=True) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1048 >>> parser.parse_args(['--foo', 'BAR']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1049 Namespace(foo='BAR') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1050 >>> parser.parse_args([]) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1051 usage: argparse.py [-h] [--foo FOO] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1052 argparse.py: error: option --foo is required |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1053 |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1054 As the example shows, if an option is marked as ``required``, |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1055 :meth:`~ArgumentParser.parse_args` will report an error if that option is not |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1056 present at the command line. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1057 |
| 59293 | 1058 .. note:: |
| 1059 | |
| 1060 Required options are generally considered bad form because users expect | |
| 1061 *options* to be *optional*, and thus they should be avoided when possible. | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1062 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1063 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1064 help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1065 ^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1066 |
| 59293 | 1067 The ``help`` value is a string containing a brief description of the argument. |
| 1068 When a user requests help (usually by using ``-h`` or ``--help`` at the | |
|
69406
cc65cf9a9ce5
Fix a few hyphens in argparse.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
68987
diff
changeset
|
1069 command line), these ``help`` descriptions will be displayed with each |
| 59269 | 1070 argument:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1071 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1072 >>> parser = argparse.ArgumentParser(prog='frobble') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1073 >>> parser.add_argument('--foo', action='store_true', |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1074 ... help='foo the bars before frobbling') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1075 >>> parser.add_argument('bar', nargs='+', |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1076 ... help='one of the bars to be frobbled') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1077 >>> parser.parse_args('-h'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1078 usage: frobble [-h] [--foo] bar [bar ...] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1079 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1080 positional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1081 bar one of the bars to be frobbled |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1082 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1083 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1084 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1085 --foo foo the bars before frobbling |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1086 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1087 The ``help`` strings can include various format specifiers to avoid repetition |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1088 of things like the program name or the argument default_. The available |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1089 specifiers include the program name, ``%(prog)s`` and most keyword arguments to |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1090 :meth:`~ArgumentParser.add_argument`, e.g. ``%(default)s``, ``%(type)s``, etc.:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1091 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1092 >>> parser = argparse.ArgumentParser(prog='frobble') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1093 >>> parser.add_argument('bar', nargs='?', type=int, default=42, |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1094 ... help='the bar to %(prog)s (default: %(default)s)') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1095 >>> parser.print_help() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1096 usage: frobble [-h] [bar] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1097 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1098 positional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1099 bar the bar to frobble (default: 42) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1100 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1101 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1102 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1103 |
|
74243
17b7b856cbe8
Issue #9349: add argparse.SUPPRESS to help doc
Sandro Tosi <sandro.tosi@gmail.com>
parents:
73628
diff
changeset
|
1104 :mod:`argparse` supports silencing the help entry for certain options, by |
|
17b7b856cbe8
Issue #9349: add argparse.SUPPRESS to help doc
Sandro Tosi <sandro.tosi@gmail.com>
parents:
73628
diff
changeset
|
1105 setting the ``help`` value to ``argparse.SUPPRESS``:: |
|
17b7b856cbe8
Issue #9349: add argparse.SUPPRESS to help doc
Sandro Tosi <sandro.tosi@gmail.com>
parents:
73628
diff
changeset
|
1106 |
|
17b7b856cbe8
Issue #9349: add argparse.SUPPRESS to help doc
Sandro Tosi <sandro.tosi@gmail.com>
parents:
73628
diff
changeset
|
1107 >>> parser = argparse.ArgumentParser(prog='frobble') |
|
17b7b856cbe8
Issue #9349: add argparse.SUPPRESS to help doc
Sandro Tosi <sandro.tosi@gmail.com>
parents:
73628
diff
changeset
|
1108 >>> parser.add_argument('--foo', help=argparse.SUPPRESS) |
|
17b7b856cbe8
Issue #9349: add argparse.SUPPRESS to help doc
Sandro Tosi <sandro.tosi@gmail.com>
parents:
73628
diff
changeset
|
1109 >>> parser.print_help() |
|
17b7b856cbe8
Issue #9349: add argparse.SUPPRESS to help doc
Sandro Tosi <sandro.tosi@gmail.com>
parents:
73628
diff
changeset
|
1110 usage: frobble [-h] |
|
17b7b856cbe8
Issue #9349: add argparse.SUPPRESS to help doc
Sandro Tosi <sandro.tosi@gmail.com>
parents:
73628
diff
changeset
|
1111 |
|
17b7b856cbe8
Issue #9349: add argparse.SUPPRESS to help doc
Sandro Tosi <sandro.tosi@gmail.com>
parents:
73628
diff
changeset
|
1112 optional arguments: |
|
17b7b856cbe8
Issue #9349: add argparse.SUPPRESS to help doc
Sandro Tosi <sandro.tosi@gmail.com>
parents:
73628
diff
changeset
|
1113 -h, --help show this help message and exit |
|
17b7b856cbe8
Issue #9349: add argparse.SUPPRESS to help doc
Sandro Tosi <sandro.tosi@gmail.com>
parents:
73628
diff
changeset
|
1114 |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1115 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1116 metavar |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1117 ^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1118 |
| 59293 | 1119 When :class:`ArgumentParser` generates help messages, it need some way to refer |
| 59269 | 1120 to each expected argument. By default, ArgumentParser objects use the dest_ |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1121 value as the "name" of each object. By default, for positional argument |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1122 actions, the dest_ value is used directly, and for optional argument actions, |
| 59293 | 1123 the dest_ value is uppercased. So, a single positional argument with |
|
73498
477f633aa09d
Issue #13191: typo in argparse docs
Eli Bendersky <eliben@gmail.com>
parents:
72197
diff
changeset
|
1124 ``dest='bar'`` will be referred to as ``bar``. A single |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
1125 optional argument ``--foo`` that should be followed by a single command-line argument |
| 59293 | 1126 will be referred to as ``FOO``. An example:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1127 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1128 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1129 >>> parser.add_argument('--foo') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1130 >>> parser.add_argument('bar') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1131 >>> parser.parse_args('X --foo Y'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1132 Namespace(bar='X', foo='Y') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1133 >>> parser.print_help() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1134 usage: [-h] [--foo FOO] bar |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1135 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1136 positional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1137 bar |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1138 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1139 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1140 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1141 --foo FOO |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1142 |
| 59293 | 1143 An alternative name can be specified with ``metavar``:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1144 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1145 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1146 >>> parser.add_argument('--foo', metavar='YYY') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1147 >>> parser.add_argument('bar', metavar='XXX') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1148 >>> parser.parse_args('X --foo Y'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1149 Namespace(bar='X', foo='Y') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1150 >>> parser.print_help() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1151 usage: [-h] [--foo YYY] XXX |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1152 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1153 positional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1154 XXX |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1155 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1156 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1157 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1158 --foo YYY |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1159 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1160 Note that ``metavar`` only changes the *displayed* name - the name of the |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1161 attribute on the :meth:`~ArgumentParser.parse_args` object is still determined |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1162 by the dest_ value. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1163 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1164 Different values of ``nargs`` may cause the metavar to be used multiple times. |
| 59293 | 1165 Providing a tuple to ``metavar`` specifies a different display for each of the |
| 1166 arguments:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1167 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1168 >>> parser = argparse.ArgumentParser(prog='PROG') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1169 >>> parser.add_argument('-x', nargs=2) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1170 >>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz')) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1171 >>> parser.print_help() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1172 usage: PROG [-h] [-x X X] [--foo bar baz] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1173 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1174 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1175 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1176 -x X X |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1177 --foo bar baz |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1178 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1179 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1180 dest |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1181 ^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1182 |
| 59293 | 1183 Most :class:`ArgumentParser` actions add some value as an attribute of the |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1184 object returned by :meth:`~ArgumentParser.parse_args`. The name of this |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1185 attribute is determined by the ``dest`` keyword argument of |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1186 :meth:`~ArgumentParser.add_argument`. For positional argument actions, |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1187 ``dest`` is normally supplied as the first argument to |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1188 :meth:`~ArgumentParser.add_argument`:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1189 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1190 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1191 >>> parser.add_argument('bar') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1192 >>> parser.parse_args('XXX'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1193 Namespace(bar='XXX') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1194 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1195 For optional argument actions, the value of ``dest`` is normally inferred from |
| 59293 | 1196 the option strings. :class:`ArgumentParser` generates the value of ``dest`` by |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
1197 taking the first long option string and stripping away the initial ``--`` |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1198 string. If no long option strings were supplied, ``dest`` will be derived from |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
1199 the first short option string by stripping the initial ``-`` character. Any |
|
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
1200 internal ``-`` characters will be converted to ``_`` characters to make sure |
| 59269 | 1201 the string is a valid attribute name. The examples below illustrate this |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1202 behavior:: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1203 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1204 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1205 >>> parser.add_argument('-f', '--foo-bar', '--foo') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1206 >>> parser.add_argument('-x', '-y') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1207 >>> parser.parse_args('-f 1 -x 2'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1208 Namespace(foo_bar='1', x='2') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1209 >>> parser.parse_args('--foo 1 -y 2'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1210 Namespace(foo_bar='1', x='2') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1211 |
| 59293 | 1212 ``dest`` allows a custom attribute name to be provided:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1213 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1214 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1215 >>> parser.add_argument('--foo', dest='bar') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1216 >>> parser.parse_args('--foo XXX'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1217 Namespace(bar='XXX') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1218 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1219 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1220 The parse_args() method |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1221 ----------------------- |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1222 |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1223 .. method:: ArgumentParser.parse_args(args=None, namespace=None) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1224 |
| 59293 | 1225 Convert argument strings to objects and assign them as attributes of the |
| 59269 | 1226 namespace. Return the populated namespace. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1227 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1228 Previous calls to :meth:`add_argument` determine exactly what objects are |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1229 created and how they are assigned. See the documentation for |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1230 :meth:`add_argument` for details. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1231 |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
1232 By default, the argument strings are taken from :data:`sys.argv`, and a new empty |
| 59293 | 1233 :class:`Namespace` object is created for the attributes. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1234 |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1235 |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1236 Option value syntax |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1237 ^^^^^^^^^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1238 |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1239 The :meth:`~ArgumentParser.parse_args` method supports several ways of |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1240 specifying the value of an option (if it takes one). In the simplest case, the |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1241 option and its value are passed as two separate arguments:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1242 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1243 >>> parser = argparse.ArgumentParser(prog='PROG') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1244 >>> parser.add_argument('-x') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1245 >>> parser.add_argument('--foo') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1246 >>> parser.parse_args('-x X'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1247 Namespace(foo=None, x='X') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1248 >>> parser.parse_args('--foo FOO'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1249 Namespace(foo='FOO', x=None) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1250 |
| 59293 | 1251 For long options (options with names longer than a single character), the option |
|
69406
cc65cf9a9ce5
Fix a few hyphens in argparse.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
68987
diff
changeset
|
1252 and value can also be passed as a single command-line argument, using ``=`` to |
| 59269 | 1253 separate them:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1254 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1255 >>> parser.parse_args('--foo=FOO'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1256 Namespace(foo='FOO', x=None) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1257 |
| 59293 | 1258 For short options (options only one character long), the option and its value |
| 1259 can be concatenated:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1260 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1261 >>> parser.parse_args('-xX'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1262 Namespace(foo=None, x='X') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1263 |
| 59293 | 1264 Several short options can be joined together, using only a single ``-`` prefix, |
| 1265 as long as only the last option (or none of them) requires a value:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1266 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1267 >>> parser = argparse.ArgumentParser(prog='PROG') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1268 >>> parser.add_argument('-x', action='store_true') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1269 >>> parser.add_argument('-y', action='store_true') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1270 >>> parser.add_argument('-z') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1271 >>> parser.parse_args('-xyzZ'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1272 Namespace(x=True, y=True, z='Z') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1273 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1274 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1275 Invalid arguments |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1276 ^^^^^^^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1277 |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1278 While parsing the command line, :meth:`~ArgumentParser.parse_args` checks for a |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1279 variety of errors, including ambiguous options, invalid types, invalid options, |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1280 wrong number of positional arguments, etc. When it encounters such an error, |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1281 it exits and prints the error along with a usage message:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1282 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1283 >>> parser = argparse.ArgumentParser(prog='PROG') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1284 >>> parser.add_argument('--foo', type=int) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1285 >>> parser.add_argument('bar', nargs='?') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1286 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1287 >>> # invalid type |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1288 >>> parser.parse_args(['--foo', 'spam']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1289 usage: PROG [-h] [--foo FOO] [bar] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1290 PROG: error: argument --foo: invalid int value: 'spam' |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1291 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1292 >>> # invalid option |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1293 >>> parser.parse_args(['--bar']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1294 usage: PROG [-h] [--foo FOO] [bar] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1295 PROG: error: no such option: --bar |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1296 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1297 >>> # wrong number of arguments |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1298 >>> parser.parse_args(['spam', 'badger']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1299 usage: PROG [-h] [--foo FOO] [bar] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1300 PROG: error: extra arguments found: badger |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1301 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1302 |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
1303 Arguments containing ``-`` |
|
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
1304 ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1305 |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1306 The :meth:`~ArgumentParser.parse_args` method attempts to give errors whenever |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1307 the user has clearly made a mistake, but some situations are inherently |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
1308 ambiguous. For example, the command-line argument ``-1`` could either be an |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1309 attempt to specify an option or an attempt to provide a positional argument. |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1310 The :meth:`~ArgumentParser.parse_args` method is cautious here: positional |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
1311 arguments may only begin with ``-`` if they look like negative numbers and |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1312 there are no options in the parser that look like negative numbers:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1313 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1314 >>> parser = argparse.ArgumentParser(prog='PROG') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1315 >>> parser.add_argument('-x') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1316 >>> parser.add_argument('foo', nargs='?') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1317 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1318 >>> # no negative number options, so -1 is a positional argument |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1319 >>> parser.parse_args(['-x', '-1']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1320 Namespace(foo=None, x='-1') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1321 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1322 >>> # no negative number options, so -1 and -5 are positional arguments |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1323 >>> parser.parse_args(['-x', '-1', '-5']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1324 Namespace(foo='-5', x='-1') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1325 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1326 >>> parser = argparse.ArgumentParser(prog='PROG') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1327 >>> parser.add_argument('-1', dest='one') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1328 >>> parser.add_argument('foo', nargs='?') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1329 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1330 >>> # negative number options present, so -1 is an option |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1331 >>> parser.parse_args(['-1', 'X']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1332 Namespace(foo=None, one='X') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1333 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1334 >>> # negative number options present, so -2 is an option |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1335 >>> parser.parse_args(['-2']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1336 usage: PROG [-h] [-1 ONE] [foo] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1337 PROG: error: no such option: -2 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1338 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1339 >>> # negative number options present, so both -1s are options |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1340 >>> parser.parse_args(['-1', '-1']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1341 usage: PROG [-h] [-1 ONE] [foo] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1342 PROG: error: argument -1: expected one argument |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1343 |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
1344 If you have positional arguments that must begin with ``-`` and don't look |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1345 like negative numbers, you can insert the pseudo-argument ``'--'`` which tells |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1346 :meth:`~ArgumentParser.parse_args` that everything after that is a positional |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1347 argument:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1348 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1349 >>> parser.parse_args(['--', '-f']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1350 Namespace(foo='-f', one=None) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1351 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1352 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1353 Argument abbreviations |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1354 ^^^^^^^^^^^^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1355 |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1356 The :meth:`~ArgumentParser.parse_args` method allows long options to be |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1357 abbreviated if the abbreviation is unambiguous:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1358 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1359 >>> parser = argparse.ArgumentParser(prog='PROG') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1360 >>> parser.add_argument('-bacon') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1361 >>> parser.add_argument('-badger') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1362 >>> parser.parse_args('-bac MMM'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1363 Namespace(bacon='MMM', badger=None) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1364 >>> parser.parse_args('-bad WOOD'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1365 Namespace(bacon=None, badger='WOOD') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1366 >>> parser.parse_args('-ba BA'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1367 usage: PROG [-h] [-bacon BACON] [-badger BADGER] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1368 PROG: error: ambiguous option: -ba could match -badger, -bacon |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1369 |
| 59293 | 1370 An error is produced for arguments that could produce more than one options. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1371 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1372 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1373 Beyond ``sys.argv`` |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1374 ^^^^^^^^^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1375 |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
1376 Sometimes it may be useful to have an ArgumentParser parse arguments other than those |
| 59269 | 1377 of :data:`sys.argv`. This can be accomplished by passing a list of strings to |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1378 :meth:`~ArgumentParser.parse_args`. This is useful for testing at the |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1379 interactive prompt:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1380 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1381 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1382 >>> parser.add_argument( |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1383 ... 'integers', metavar='int', type=int, choices=xrange(10), |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1384 ... nargs='+', help='an integer in the range 0..9') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1385 >>> parser.add_argument( |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1386 ... '--sum', dest='accumulate', action='store_const', const=sum, |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1387 ... default=max, help='sum the integers (default: find the max)') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1388 >>> parser.parse_args(['1', '2', '3', '4']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1389 Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4]) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1390 >>> parser.parse_args('1 2 3 4 --sum'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1391 Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4]) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1392 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1393 |
|
68979
fe72160ea2a3
Issue #8982: Improve the documentation for the argparse Namespace object. (Merge from 3.2.)
Steven Bethard <steven.bethard@gmail.com>
parents:
67921
diff
changeset
|
1394 The Namespace object |
|
fe72160ea2a3
Issue #8982: Improve the documentation for the argparse Namespace object. (Merge from 3.2.)
Steven Bethard <steven.bethard@gmail.com>
parents:
67921
diff
changeset
|
1395 ^^^^^^^^^^^^^^^^^^^^ |
|
fe72160ea2a3
Issue #8982: Improve the documentation for the argparse Namespace object. (Merge from 3.2.)
Steven Bethard <steven.bethard@gmail.com>
parents:
67921
diff
changeset
|
1396 |
|
71606
01722022f88d
Add a link target for argparse.Namespace (#8982)
Éric Araujo <merwok@netwok.org>
parents:
69525
diff
changeset
|
1397 .. class:: Namespace |
|
01722022f88d
Add a link target for argparse.Namespace (#8982)
Éric Araujo <merwok@netwok.org>
parents:
69525
diff
changeset
|
1398 |
|
01722022f88d
Add a link target for argparse.Namespace (#8982)
Éric Araujo <merwok@netwok.org>
parents:
69525
diff
changeset
|
1399 Simple class used by default by :meth:`~ArgumentParser.parse_args` to create |
|
01722022f88d
Add a link target for argparse.Namespace (#8982)
Éric Araujo <merwok@netwok.org>
parents:
69525
diff
changeset
|
1400 an object holding attributes and return it. |
|
01722022f88d
Add a link target for argparse.Namespace (#8982)
Éric Araujo <merwok@netwok.org>
parents:
69525
diff
changeset
|
1401 |
|
01722022f88d
Add a link target for argparse.Namespace (#8982)
Éric Araujo <merwok@netwok.org>
parents:
69525
diff
changeset
|
1402 This class is deliberately simple, just an :class:`object` subclass with a |
|
01722022f88d
Add a link target for argparse.Namespace (#8982)
Éric Araujo <merwok@netwok.org>
parents:
69525
diff
changeset
|
1403 readable string representation. If you prefer to have dict-like view of the |
|
01722022f88d
Add a link target for argparse.Namespace (#8982)
Éric Araujo <merwok@netwok.org>
parents:
69525
diff
changeset
|
1404 attributes, you can use the standard Python idiom, :func:`vars`:: |
|
68979
fe72160ea2a3
Issue #8982: Improve the documentation for the argparse Namespace object. (Merge from 3.2.)
Steven Bethard <steven.bethard@gmail.com>
parents:
67921
diff
changeset
|
1405 |
|
fe72160ea2a3
Issue #8982: Improve the documentation for the argparse Namespace object. (Merge from 3.2.)
Steven Bethard <steven.bethard@gmail.com>
parents:
67921
diff
changeset
|
1406 >>> parser = argparse.ArgumentParser() |
|
fe72160ea2a3
Issue #8982: Improve the documentation for the argparse Namespace object. (Merge from 3.2.)
Steven Bethard <steven.bethard@gmail.com>
parents:
67921
diff
changeset
|
1407 >>> parser.add_argument('--foo') |
|
fe72160ea2a3
Issue #8982: Improve the documentation for the argparse Namespace object. (Merge from 3.2.)
Steven Bethard <steven.bethard@gmail.com>
parents:
67921
diff
changeset
|
1408 >>> args = parser.parse_args(['--foo', 'BAR']) |
|
fe72160ea2a3
Issue #8982: Improve the documentation for the argparse Namespace object. (Merge from 3.2.)
Steven Bethard <steven.bethard@gmail.com>
parents:
67921
diff
changeset
|
1409 >>> vars(args) |
|
fe72160ea2a3
Issue #8982: Improve the documentation for the argparse Namespace object. (Merge from 3.2.)
Steven Bethard <steven.bethard@gmail.com>
parents:
67921
diff
changeset
|
1410 {'foo': 'BAR'} |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1411 |
| 59293 | 1412 It may also be useful to have an :class:`ArgumentParser` assign attributes to an |
|
68979
fe72160ea2a3
Issue #8982: Improve the documentation for the argparse Namespace object. (Merge from 3.2.)
Steven Bethard <steven.bethard@gmail.com>
parents:
67921
diff
changeset
|
1413 already existing object, rather than a new :class:`Namespace` object. This can |
|
fe72160ea2a3
Issue #8982: Improve the documentation for the argparse Namespace object. (Merge from 3.2.)
Steven Bethard <steven.bethard@gmail.com>
parents:
67921
diff
changeset
|
1414 be achieved by specifying the ``namespace=`` keyword argument:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1415 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1416 >>> class C(object): |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1417 ... pass |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1418 ... |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1419 >>> c = C() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1420 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1421 >>> parser.add_argument('--foo') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1422 >>> parser.parse_args(args=['--foo', 'BAR'], namespace=c) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1423 >>> c.foo |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1424 'BAR' |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1425 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1426 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1427 Other utilities |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1428 --------------- |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1429 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1430 Sub-commands |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1431 ^^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1432 |
| 59293 | 1433 .. method:: ArgumentParser.add_subparsers() |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1434 |
| 59293 | 1435 Many programs split up their functionality into a number of sub-commands, |
| 59269 | 1436 for example, the ``svn`` program can invoke sub-commands like ``svn |
| 59293 | 1437 checkout``, ``svn update``, and ``svn commit``. Splitting up functionality |
| 59269 | 1438 this way can be a particularly good idea when a program performs several |
| 1439 different functions which require different kinds of command-line arguments. | |
| 59293 | 1440 :class:`ArgumentParser` supports the creation of such sub-commands with the |
| 59269 | 1441 :meth:`add_subparsers` method. The :meth:`add_subparsers` method is normally |
| 1442 called with no arguments and returns an special action object. This object | |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1443 has a single method, :meth:`~ArgumentParser.add_parser`, which takes a |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1444 command name and any :class:`ArgumentParser` constructor arguments, and |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1445 returns an :class:`ArgumentParser` object that can be modified as usual. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1446 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1447 Some example usage:: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1448 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1449 >>> # create the top-level parser |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1450 >>> parser = argparse.ArgumentParser(prog='PROG') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1451 >>> parser.add_argument('--foo', action='store_true', help='foo help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1452 >>> subparsers = parser.add_subparsers(help='sub-command help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1453 >>> |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1454 >>> # create the parser for the "a" command |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1455 >>> parser_a = subparsers.add_parser('a', help='a help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1456 >>> parser_a.add_argument('bar', type=int, help='bar help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1457 >>> |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1458 >>> # create the parser for the "b" command |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1459 >>> parser_b = subparsers.add_parser('b', help='b help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1460 >>> parser_b.add_argument('--baz', choices='XYZ', help='baz help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1461 >>> |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
1462 >>> # parse some argument lists |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1463 >>> parser.parse_args(['a', '12']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1464 Namespace(bar=12, foo=False) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1465 >>> parser.parse_args(['--foo', 'b', '--baz', 'Z']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1466 Namespace(baz='Z', foo=True) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1467 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1468 Note that the object returned by :meth:`parse_args` will only contain |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1469 attributes for the main parser and the subparser that was selected by the |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1470 command line (and not any other subparsers). So in the example above, when |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
1471 the ``a`` command is specified, only the ``foo`` and ``bar`` attributes are |
|
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
1472 present, and when the ``b`` command is specified, only the ``foo`` and |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1473 ``baz`` attributes are present. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1474 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1475 Similarly, when a help message is requested from a subparser, only the help |
| 59269 | 1476 for that particular parser will be printed. The help message will not |
| 59293 | 1477 include parent parser or sibling parser messages. (A help message for each |
| 1478 subparser command, however, can be given by supplying the ``help=`` argument | |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1479 to :meth:`add_parser` as above.) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1480 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1481 :: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1482 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1483 >>> parser.parse_args(['--help']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1484 usage: PROG [-h] [--foo] {a,b} ... |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1485 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1486 positional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1487 {a,b} sub-command help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1488 a a help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1489 b b help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1490 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1491 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1492 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1493 --foo foo help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1494 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1495 >>> parser.parse_args(['a', '--help']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1496 usage: PROG a [-h] bar |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1497 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1498 positional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1499 bar bar help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1500 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1501 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1502 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1503 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1504 >>> parser.parse_args(['b', '--help']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1505 usage: PROG b [-h] [--baz {X,Y,Z}] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1506 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1507 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1508 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1509 --baz {X,Y,Z} baz help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1510 |
| 59269 | 1511 The :meth:`add_subparsers` method also supports ``title`` and ``description`` |
| 1512 keyword arguments. When either is present, the subparser's commands will | |
| 1513 appear in their own group in the help output. For example:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1514 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1515 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1516 >>> subparsers = parser.add_subparsers(title='subcommands', |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1517 ... description='valid subcommands', |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1518 ... help='additional help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1519 >>> subparsers.add_parser('foo') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1520 >>> subparsers.add_parser('bar') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1521 >>> parser.parse_args(['-h']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1522 usage: [-h] {foo,bar} ... |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1523 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1524 optional arguments: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1525 -h, --help show this help message and exit |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1526 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1527 subcommands: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1528 valid subcommands |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1529 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1530 {foo,bar} additional help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1531 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1532 |
| 59269 | 1533 One particularly effective way of handling sub-commands is to combine the use |
| 1534 of the :meth:`add_subparsers` method with calls to :meth:`set_defaults` so | |
| 1535 that each subparser knows which Python function it should execute. For | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1536 example:: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1537 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1538 >>> # sub-command functions |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1539 >>> def foo(args): |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1540 ... print args.x * args.y |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1541 ... |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1542 >>> def bar(args): |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1543 ... print '((%s))' % args.z |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1544 ... |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1545 >>> # create the top-level parser |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1546 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1547 >>> subparsers = parser.add_subparsers() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1548 >>> |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1549 >>> # create the parser for the "foo" command |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1550 >>> parser_foo = subparsers.add_parser('foo') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1551 >>> parser_foo.add_argument('-x', type=int, default=1) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1552 >>> parser_foo.add_argument('y', type=float) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1553 >>> parser_foo.set_defaults(func=foo) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1554 >>> |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1555 >>> # create the parser for the "bar" command |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1556 >>> parser_bar = subparsers.add_parser('bar') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1557 >>> parser_bar.add_argument('z') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1558 >>> parser_bar.set_defaults(func=bar) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1559 >>> |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1560 >>> # parse the args and call whatever function was selected |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1561 >>> args = parser.parse_args('foo 1 -x 2'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1562 >>> args.func(args) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1563 2.0 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1564 >>> |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1565 >>> # parse the args and call whatever function was selected |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1566 >>> args = parser.parse_args('bar XYZYX'.split()) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1567 >>> args.func(args) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1568 ((XYZYX)) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1569 |
|
75053
7ff4731853e2
Add missing “::” markup and wrap overlong lines
Éric Araujo <merwok@netwok.org>
parents:
74529
diff
changeset
|
1570 This way, you can let :meth:`parse_args` do the job of calling the |
| 59293 | 1571 appropriate function after argument parsing is complete. Associating |
| 1572 functions with actions like this is typically the easiest way to handle the | |
| 1573 different actions for each of your subparsers. However, if it is necessary | |
| 1574 to check the name of the subparser that was invoked, the ``dest`` keyword | |
| 1575 argument to the :meth:`add_subparsers` call will work:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1576 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1577 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1578 >>> subparsers = parser.add_subparsers(dest='subparser_name') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1579 >>> subparser1 = subparsers.add_parser('1') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1580 >>> subparser1.add_argument('-x') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1581 >>> subparser2 = subparsers.add_parser('2') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1582 >>> subparser2.add_argument('y') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1583 >>> parser.parse_args(['2', 'frobble']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1584 Namespace(subparser_name='2', y='frobble') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1585 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1586 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1587 FileType objects |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1588 ^^^^^^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1589 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1590 .. class:: FileType(mode='r', bufsize=None) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1591 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1592 The :class:`FileType` factory creates objects that can be passed to the type |
| 59293 | 1593 argument of :meth:`ArgumentParser.add_argument`. Arguments that have |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
1594 :class:`FileType` objects as their type will open command-line arguments as files |
|
75053
7ff4731853e2
Add missing “::” markup and wrap overlong lines
Éric Araujo <merwok@netwok.org>
parents:
74529
diff
changeset
|
1595 with the requested modes and buffer sizes:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1596 |
|
75053
7ff4731853e2
Add missing “::” markup and wrap overlong lines
Éric Araujo <merwok@netwok.org>
parents:
74529
diff
changeset
|
1597 >>> parser = argparse.ArgumentParser() |
|
7ff4731853e2
Add missing “::” markup and wrap overlong lines
Éric Araujo <merwok@netwok.org>
parents:
74529
diff
changeset
|
1598 >>> parser.add_argument('--output', type=argparse.FileType('wb', 0)) |
|
7ff4731853e2
Add missing “::” markup and wrap overlong lines
Éric Araujo <merwok@netwok.org>
parents:
74529
diff
changeset
|
1599 >>> parser.parse_args(['--output', 'out']) |
|
7ff4731853e2
Add missing “::” markup and wrap overlong lines
Éric Araujo <merwok@netwok.org>
parents:
74529
diff
changeset
|
1600 Namespace(output=<open file 'out', mode 'wb' at 0x...>) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1601 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1602 FileType objects understand the pseudo-argument ``'-'`` and automatically |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1603 convert this into ``sys.stdin`` for readable :class:`FileType` objects and |
|
75053
7ff4731853e2
Add missing “::” markup and wrap overlong lines
Éric Araujo <merwok@netwok.org>
parents:
74529
diff
changeset
|
1604 ``sys.stdout`` for writable :class:`FileType` objects:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1605 |
|
75053
7ff4731853e2
Add missing “::” markup and wrap overlong lines
Éric Araujo <merwok@netwok.org>
parents:
74529
diff
changeset
|
1606 >>> parser = argparse.ArgumentParser() |
|
7ff4731853e2
Add missing “::” markup and wrap overlong lines
Éric Araujo <merwok@netwok.org>
parents:
74529
diff
changeset
|
1607 >>> parser.add_argument('infile', type=argparse.FileType('r')) |
|
7ff4731853e2
Add missing “::” markup and wrap overlong lines
Éric Araujo <merwok@netwok.org>
parents:
74529
diff
changeset
|
1608 >>> parser.parse_args(['-']) |
|
7ff4731853e2
Add missing “::” markup and wrap overlong lines
Éric Araujo <merwok@netwok.org>
parents:
74529
diff
changeset
|
1609 Namespace(infile=<open file '<stdin>', mode 'r' at 0x...>) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1610 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1611 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1612 Argument groups |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1613 ^^^^^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1614 |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1615 .. method:: ArgumentParser.add_argument_group(title=None, description=None) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1616 |
| 59293 | 1617 By default, :class:`ArgumentParser` groups command-line arguments into |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1618 "positional arguments" and "optional arguments" when displaying help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1619 messages. When there is a better conceptual grouping of arguments than this |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1620 default one, appropriate groups can be created using the |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1621 :meth:`add_argument_group` method:: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1622 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1623 >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1624 >>> group = parser.add_argument_group('group') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1625 >>> group.add_argument('--foo', help='foo help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1626 >>> group.add_argument('bar', help='bar help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1627 >>> parser.print_help() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1628 usage: PROG [--foo FOO] bar |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1629 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1630 group: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1631 bar bar help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1632 --foo FOO foo help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1633 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1634 The :meth:`add_argument_group` method returns an argument group object which |
| 59293 | 1635 has an :meth:`~ArgumentParser.add_argument` method just like a regular |
| 1636 :class:`ArgumentParser`. When an argument is added to the group, the parser | |
| 1637 treats it just like a normal argument, but displays the argument in a | |
| 1638 separate group for help messages. The :meth:`add_argument_group` method | |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1639 accepts *title* and *description* arguments which can be used to |
| 59293 | 1640 customize this display:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1641 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1642 >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1643 >>> group1 = parser.add_argument_group('group1', 'group1 description') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1644 >>> group1.add_argument('foo', help='foo help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1645 >>> group2 = parser.add_argument_group('group2', 'group2 description') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1646 >>> group2.add_argument('--bar', help='bar help') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1647 >>> parser.print_help() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1648 usage: PROG [--bar BAR] foo |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1649 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1650 group1: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1651 group1 description |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1652 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1653 foo foo help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1654 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1655 group2: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1656 group2 description |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1657 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1658 --bar BAR bar help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1659 |
|
75950
03771ea22ead
Issue #14410: fix typo in argparse doc; patch by Tshepang Lekhonkhobe
Sandro Tosi <sandro.tosi@gmail.com>
parents:
75053
diff
changeset
|
1660 Note that any arguments not in your user-defined groups will end up back |
|
03771ea22ead
Issue #14410: fix typo in argparse doc; patch by Tshepang Lekhonkhobe
Sandro Tosi <sandro.tosi@gmail.com>
parents:
75053
diff
changeset
|
1661 in the usual "positional arguments" and "optional arguments" sections. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1662 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1663 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1664 Mutual exclusion |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1665 ^^^^^^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1666 |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1667 .. method:: add_mutually_exclusive_group(required=False) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1668 |
|
69512
6f27baeecf4c
Add the :mod: role where it was missing.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69509
diff
changeset
|
1669 Create a mutually exclusive group. :mod:`argparse` will make sure that only |
|
6f27baeecf4c
Add the :mod: role where it was missing.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69509
diff
changeset
|
1670 one of the arguments in the mutually exclusive group was present on the |
|
6f27baeecf4c
Add the :mod: role where it was missing.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69509
diff
changeset
|
1671 command line:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1672 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1673 >>> parser = argparse.ArgumentParser(prog='PROG') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1674 >>> group = parser.add_mutually_exclusive_group() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1675 >>> group.add_argument('--foo', action='store_true') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1676 >>> group.add_argument('--bar', action='store_false') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1677 >>> parser.parse_args(['--foo']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1678 Namespace(bar=True, foo=True) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1679 >>> parser.parse_args(['--bar']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1680 Namespace(bar=False, foo=False) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1681 >>> parser.parse_args(['--foo', '--bar']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1682 usage: PROG [-h] [--foo | --bar] |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1683 PROG: error: argument --bar: not allowed with argument --foo |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1684 |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1685 The :meth:`add_mutually_exclusive_group` method also accepts a *required* |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1686 argument, to indicate that at least one of the mutually exclusive arguments |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1687 is required:: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1688 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1689 >>> parser = argparse.ArgumentParser(prog='PROG') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1690 >>> group = parser.add_mutually_exclusive_group(required=True) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1691 >>> group.add_argument('--foo', action='store_true') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1692 >>> group.add_argument('--bar', action='store_false') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1693 >>> parser.parse_args([]) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1694 usage: PROG [-h] (--foo | --bar) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1695 PROG: error: one of the arguments --foo --bar is required |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1696 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1697 Note that currently mutually exclusive argument groups do not support the |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1698 *title* and *description* arguments of |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1699 :meth:`~ArgumentParser.add_argument_group`. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1700 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1701 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1702 Parser defaults |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1703 ^^^^^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1704 |
| 59293 | 1705 .. method:: ArgumentParser.set_defaults(**kwargs) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1706 |
| 59269 | 1707 Most of the time, the attributes of the object returned by :meth:`parse_args` |
|
71950
4e28e8a9a817
Synchronize argparse docs with 3.x versions
Éric Araujo <merwok@netwok.org>
parents:
71716
diff
changeset
|
1708 will be fully determined by inspecting the command-line arguments and the argument |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1709 actions. :meth:`set_defaults` allows some additional |
|
69406
cc65cf9a9ce5
Fix a few hyphens in argparse.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
68987
diff
changeset
|
1710 attributes that are determined without any inspection of the command line to |
|
59294
38cef8deae22
fix Sphinx warnings
Benjamin Peterson <benjamin@python.org>
parents:
59293
diff
changeset
|
1711 be added:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1712 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1713 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1714 >>> parser.add_argument('foo', type=int) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1715 >>> parser.set_defaults(bar=42, baz='badger') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1716 >>> parser.parse_args(['736']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1717 Namespace(bar=42, baz='badger', foo=736) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1718 |
| 59293 | 1719 Note that parser-level defaults always override argument-level defaults:: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1720 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1721 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1722 >>> parser.add_argument('--foo', default='bar') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1723 >>> parser.set_defaults(foo='spam') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1724 >>> parser.parse_args([]) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1725 Namespace(foo='spam') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1726 |
| 59293 | 1727 Parser-level defaults can be particularly useful when working with multiple |
| 1728 parsers. See the :meth:`~ArgumentParser.add_subparsers` method for an | |
| 1729 example of this type. | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1730 |
| 59293 | 1731 .. method:: ArgumentParser.get_default(dest) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1732 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1733 Get the default value for a namespace attribute, as set by either |
| 59293 | 1734 :meth:`~ArgumentParser.add_argument` or by |
| 1735 :meth:`~ArgumentParser.set_defaults`:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1736 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1737 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1738 >>> parser.add_argument('--foo', default='badger') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1739 >>> parser.get_default('foo') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1740 'badger' |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1741 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1742 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1743 Printing help |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1744 ^^^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1745 |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1746 In most typical applications, :meth:`~ArgumentParser.parse_args` will take |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1747 care of formatting and printing any usage or error messages. However, several |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1748 formatting methods are available: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1749 |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1750 .. method:: ArgumentParser.print_usage(file=None) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1751 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1752 Print a brief description of how the :class:`ArgumentParser` should be |
|
67921
89d52effc30a
Merged revisions 86542,87136,87216,87221,87228,87256,87337-87338,87372,87516,87571,88164 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents:
67495
diff
changeset
|
1753 invoked on the command line. If *file* is ``None``, :data:`sys.stdout` is |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1754 assumed. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1755 |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1756 .. method:: ArgumentParser.print_help(file=None) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1757 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1758 Print a help message, including the program usage and information about the |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1759 arguments registered with the :class:`ArgumentParser`. If *file* is |
|
67921
89d52effc30a
Merged revisions 86542,87136,87216,87221,87228,87256,87337-87338,87372,87516,87571,88164 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents:
67495
diff
changeset
|
1760 ``None``, :data:`sys.stdout` is assumed. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1761 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1762 There are also variants of these methods that simply return a string instead of |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1763 printing it: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1764 |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1765 .. method:: ArgumentParser.format_usage() |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1766 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1767 Return a string containing a brief description of how the |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1768 :class:`ArgumentParser` should be invoked on the command line. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1769 |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1770 .. method:: ArgumentParser.format_help() |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1771 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1772 Return a string containing a help message, including the program usage and |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1773 information about the arguments registered with the :class:`ArgumentParser`. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1774 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1775 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1776 Partial parsing |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1777 ^^^^^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1778 |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1779 .. method:: ArgumentParser.parse_known_args(args=None, namespace=None) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1780 |
|
69406
cc65cf9a9ce5
Fix a few hyphens in argparse.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
68987
diff
changeset
|
1781 Sometimes a script may only parse a few of the command-line arguments, passing |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1782 the remaining arguments on to another script or program. In these cases, the |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1783 :meth:`~ArgumentParser.parse_known_args` method can be useful. It works much like |
| 59293 | 1784 :meth:`~ArgumentParser.parse_args` except that it does not produce an error when |
| 1785 extra arguments are present. Instead, it returns a two item tuple containing | |
| 1786 the populated namespace and the list of remaining argument strings. | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1787 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1788 :: |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1789 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1790 >>> parser = argparse.ArgumentParser() |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1791 >>> parser.add_argument('--foo', action='store_true') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1792 >>> parser.add_argument('bar') |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1793 >>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1794 (Namespace(bar='BAR', foo=True), ['--badger', 'spam']) |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1795 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1796 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1797 Customizing file parsing |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1798 ^^^^^^^^^^^^^^^^^^^^^^^^ |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1799 |
| 59293 | 1800 .. method:: ArgumentParser.convert_arg_line_to_args(arg_line) |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1801 |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1802 Arguments that are read from a file (see the *fromfile_prefix_chars* |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1803 keyword argument to the :class:`ArgumentParser` constructor) are read one |
| 59293 | 1804 argument per line. :meth:`convert_arg_line_to_args` can be overriden for |
| 1805 fancier reading. | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1806 |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1807 This method takes a single argument *arg_line* which is a string read from |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1808 the argument file. It returns a list of arguments parsed from this string. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1809 The method is called once per line read from the argument file, in order. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1810 |
| 59269 | 1811 A useful override of this method is one that treats each space-separated word |
| 1812 as an argument:: | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1813 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1814 def convert_arg_line_to_args(self, arg_line): |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1815 for arg in arg_line.split(): |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1816 if not arg.strip(): |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1817 continue |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1818 yield arg |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1819 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1820 |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1821 Exiting methods |
|
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1822 ^^^^^^^^^^^^^^^ |
|
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1823 |
|
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1824 .. method:: ArgumentParser.exit(status=0, message=None) |
|
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1825 |
|
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1826 This method terminates the program, exiting with the specified *status* |
|
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1827 and, if given, it prints a *message* before that. |
|
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1828 |
|
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1829 .. method:: ArgumentParser.error(message) |
|
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1830 |
|
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1831 This method prints a usage message including the *message* to the |
|
71716
1e8dc34ece30
Fix closes issue12663 - Correcting the ArgumentParser.error description. Patch by Sandro Tosi.
Senthil Kumaran <senthil@uthcode.com>
parents:
71606
diff
changeset
|
1832 standard error and terminates the program with a status code of 2. |
|
66457
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1833 |
|
a803fd841fd1
Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents:
65144
diff
changeset
|
1834 |
| 62723 | 1835 .. _argparse-from-optparse: |
| 1836 | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1837 Upgrading optparse code |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1838 ----------------------- |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1839 |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1840 Originally, the :mod:`argparse` module had attempted to maintain compatibility |
|
69512
6f27baeecf4c
Add the :mod: role where it was missing.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69509
diff
changeset
|
1841 with :mod:`optparse`. However, :mod:`optparse` was difficult to extend |
|
6f27baeecf4c
Add the :mod: role where it was missing.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69509
diff
changeset
|
1842 transparently, particularly with the changes required to support the new |
|
6f27baeecf4c
Add the :mod: role where it was missing.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69509
diff
changeset
|
1843 ``nargs=`` specifiers and better usage messages. When most everything in |
|
6f27baeecf4c
Add the :mod: role where it was missing.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69509
diff
changeset
|
1844 :mod:`optparse` had either been copy-pasted over or monkey-patched, it no |
|
6f27baeecf4c
Add the :mod: role where it was missing.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69509
diff
changeset
|
1845 longer seemed practical to try to maintain the backwards compatibility. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1846 |
|
69512
6f27baeecf4c
Add the :mod: role where it was missing.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69509
diff
changeset
|
1847 A partial upgrade path from :mod:`optparse` to :mod:`argparse`: |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1848 |
|
69525
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1849 * Replace all :meth:`optparse.OptionParser.add_option` calls with |
|
c821d3d335e8
Fix some more markup glitches in argparse doc.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69524
diff
changeset
|
1850 :meth:`ArgumentParser.add_argument` calls. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1851 |
|
76001
cb5214e6c287
#10423: clarify options vs args in argparse discussion of optparse
R David Murray <rdmurray@bitdance.com>
parents:
75950
diff
changeset
|
1852 * Replace ``(options, args) = parser.parse_args()`` with ``args = |
|
67495
681d0542bbbd
Merged revisions 87890 via svnmerge from
Georg Brandl <georg@python.org>
parents:
66457
diff
changeset
|
1853 parser.parse_args()`` and add additional :meth:`ArgumentParser.add_argument` |
|
76001
cb5214e6c287
#10423: clarify options vs args in argparse discussion of optparse
R David Murray <rdmurray@bitdance.com>
parents:
75950
diff
changeset
|
1854 calls for the positional arguments. Keep in mind that what was previously |
|
cb5214e6c287
#10423: clarify options vs args in argparse discussion of optparse
R David Murray <rdmurray@bitdance.com>
parents:
75950
diff
changeset
|
1855 called ``options``, now in :mod:`argparse` context is called ``args``. |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1856 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1857 * Replace callback actions and the ``callback_*`` keyword arguments with |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1858 ``type`` or ``action`` arguments. |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1859 |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1860 * Replace string names for ``type`` keyword arguments with the corresponding |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1861 type objects (e.g. int, float, complex, etc). |
|
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1862 |
| 59293 | 1863 * Replace :class:`optparse.Values` with :class:`Namespace` and |
| 1864 :exc:`optparse.OptionError` and :exc:`optparse.OptionValueError` with | |
| 1865 :exc:`ArgumentError`. | |
|
59267
4ca83c5b8551
set svn:eol-style
Benjamin Peterson <benjamin@python.org>
parents:
59257
diff
changeset
|
1866 |
| 59269 | 1867 * Replace strings with implicit arguments such as ``%default`` or ``%prog`` with |
|
69509
0f084f150198
#11885: capitalize Python.
Ezio Melotti <ezio.melotti@gmail.com>
parents:
69406
diff
changeset
|
1868 the standard Python syntax to use dictionaries to format strings, that is, |
| 59269 | 1869 ``%(default)s`` and ``%(prog)s``. |
|
61877
40cad759a355
argparse documentation updates (including updates to optparse and getopt documentation that were promised in the PEP)
Steven Bethard <steven.bethard@gmail.com>
parents:
61715
diff
changeset
|
1870 |
|
40cad759a355
argparse documentation updates (including updates to optparse and getopt documentation that were promised in the PEP)
Steven Bethard <steven.bethard@gmail.com>
parents:
61715
diff
changeset
|
1871 * Replace the OptionParser constructor ``version`` argument with a call to |
|
40cad759a355
argparse documentation updates (including updates to optparse and getopt documentation that were promised in the PEP)
Steven Bethard <steven.bethard@gmail.com>
parents:
61715
diff
changeset
|
1872 ``parser.add_argument('--version', action='version', version='<the version>')`` |