cpython-lru_cache-weakref: Doc/library/optparse.rst annotate

annotate Doc/library/optparse.rst @ 78069:a8aa77458e12 3.2

Add c_size_t and c_ssize_t to the ctypes summary table.

author	Antoine Pitrou <solipsis@pitrou.net>
date	Thu, 12 Jul 2012 20:31:50 +0200
parents	738c43484b47
children	8c60bb098eff

rev	line source
59258 f923fe55a40c Merged revisions 78576 via svnmerge from Steven Bethard <steven.bethard@gmail.com> parents: 58157 diff changeset	1 :mod:`optparse` --- Parser for command line options
f923fe55a40c Merged revisions 78576 via svnmerge from Steven Bethard <steven.bethard@gmail.com> parents: 58157 diff changeset	2 ===================================================
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 .. module:: optparse
59258 f923fe55a40c Merged revisions 78576 via svnmerge from Steven Bethard <steven.bethard@gmail.com> parents: 58157 diff changeset	5 :synopsis: Command-line option parsing library.
61878 7750579c375d Merged revisions 81490 via svnmerge from Steven Bethard <steven.bethard@gmail.com> parents: 59944 diff changeset	6 :deprecated:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7 .. moduleauthor:: Greg Ward <gward@python.net>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 .. sectionauthor:: Greg Ward <gward@python.net>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9
71926 3bbb1a3eca01 Add a few missing source links from 2.7 and harmonize lib docs headers Éric Araujo <merwok@netwok.org> parents: 71629 diff changeset	10 .. deprecated:: 3.2
3bbb1a3eca01 Add a few missing source links from 2.7 and harmonize lib docs headers Éric Araujo <merwok@netwok.org> parents: 71629 diff changeset	11 The :mod:`optparse` module is deprecated and will not be developed further;
3bbb1a3eca01 Add a few missing source links from 2.7 and harmonize lib docs headers Éric Araujo <merwok@netwok.org> parents: 71629 diff changeset	12 development will continue with the :mod:`argparse` module.
3bbb1a3eca01 Add a few missing source links from 2.7 and harmonize lib docs headers Éric Araujo <merwok@netwok.org> parents: 71629 diff changeset	13
67786 dd7328672968 More source links Raymond Hettinger <python@rcn.com> parents: 67256 diff changeset	14 Source code: :source:`Lib/optparse.py`
dd7328672968 More source links Raymond Hettinger <python@rcn.com> parents: 67256 diff changeset	15
dd7328672968 More source links Raymond Hettinger <python@rcn.com> parents: 67256 diff changeset	16 --------------
61878 7750579c375d Merged revisions 81490 via svnmerge from Steven Bethard <steven.bethard@gmail.com> parents: 59944 diff changeset	17
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	18 :mod:`optparse` is a more convenient, flexible, and powerful library for parsing
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	19 command-line options than the old :mod:`getopt` module. :mod:`optparse` uses a
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	20 more declarative style of command-line parsing: you create an instance of
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	21 :class:`OptionParser`, populate it with options, and parse the command
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	22 line. :mod:`optparse` allows users to specify options in the conventional
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	23 GNU/POSIX syntax, and additionally generates usage and help messages for you.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	24
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	25 Here's an example of using :mod:`optparse` in a simple script::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27 from optparse import OptionParser
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29 parser = OptionParser()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30 parser.add_option("-f", "--file", dest="filename",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31 help="write report to FILE", metavar="FILE")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32 parser.add_option("-q", "--quiet",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33 action="store_false", dest="verbose", default=True,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34 help="don't print status messages to stdout")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36 (options, args) = parser.parse_args()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38 With these few lines of code, users of your script can now do the "usual thing"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 on the command-line, for example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41 <yourscript> --file=outfile -q
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	43 As it parses the command line, :mod:`optparse` sets attributes of the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	44 ``options`` object returned by :meth:`parse_args` based on user-supplied
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	45 command-line values. When :meth:`parse_args` returns from parsing this command
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	46 line, ``options.filename`` will be ``"outfile"`` and ``options.verbose`` will be
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	47 ``False``. :mod:`optparse` supports both long and short options, allows short
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48 options to be merged together, and allows options to be associated with their
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49 arguments in a variety of ways. Thus, the following command lines are all
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50 equivalent to the above example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52 <yourscript> -f outfile --quiet
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53 <yourscript> --quiet --file outfile
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54 <yourscript> -q -foutfile
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55 <yourscript> -qfoutfile
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57 Additionally, users can run one of ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59 <yourscript> -h
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60 <yourscript> --help
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61
58119 e54434d2e2a7 Merged revisions 77269 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58026 diff changeset	62 and :mod:`optparse` will print out a brief summary of your script's options:
e54434d2e2a7 Merged revisions 77269 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58026 diff changeset	63
e54434d2e2a7 Merged revisions 77269 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58026 diff changeset	64 .. code-block:: text
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65
68009 92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	66 Usage: <yourscript> [options]
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	67
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	68 Options:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69 -h, --help show this help message and exit
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 -f FILE, --file=FILE write report to FILE
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 -q, --quiet don't print status messages to stdout
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73 where the value of yourscript is determined at runtime (normally from
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74 ``sys.argv[0]``).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77 .. _optparse-background:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 Background
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80 ----------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82 :mod:`optparse` was explicitly designed to encourage the creation of programs
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83 with straightforward, conventional command-line interfaces. To that end, it
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84 supports only the most common command-line syntax and semantics conventionally
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85 used under Unix. If you are unfamiliar with these conventions, read this
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86 section to acquaint yourself with them.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89 .. _optparse-terminology:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91 Terminology
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92 ^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 argument
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	95 a string entered on the command-line, and passed by the shell to ``execl()``
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	96 or ``execv()``. In Python, arguments are elements of ``sys.argv[1:]``
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	97 (``sys.argv[0]`` is the name of the program being executed). Unix shells
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	98 also use the term "word".
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100 It is occasionally desirable to substitute an argument list other than
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101 ``sys.argv[1:]``, so you should read "argument" as "an element of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 ``sys.argv[1:]``, or of some other list provided as a substitute for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103 ``sys.argv[1:]``".
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104
49095 4d148bb84a07 Merged revisions 66141,66145,66150,66180,66211,66217,66219,66226,66231,66244,66246,66249-66250,66264,66268,66272,66294,66306 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48321 diff changeset	105 option
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	106 an argument used to supply extra information to guide or customize the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	107 execution of a program. There are many different syntaxes for options; the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	108 traditional Unix syntax is a hyphen ("-") followed by a single letter,
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	109 e.g. ``-x`` or ``-F``. Also, traditional Unix syntax allows multiple
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	110 options to be merged into a single argument, e.g. ``-x -F`` is equivalent
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	111 to ``-xF``. The GNU project introduced ``--`` followed by a series of
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	112 hyphen-separated words, e.g. ``--file`` or ``--dry-run``. These are the
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	113 only two option syntaxes provided by :mod:`optparse`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115 Some other option syntaxes that the world has seen include:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	117 * a hyphen followed by a few letters, e.g. ``-pf`` (this is not the same
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118 as multiple options merged into a single argument)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	120 * a hyphen followed by a whole word, e.g. ``-file`` (this is technically
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121 equivalent to the previous syntax, but they aren't usually seen in the same
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122 program)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124 * a plus sign followed by a single letter, or a few letters, or a word, e.g.
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	125 ``+f``, ``+rgb``
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	126
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	127 * a slash followed by a letter, or a few letters, or a word, e.g. ``/f``,
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	128 ``/file``
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	130 These option syntaxes are not supported by :mod:`optparse`, and they never
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	131 will be. This is deliberate: the first three are non-standard on any
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	132 environment, and the last only makes sense if you're exclusively targeting
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	133 VMS, MS-DOS, and/or Windows.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135 option argument
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	136 an argument that follows an option, is closely associated with that option,
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	137 and is consumed from the argument list when that option is. With
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	138 :mod:`optparse`, option arguments may either be in a separate argument from
58119 e54434d2e2a7 Merged revisions 77269 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58026 diff changeset	139 their option:
e54434d2e2a7 Merged revisions 77269 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58026 diff changeset	140
e54434d2e2a7 Merged revisions 77269 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58026 diff changeset	141 .. code-block:: text
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143 -f foo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144 --file foo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145
58119 e54434d2e2a7 Merged revisions 77269 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58026 diff changeset	146 or included in the same argument:
e54434d2e2a7 Merged revisions 77269 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58026 diff changeset	147
e54434d2e2a7 Merged revisions 77269 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58026 diff changeset	148 .. code-block:: text
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 -ffoo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151 --file=foo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	153 Typically, a given option either takes an argument or it doesn't. Lots of
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	154 people want an "optional option arguments" feature, meaning that some options
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	155 will take an argument if they see it, and won't if they don't. This is
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	156 somewhat controversial, because it makes parsing ambiguous: if ``-a`` takes
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	157 an optional argument and ``-b`` is another option entirely, how do we
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	158 interpret ``-ab``? Because of this ambiguity, :mod:`optparse` does not
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	159 support this feature.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161 positional argument
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162 something leftover in the argument list after options have been parsed, i.e.
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	163 after options and their arguments have been parsed and removed from the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	164 argument list.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	166 required option
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167 an option that must be supplied on the command-line; note that the phrase
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168 "required option" is self-contradictory in English. :mod:`optparse` doesn't
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	169 prevent you from implementing required options, but doesn't give you much
58026 e078579984a4 Merged revisions 77167 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 56054 diff changeset	170 help at it either.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	172 For example, consider this hypothetical command-line::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	173
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	174 prog -v --report /tmp/report.txt foo bar
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	175
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	176 ``-v`` and ``--report`` are both options. Assuming that ``--report``
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	177 takes one argument, ``/tmp/report.txt`` is an option argument. ``foo`` and
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	178 ``bar`` are positional arguments.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	180
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	181 .. _optparse-what-options-for:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	183 What are options for?
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184 ^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186 Options are used to provide extra information to tune or customize the execution
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187 of a program. In case it wasn't clear, options are usually optional. A
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188 program should be able to run just fine with no options whatsoever. (Pick a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	189 random program from the Unix or GNU toolsets. Can it run without any options at
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	190 all and still make sense? The main exceptions are ``find``, ``tar``, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191 ``dd``\ ---all of which are mutant oddballs that have been rightly criticized
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	192 for their non-standard syntax and confusing interfaces.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194 Lots of people want their programs to have "required options". Think about it.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	195 If it's required, then it's not optional! If there is a piece of information
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196 that your program absolutely requires in order to run successfully, that's what
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197 positional arguments are for.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199 As an example of good command-line interface design, consider the humble ``cp``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200 utility, for copying files. It doesn't make much sense to try to copy files
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201 without supplying a destination and at least one source. Hence, ``cp`` fails if
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202 you run it with no arguments. However, it has a flexible, useful syntax that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203 does not require any options at all::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205 cp SOURCE DEST
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206 cp SOURCE ... DEST-DIR
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208 You can get pretty far with just that. Most ``cp`` implementations provide a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209 bunch of options to tweak exactly how the files are copied: you can preserve
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210 mode and modification time, avoid following symlinks, ask before clobbering
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211 existing files, etc. But none of this distracts from the core mission of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212 ``cp``, which is to copy either one file to another, or several files to another
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213 directory.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216 .. _optparse-what-positional-arguments-for:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 What are positional arguments for?
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221 Positional arguments are for those pieces of information that your program
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222 absolutely, positively requires to run.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224 A good user interface should have as few absolute requirements as possible. If
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225 your program requires 17 distinct pieces of information in order to run
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226 successfully, it doesn't much matter how you get that information from the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227 user---most people will give up and walk away before they successfully run the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228 program. This applies whether the user interface is a command-line, a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229 configuration file, or a GUI: if you make that many demands on your users, most
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230 of them will simply give up.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	232 In short, try to minimize the amount of information that users are absolutely
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233 required to supply---use sensible defaults whenever possible. Of course, you
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234 also want to make your programs reasonably flexible. That's what options are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235 for. Again, it doesn't matter if they are entries in a config file, widgets in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236 the "Preferences" dialog of a GUI, or command-line options---the more options
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237 you implement, the more flexible your program is, and the more complicated its
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238 implementation becomes. Too much flexibility has drawbacks as well, of course;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239 too many options can overwhelm users and make your code much harder to maintain.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242 .. _optparse-tutorial:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244 Tutorial
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245 --------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247 While :mod:`optparse` is quite flexible and powerful, it's also straightforward
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248 to use in most cases. This section covers the code patterns that are common to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249 any :mod:`optparse`\ -based program.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	251 First, you need to import the OptionParser class; then, early in the main
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	252 program, create an OptionParser instance::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	254 from optparse import OptionParser
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	255 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	256 parser = OptionParser()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	257
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258 Then you can start defining options. The basic syntax is::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 parser.add_option(opt_str, ...,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261 attr=value, ...)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	263 Each option has one or more option strings, such as ``-f`` or ``--file``,
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264 and several option attributes that tell :mod:`optparse` what to expect and what
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265 to do when it encounters that option on the command line.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	267 Typically, each option will have one short option string and one long option
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	268 string, e.g.::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	270 parser.add_option("-f", "--file", ...)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	271
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	272 You're free to define as many short option strings and as many long option
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273 strings as you like (including zero), as long as there is at least one option
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	274 string overall.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	275
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276 The option strings passed to :meth:`add_option` are effectively labels for the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277 option defined by that call. For brevity, we will frequently refer to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278 encountering an option on the command line; in reality, :mod:`optparse`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279 encounters option strings and looks up options from them.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281 Once all of your options are defined, instruct :mod:`optparse` to parse your
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	282 program's command line::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	283
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284 (options, args) = parser.parse_args()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	285
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286 (If you like, you can pass a custom argument list to :meth:`parse_args`, but
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287 that's rarely necessary: by default it uses ``sys.argv[1:]``.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	289 :meth:`parse_args` returns two values:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	290
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	291 * ``options``, an object containing values for all of your options---e.g. if
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	292 ``--file`` takes a single string argument, then ``options.file`` will be the
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	293 filename supplied by the user, or ``None`` if the user did not supply that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294 option
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	295
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	296 * ``args``, the list of positional arguments leftover after parsing options
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	297
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	298 This tutorial section only covers the four most important option attributes:
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	299 :attr:`~Option.action`, :attr:`~Option.type`, :attr:`~Option.dest`
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	300 (destination), and :attr:`~Option.help`. Of these, :attr:`~Option.action` is the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	301 most fundamental.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	302
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	303
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	304 .. _optparse-understanding-option-actions:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	305
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	306 Understanding option actions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	307 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	308
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	309 Actions tell :mod:`optparse` what to do when it encounters an option on the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310 command line. There is a fixed set of actions hard-coded into :mod:`optparse`;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311 adding new actions is an advanced topic covered in section
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	312 :ref:`optparse-extending-optparse`. Most actions tell :mod:`optparse` to store
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	313 a value in some variable---for example, take a string from the command line and
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	314 store it in an attribute of ``options``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316 If you don't specify an option action, :mod:`optparse` defaults to ``store``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319 .. _optparse-store-action:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321 The store action
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322 ^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324 The most common option action is ``store``, which tells :mod:`optparse` to take
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325 the next argument (or the remainder of the current argument), ensure that it is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326 of the correct type, and store it to your chosen destination.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328 For example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330 parser.add_option("-f", "--file",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331 action="store", type="string", dest="filename")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	332
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333 Now let's make up a fake command line and ask :mod:`optparse` to parse it::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335 args = ["-f", "foo.txt"]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336 (options, args) = parser.parse_args(args)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	338 When :mod:`optparse` sees the option string ``-f``, it consumes the next
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	339 argument, ``foo.txt``, and stores it in ``options.filename``. So, after this
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340 call to :meth:`parse_args`, ``options.filename`` is ``"foo.txt"``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	341
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342 Some other option types supported by :mod:`optparse` are ``int`` and ``float``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	343 Here's an option that expects an integer argument::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345 parser.add_option("-n", type="int", dest="num")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347 Note that this option has no long option string, which is perfectly acceptable.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348 Also, there's no explicit action, since the default is ``store``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	349
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	350 Let's parse another fake command-line. This time, we'll jam the option argument
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	351 right up against the option: since ``-n42`` (one argument) is equivalent to
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	352 ``-n 42`` (two arguments), the code ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	353
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	354 (options, args) = parser.parse_args(["-n42"])
43219 655071bf6c45 Convert all print statements in the docs. Georg Brandl <georg@python.org> parents: 43176 diff changeset	355 print(options.num)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	357 will print ``42``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359 If you don't specify a type, :mod:`optparse` assumes ``string``. Combined with
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360 the fact that the default action is ``store``, that means our first example can
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	361 be a lot shorter::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	363 parser.add_option("-f", "--file", dest="filename")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	364
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	365 If you don't supply a destination, :mod:`optparse` figures out a sensible
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	366 default from the option strings: if the first long option string is
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	367 ``--foo-bar``, then the default destination is ``foo_bar``. If there are no
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	368 long option strings, :mod:`optparse` looks at the first short option string: the
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	369 default destination for ``-f`` is ``f``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	370
44053 f2385d98282a Remove further mentions of long integers. Georg Brandl <georg@python.org> parents: 43737 diff changeset	371 :mod:`optparse` also includes the built-in ``complex`` type. Adding
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	372 types is covered in section :ref:`optparse-extending-optparse`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	373
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	374
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	375 .. _optparse-handling-boolean-options:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	376
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	377 Handling boolean (flag) options
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	378 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	379
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	380 Flag options---set a variable to true or false when a particular option is seen
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	381 ---are quite common. :mod:`optparse` supports them with two separate actions,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	382 ``store_true`` and ``store_false``. For example, you might have a ``verbose``
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	383 flag that is turned on with ``-v`` and off with ``-q``::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	384
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	385 parser.add_option("-v", action="store_true", dest="verbose")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	386 parser.add_option("-q", action="store_false", dest="verbose")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	387
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	388 Here we have two different options with the same destination, which is perfectly
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	389 OK. (It just means you have to be a bit careful when setting default values---
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	390 see below.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	392 When :mod:`optparse` encounters ``-v`` on the command line, it sets
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	393 ``options.verbose`` to ``True``; when it encounters ``-q``,
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	394 ``options.verbose`` is set to ``False``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	395
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	397 .. _optparse-other-actions:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	398
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	399 Other actions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400 ^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	401
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	402 Some other actions supported by :mod:`optparse` are:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	403
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	404 ``"store_const"``
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405 store a constant value
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	406
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	407 ``"append"``
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408 append this option's argument to a list
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	410 ``"count"``
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411 increment a counter by one
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	412
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	413 ``"callback"``
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414 call a specified function
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	415
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416 These are covered in section :ref:`optparse-reference-guide`, Reference Guide
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417 and section :ref:`optparse-option-callbacks`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	418
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	420 .. _optparse-default-values:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	421
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	422 Default values
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	423 ^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	424
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	425 All of the above examples involve setting some variable (the "destination") when
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	426 certain command-line options are seen. What happens if those options are never
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427 seen? Since we didn't supply any defaults, they are all set to ``None``. This
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428 is usually fine, but sometimes you want more control. :mod:`optparse` lets you
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	429 supply a default value for each destination, which is assigned before the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	430 command line is parsed.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	431
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	432 First, consider the verbose/quiet example. If we want :mod:`optparse` to set
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	433 ``verbose`` to ``True`` unless ``-q`` is seen, then we can do this::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	434
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	435 parser.add_option("-v", action="store_true", dest="verbose", default=True)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	436 parser.add_option("-q", action="store_false", dest="verbose")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	437
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	438 Since default values apply to the destination rather than to any particular
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	439 option, and these two options happen to have the same destination, this is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	440 exactly equivalent::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	441
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	442 parser.add_option("-v", action="store_true", dest="verbose")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	443 parser.add_option("-q", action="store_false", dest="verbose", default=True)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	444
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	445 Consider this::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	446
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	447 parser.add_option("-v", action="store_true", dest="verbose", default=False)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	448 parser.add_option("-q", action="store_false", dest="verbose", default=True)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	449
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	450 Again, the default value for ``verbose`` will be ``True``: the last default
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	451 value supplied for any particular destination is the one that counts.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	452
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	453 A clearer way to specify default values is the :meth:`set_defaults` method of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	454 OptionParser, which you can call at any time before calling :meth:`parse_args`::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	455
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	456 parser.set_defaults(verbose=True)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	457 parser.add_option(...)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	458 (options, args) = parser.parse_args()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	459
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	460 As before, the last value specified for a given option destination is the one
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	461 that counts. For clarity, try to use one method or the other of setting default
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	462 values, not both.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	463
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	464
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	465 .. _optparse-generating-help:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	466
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	467 Generating help
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	468 ^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	469
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	470 :mod:`optparse`'s ability to generate help and usage text automatically is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	471 useful for creating user-friendly command-line interfaces. All you have to do
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	472 is supply a :attr:`~Option.help` value for each option, and optionally a short
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	473 usage message for your whole program. Here's an OptionParser populated with
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	474 user-friendly (documented) options::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	475
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	476 usage = "usage: %prog [options] arg1 arg2"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	477 parser = OptionParser(usage=usage)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	478 parser.add_option("-v", "--verbose",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	479 action="store_true", dest="verbose", default=True,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	480 help="make lots of noise [default]")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	481 parser.add_option("-q", "--quiet",
49095 4d148bb84a07 Merged revisions 66141,66145,66150,66180,66211,66217,66219,66226,66231,66244,66246,66249-66250,66264,66268,66272,66294,66306 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48321 diff changeset	482 action="store_false", dest="verbose",
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	483 help="be vewwy quiet (I'm hunting wabbits)")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	484 parser.add_option("-f", "--filename",
56002 fa91270b6087 Merged revisions 74821,74828-74831,74833,74835 via svnmerge from Georg Brandl <georg@python.org> parents: 55797 diff changeset	485 metavar="FILE", help="write output to FILE")
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	486 parser.add_option("-m", "--mode",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	487 default="intermediate",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	488 help="interaction mode: novice, intermediate, "
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	489 "or expert [default: %default]")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	490
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	491 If :mod:`optparse` encounters either ``-h`` or ``--help`` on the
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	492 command-line, or if you just call :meth:`parser.print_help`, it prints the
58119 e54434d2e2a7 Merged revisions 77269 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58026 diff changeset	493 following to standard output:
e54434d2e2a7 Merged revisions 77269 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58026 diff changeset	494
e54434d2e2a7 Merged revisions 77269 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58026 diff changeset	495 .. code-block:: text
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	496
68009 92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	497 Usage: <yourscript> [options] arg1 arg2
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	498
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	499 Options:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	500 -h, --help show this help message and exit
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	501 -v, --verbose make lots of noise [default]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	502 -q, --quiet be vewwy quiet (I'm hunting wabbits)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	503 -f FILE, --filename=FILE
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	504 write output to FILE
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	505 -m MODE, --mode=MODE interaction mode: novice, intermediate, or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	506 expert [default: intermediate]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	507
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	508 (If the help output is triggered by a help option, :mod:`optparse` exits after
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	509 printing the help text.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	510
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	511 There's a lot going on here to help :mod:`optparse` generate the best possible
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	512 help message:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	513
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	514 * the script defines its own usage message::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	515
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	516 usage = "usage: %prog [options] arg1 arg2"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	517
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	518 :mod:`optparse` expands ``%prog`` in the usage string to the name of the
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	519 current program, i.e. ``os.path.basename(sys.argv[0])``. The expanded string
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	520 is then printed before the detailed option help.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	521
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	522 If you don't supply a usage string, :mod:`optparse` uses a bland but sensible
68009 92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	523 default: ``"Usage: %prog [options]"``, which is fine if your script doesn't
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	524 take any positional arguments.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	525
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	526 * every option defines a help string, and doesn't worry about line-wrapping---
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	527 :mod:`optparse` takes care of wrapping lines and making the help output look
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	528 good.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	529
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	530 * options that take a value indicate this fact in their automatically-generated
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	531 help message, e.g. for the "mode" option::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	532
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	533 -m MODE, --mode=MODE
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	534
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	535 Here, "MODE" is called the meta-variable: it stands for the argument that the
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	536 user is expected to supply to ``-m``/``--mode``. By default,
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	537 :mod:`optparse` converts the destination variable name to uppercase and uses
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	538 that for the meta-variable. Sometimes, that's not what you want---for
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	539 example, the ``--filename`` option explicitly sets ``metavar="FILE"``,
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	540 resulting in this automatically-generated option description::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	541
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	542 -f FILE, --filename=FILE
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	544 This is important for more than just saving space, though: the manually
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	545 written help text uses the meta-variable ``FILE`` to clue the user in that
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	546 there's a connection between the semi-formal syntax ``-f FILE`` and the informal
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	547 semantic description "write output to FILE". This is a simple but effective
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	548 way to make your help text a lot clearer and more useful for end users.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	549
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	550 * options that have a default value can include ``%default`` in the help
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	551 string---\ :mod:`optparse` will replace it with :func:`str` of the option's
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	552 default value. If an option has no default value (or the default value is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	553 ``None``), ``%default`` expands to ``none``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	554
68009 92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	555 Grouping Options
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	556 ++++++++++++++++
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	557
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	558 When dealing with many options, it is convenient to group these options for
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	559 better help output. An :class:`OptionParser` can contain several option groups,
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	560 each of which can contain several options.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	561
68009 92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	562 An option group is obtained using the class :class:`OptionGroup`:
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	563
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	564 .. class:: OptionGroup(parser, title, description=None)
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	565
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	566 where
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	567
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	568 * parser is the :class:`OptionParser` instance the group will be insterted in
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	569 to
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	570 * title is the group title
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	571 * description, optional, is a long description of the group
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	572
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	573 :class:`OptionGroup` inherits from :class:`OptionContainer` (like
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	574 :class:`OptionParser`) and so the :meth:`add_option` method can be used to add
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	575 an option to the group.
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	576
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	577 Once all the options are declared, using the :class:`OptionParser` method
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	578 :meth:`add_option_group` the group is added to the previously defined parser.
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	579
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	580 Continuing with the parser defined in the previous section, adding an
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	581 :class:`OptionGroup` to a parser is easy::
44810 fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	582
fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	583 group = OptionGroup(parser, "Dangerous Options",
50571 3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	584 "Caution: use these options at your own risk. "
3b08674b9b48 Merged revisions 68227 via svnmerge from Georg Brandl <georg@python.org> parents: 50563 diff changeset	585 "It is believed that some of them bite.")
44810 fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	586 group.add_option("-g", action="store_true", help="Group option.")
fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	587 parser.add_option_group(group)
fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	588
58119 e54434d2e2a7 Merged revisions 77269 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58026 diff changeset	589 This would result in the following help output:
e54434d2e2a7 Merged revisions 77269 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58026 diff changeset	590
e54434d2e2a7 Merged revisions 77269 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58026 diff changeset	591 .. code-block:: text
44810 fa6cee14dcba Merged revisions 60094-60123 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44396 diff changeset	592
68009 92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	593 Usage: <yourscript> [options] arg1 arg2
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	594
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	595 Options:
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	596 -h, --help show this help message and exit
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	597 -v, --verbose make lots of noise [default]
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	598 -q, --quiet be vewwy quiet (I'm hunting wabbits)
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	599 -f FILE, --filename=FILE
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	600 write output to FILE
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	601 -m MODE, --mode=MODE interaction mode: novice, intermediate, or
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	602 expert [default: intermediate]
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	603
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	604 Dangerous Options:
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	605 Caution: use these options at your own risk. It is believed that some
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	606 of them bite.
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	607
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	608 -g Group option.
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	609
73586 738c43484b47 fixing typos in optparse doc Eli Bendersky <eliben@gmail.com> parents: 71926 diff changeset	610 A bit more complete example might involve using more than one group: still
738c43484b47 fixing typos in optparse doc Eli Bendersky <eliben@gmail.com> parents: 71926 diff changeset	611 extending the previous example::
68009 92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	612
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	613 group = OptionGroup(parser, "Dangerous Options",
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	614 "Caution: use these options at your own risk. "
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	615 "It is believed that some of them bite.")
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	616 group.add_option("-g", action="store_true", help="Group option.")
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	617 parser.add_option_group(group)
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	618
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	619 group = OptionGroup(parser, "Debug Options")
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	620 group.add_option("-d", "--debug", action="store_true",
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	621 help="Print debug information")
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	622 group.add_option("-s", "--sql", action="store_true",
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	623 help="Print all SQL statements executed")
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	624 group.add_option("-e", action="store_true", help="Print every action done")
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	625 parser.add_option_group(group)
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	626
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	627 that results in the following output:
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	628
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	629 .. code-block:: text
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	630
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	631 Usage: <yourscript> [options] arg1 arg2
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	632
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	633 Options:
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	634 -h, --help show this help message and exit
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	635 -v, --verbose make lots of noise [default]
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	636 -q, --quiet be vewwy quiet (I'm hunting wabbits)
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	637 -f FILE, --filename=FILE
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	638 write output to FILE
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	639 -m MODE, --mode=MODE interaction mode: novice, intermediate, or expert
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	640 [default: intermediate]
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	641
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	642 Dangerous Options:
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	643 Caution: use these options at your own risk. It is believed that some
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	644 of them bite.
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	645
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	646 -g Group option.
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	647
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	648 Debug Options:
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	649 -d, --debug Print debug information
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	650 -s, --sql Print all SQL statements executed
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	651 -e Print every action done
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	652
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	653 Another interesting method, in particular when working programmatically with
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	654 option groups is:
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	655
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	656 .. method:: OptionParser.get_option_group(opt_str)
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	657
71629 cfb60dfa7734 Issue #11699: fix documentation of OptionParser.get_option_group. Patch by Petri Lehtinen Eli Bendersky <eliben@gmail.com> parents: 68257 diff changeset	658 Return the :class:`OptionGroup` to which the short or long option
cfb60dfa7734 Issue #11699: fix documentation of OptionParser.get_option_group. Patch by Petri Lehtinen Eli Bendersky <eliben@gmail.com> parents: 68257 diff changeset	659 string opt_str (e.g. ``'-o'`` or ``'--option'``) belongs. If
cfb60dfa7734 Issue #11699: fix documentation of OptionParser.get_option_group. Patch by Petri Lehtinen Eli Bendersky <eliben@gmail.com> parents: 68257 diff changeset	660 there's no such :class:`OptionGroup`, return ``None``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	661
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	662 .. _optparse-printing-version-string:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	663
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	664 Printing a version string
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	665 ^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	666
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	667 Similar to the brief usage string, :mod:`optparse` can also print a version
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	668 string for your program. You have to supply the string as the ``version``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	669 argument to OptionParser::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	670
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	671 parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	672
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	673 ``%prog`` is expanded just like it is in ``usage``. Apart from that,
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	674 ``version`` can contain anything you like. When you supply it, :mod:`optparse`
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	675 automatically adds a ``--version`` option to your parser. If it encounters
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	676 this option on the command line, it expands your ``version`` string (by
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	677 replacing ``%prog``), prints it to stdout, and exits.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	678
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	679 For example, if your script is called ``/usr/bin/foo``::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	680
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	681 $ /usr/bin/foo --version
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	682 foo 1.0
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	683
58158 fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	684 The following two methods can be used to print and get the ``version`` string:
fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	685
fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	686 .. method:: OptionParser.print_version(file=None)
fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	687
fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	688 Print the version message for the current program (``self.version``) to
fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	689 file (default stdout). As with :meth:`print_usage`, any occurrence
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	690 of ``%prog`` in ``self.version`` is replaced with the name of the current
58158 fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	691 program. Does nothing if ``self.version`` is empty or undefined.
fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	692
fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	693 .. method:: OptionParser.get_version()
fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	694
fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	695 Same as :meth:`print_version` but returns the version string instead of
fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	696 printing it.
fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	697
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	698
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	699 .. _optparse-how-optparse-handles-errors:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	700
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	701 How :mod:`optparse` handles errors
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	702 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	703
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	704 There are two broad classes of errors that :mod:`optparse` has to worry about:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	705 programmer errors and user errors. Programmer errors are usually erroneous
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	706 calls to :func:`OptionParser.add_option`, e.g. invalid option strings, unknown
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	707 option attributes, missing option attributes, etc. These are dealt with in the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	708 usual way: raise an exception (either :exc:`optparse.OptionError` or
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	709 :exc:`TypeError`) and let the program crash.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	710
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	711 Handling user errors is much more important, since they are guaranteed to happen
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	712 no matter how stable your code is. :mod:`optparse` can automatically detect
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	713 some user errors, such as bad option arguments (passing ``-n 4x`` where
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	714 ``-n`` takes an integer argument), missing arguments (``-n`` at the end
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	715 of the command line, where ``-n`` takes an argument of any type). Also,
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	716 you can call :func:`OptionParser.error` to signal an application-defined error
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	717 condition::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	718
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	719 (options, args) = parser.parse_args()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	720 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	721 if options.a and options.b:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	722 parser.error("options -a and -b are mutually exclusive")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	723
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	724 In either case, :mod:`optparse` handles the error the same way: it prints the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	725 program's usage message and an error message to standard error and exits with
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	726 error status 2.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	727
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	728 Consider the first example above, where the user passes ``4x`` to an option
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	729 that takes an integer::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	730
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	731 $ /usr/bin/foo -n 4x
68009 92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	732 Usage: foo [options]
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	733
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	734 foo: error: option -n: invalid integer value: '4x'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	735
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	736 Or, where the user fails to pass a value at all::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	737
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	738 $ /usr/bin/foo -n
68009 92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	739 Usage: foo [options]
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	740
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	741 foo: error: -n option requires an argument
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	742
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	743 :mod:`optparse`\ -generated error messages take care always to mention the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	744 option involved in the error; be sure to do the same when calling
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	745 :func:`OptionParser.error` from your application code.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	746
48321 f6726f32ef70 Merged revisions 64119,64147,64150,64165,64219-64221,64229-64230,64233,64235,64253,64278,64280,64301,64303,64320,64328,64338-64339 via svnmerge from Amaury Forgeot d'Arc <amauryfa@gmail.com> parents: 46664 diff changeset	747 If :mod:`optparse`'s default error-handling behaviour does not suit your needs,
55611 4d38e51e7cdc Merged revisions 74062 via svnmerge from Georg Brandl <georg@python.org> parents: 55580 diff changeset	748 you'll need to subclass OptionParser and override its :meth:`~OptionParser.exit`
4d38e51e7cdc Merged revisions 74062 via svnmerge from Georg Brandl <georg@python.org> parents: 55580 diff changeset	749 and/or :meth:`~OptionParser.error` methods.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	750
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	751
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	752 .. _optparse-putting-it-all-together:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	753
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	754 Putting it all together
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	755 ^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	756
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	757 Here's what :mod:`optparse`\ -based scripts usually look like::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	758
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	759 from optparse import OptionParser
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	760 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	761 def main():
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	762 usage = "usage: %prog [options] arg"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	763 parser = OptionParser(usage)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	764 parser.add_option("-f", "--file", dest="filename",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	765 help="read data from FILENAME")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	766 parser.add_option("-v", "--verbose",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	767 action="store_true", dest="verbose")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	768 parser.add_option("-q", "--quiet",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	769 action="store_false", dest="verbose")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	770 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	771 (options, args) = parser.parse_args()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	772 if len(args) != 1:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	773 parser.error("incorrect number of arguments")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	774 if options.verbose:
43219 655071bf6c45 Convert all print statements in the docs. Georg Brandl <georg@python.org> parents: 43176 diff changeset	775 print("reading %s..." % options.filename)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	776 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	777
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	778 if __name__ == "__main__":
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	779 main()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	780
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	781
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	782 .. _optparse-reference-guide:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	783
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	784 Reference Guide
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	785 ---------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	786
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	787
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	788 .. _optparse-creating-parser:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	789
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	790 Creating the parser
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	791 ^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	792
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	793 The first step in using :mod:`optparse` is to create an OptionParser instance.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	794
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	795 .. class:: OptionParser(...)
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	796
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	797 The OptionParser constructor has no required arguments, but a number of
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	798 optional keyword arguments. You should always pass them as keyword
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	799 arguments, i.e. do not rely on the order in which the arguments are declared.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	800
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	801 ``usage`` (default: ``"%prog [options]"``)
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	802 The usage summary to print when your program is run incorrectly or with a
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	803 help option. When :mod:`optparse` prints the usage string, it expands
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	804 ``%prog`` to ``os.path.basename(sys.argv[0])`` (or to ``prog`` if you
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	805 passed that keyword argument). To suppress a usage message, pass the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	806 special value :data:`optparse.SUPPRESS_USAGE`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	807
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	808 ``option_list`` (default: ``[]``)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	809 A list of Option objects to populate the parser with. The options in
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	810 ``option_list`` are added after any options in ``standard_option_list`` (a
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	811 class attribute that may be set by OptionParser subclasses), but before
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	812 any version or help options. Deprecated; use :meth:`add_option` after
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	813 creating the parser instead.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	814
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	815 ``option_class`` (default: optparse.Option)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	816 Class to use when adding options to the parser in :meth:`add_option`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	817
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	818 ``version`` (default: ``None``)
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	819 A version string to print when the user supplies a version option. If you
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	820 supply a true value for ``version``, :mod:`optparse` automatically adds a
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	821 version option with the single option string ``--version``. The
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	822 substring ``%prog`` is expanded the same as for ``usage``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	823
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	824 ``conflict_handler`` (default: ``"error"``)
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	825 Specifies what to do when options with conflicting option strings are
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	826 added to the parser; see section
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	827 :ref:`optparse-conflicts-between-options`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	828
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	829 ``description`` (default: ``None``)
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	830 A paragraph of text giving a brief overview of your program.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	831 :mod:`optparse` reformats this paragraph to fit the current terminal width
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	832 and prints it when the user requests help (after ``usage``, but before the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	833 list of options).
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	834
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	835 ``formatter`` (default: a new :class:`IndentedHelpFormatter`)
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	836 An instance of optparse.HelpFormatter that will be used for printing help
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	837 text. :mod:`optparse` provides two concrete classes for this purpose:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	838 IndentedHelpFormatter and TitledHelpFormatter.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	839
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	840 ``add_help_option`` (default: ``True``)
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	841 If true, :mod:`optparse` will add a help option (with option strings ``-h``
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	842 and ``--help``) to the parser.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	843
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	844 ``prog``
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	845 The string to use when expanding ``%prog`` in ``usage`` and ``version``
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	846 instead of ``os.path.basename(sys.argv[0])``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	847
60071 bbb340501f29 Merged revisions 79333 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 58158 diff changeset	848 ``epilog`` (default: ``None``)
bbb340501f29 Merged revisions 79333 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 58158 diff changeset	849 A paragraph of help text to print after the option help.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	850
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	851 .. _optparse-populating-parser:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	852
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	853 Populating the parser
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	854 ^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	855
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	856 There are several ways to populate the parser with options. The preferred way
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	857 is by using :meth:`OptionParser.add_option`, as shown in section
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	858 :ref:`optparse-tutorial`. :meth:`add_option` can be called in one of two ways:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	859
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	860 * pass it an Option instance (as returned by :func:`make_option`)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	861
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	862 * pass it any combination of positional and keyword arguments that are
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	863 acceptable to :func:`make_option` (i.e., to the Option constructor), and it
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	864 will create the Option instance for you
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	865
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	866 The other alternative is to pass a list of pre-constructed Option instances to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	867 the OptionParser constructor, as in::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	868
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	869 option_list = [
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	870 make_option("-f", "--filename",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	871 action="store", type="string", dest="filename"),
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	872 make_option("-q", "--quiet",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	873 action="store_false", dest="verbose"),
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	874 ]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	875 parser = OptionParser(option_list=option_list)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	876
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	877 (:func:`make_option` is a factory function for creating Option instances;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	878 currently it is an alias for the Option constructor. A future version of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	879 :mod:`optparse` may split Option into several classes, and :func:`make_option`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	880 will pick the right class to instantiate. Do not instantiate Option directly.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	881
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	882
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	883 .. _optparse-defining-options:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	884
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	885 Defining options
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	886 ^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	887
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	888 Each Option instance represents a set of synonymous command-line option strings,
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	889 e.g. ``-f`` and ``--file``. You can specify any number of short or
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	890 long option strings, but you must specify at least one overall option string.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	891
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	892 The canonical way to create an :class:`Option` instance is with the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	893 :meth:`add_option` method of :class:`OptionParser`.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	894
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	895 .. method:: OptionParser.add_option(opt_str[, ...], attr=value, ...)
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	896
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	897 To define an option with only a short option string::
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	898
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	899 parser.add_option("-f", attr=value, ...)
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	900
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	901 And to define an option with only a long option string::
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	902
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	903 parser.add_option("--foo", attr=value, ...)
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	904
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	905 The keyword arguments define attributes of the new Option object. The most
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	906 important option attribute is :attr:`~Option.action`, and it largely
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	907 determines which other attributes are relevant or required. If you pass
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	908 irrelevant option attributes, or fail to pass required ones, :mod:`optparse`
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	909 raises an :exc:`OptionError` exception explaining your mistake.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	910
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	911 An option's action determines what :mod:`optparse` does when it encounters
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	912 this option on the command-line. The standard option actions hard-coded into
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	913 :mod:`optparse` are:
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	914
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	915 ``"store"``
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	916 store this option's argument (default)
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	917
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	918 ``"store_const"``
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	919 store a constant value
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	920
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	921 ``"store_true"``
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	922 store a true value
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	923
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	924 ``"store_false"``
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	925 store a false value
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	926
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	927 ``"append"``
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	928 append this option's argument to a list
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	929
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	930 ``"append_const"``
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	931 append a constant value to a list
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	932
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	933 ``"count"``
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	934 increment a counter by one
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	935
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	936 ``"callback"``
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	937 call a specified function
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	938
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	939 ``"help"``
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	940 print a usage message including all options and the documentation for them
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	941
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	942 (If you don't supply an action, the default is ``"store"``. For this action,
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	943 you may also supply :attr:`~Option.type` and :attr:`~Option.dest` option
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	944 attributes; see :ref:`optparse-standard-option-actions`.)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	945
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	946 As you can see, most actions involve storing or updating a value somewhere.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	947 :mod:`optparse` always creates a special object for this, conventionally called
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	948 ``options`` (it happens to be an instance of :class:`optparse.Values`). Option
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	949 arguments (and various other values) are stored as attributes of this object,
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	950 according to the :attr:`~Option.dest` (destination) option attribute.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	951
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	952 For example, when you call ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	953
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	954 parser.parse_args()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	955
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	956 one of the first things :mod:`optparse` does is create the ``options`` object::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	957
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	958 options = Values()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	959
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	960 If one of the options in this parser is defined with ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	961
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	962 parser.add_option("-f", "--file", action="store", type="string", dest="filename")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	963
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	964 and the command-line being parsed includes any of the following::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	965
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	966 -ffoo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	967 -f foo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	968 --file=foo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	969 --file foo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	970
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	971 then :mod:`optparse`, on seeing this option, will do the equivalent of ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	972
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	973 options.filename = "foo"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	974
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	975 The :attr:`~Option.type` and :attr:`~Option.dest` option attributes are almost
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	976 as important as :attr:`~Option.action`, but :attr:`~Option.action` is the only
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	977 one that makes sense for all options.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	978
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	979
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	980 .. _optparse-option-attributes:
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	981
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	982 Option attributes
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	983 ^^^^^^^^^^^^^^^^^
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	984
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	985 The following option attributes may be passed as keyword arguments to
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	986 :meth:`OptionParser.add_option`. If you pass an option attribute that is not
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	987 relevant to a particular option, or fail to pass a required option attribute,
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	988 :mod:`optparse` raises :exc:`OptionError`.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	989
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	990 .. attribute:: Option.action
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	991
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	992 (default: ``"store"``)
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	993
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	994 Determines :mod:`optparse`'s behaviour when this option is seen on the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	995 command line; the available options are documented :ref:`here
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	996 <optparse-standard-option-actions>`.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	997
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	998 .. attribute:: Option.type
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	999
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1000 (default: ``"string"``)
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1001
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1002 The argument type expected by this option (e.g., ``"string"`` or ``"int"``);
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1003 the available option types are documented :ref:`here
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1004 <optparse-standard-option-types>`.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1005
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1006 .. attribute:: Option.dest
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1007
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1008 (default: derived from option strings)
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1009
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1010 If the option's action implies writing or modifying a value somewhere, this
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1011 tells :mod:`optparse` where to write it: :attr:`~Option.dest` names an
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1012 attribute of the ``options`` object that :mod:`optparse` builds as it parses
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1013 the command line.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1014
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1015 .. attribute:: Option.default
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1016
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1017 The value to use for this option's destination if the option is not seen on
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1018 the command line. See also :meth:`OptionParser.set_defaults`.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1019
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1020 .. attribute:: Option.nargs
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1021
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1022 (default: 1)
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1023
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1024 How many arguments of type :attr:`~Option.type` should be consumed when this
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1025 option is seen. If > 1, :mod:`optparse` will store a tuple of values to
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1026 :attr:`~Option.dest`.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1027
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1028 .. attribute:: Option.const
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1029
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1030 For actions that store a constant value, the constant value to store.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1031
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1032 .. attribute:: Option.choices
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1033
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1034 For options of type ``"choice"``, the list of strings the user may choose
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1035 from.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1036
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1037 .. attribute:: Option.callback
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1038
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1039 For options with action ``"callback"``, the callable to call when this option
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1040 is seen. See section :ref:`optparse-option-callbacks` for detail on the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1041 arguments passed to the callable.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1042
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1043 .. attribute:: Option.callback_args
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1044 Option.callback_kwargs
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1045
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1046 Additional positional and keyword arguments to pass to ``callback`` after the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1047 four standard callback arguments.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1048
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1049 .. attribute:: Option.help
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1050
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1051 Help text to print for this option when listing all available options after
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1052 the user supplies a :attr:`~Option.help` option (such as ``--help``). If
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1053 no help text is supplied, the option will be listed without help text. To
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1054 hide this option, use the special value :data:`optparse.SUPPRESS_HELP`.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1055
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1056 .. attribute:: Option.metavar
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1057
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1058 (default: derived from option strings)
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1059
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1060 Stand-in for the option argument(s) to use when printing help text. See
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1061 section :ref:`optparse-tutorial` for an example.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1062
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1063
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1064 .. _optparse-standard-option-actions:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1065
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1066 Standard option actions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1067 ^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1068
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1069 The various option actions all have slightly different requirements and effects.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1070 Most actions have several relevant option attributes which you may specify to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1071 guide :mod:`optparse`'s behaviour; a few have required attributes, which you
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1072 must specify for any option using that action.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1073
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1074 * ``"store"`` [relevant: :attr:`~Option.type`, :attr:`~Option.dest`,
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1075 :attr:`~Option.nargs`, :attr:`~Option.choices`]
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1076
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1077 The option must be followed by an argument, which is converted to a value
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1078 according to :attr:`~Option.type` and stored in :attr:`~Option.dest`. If
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1079 :attr:`~Option.nargs` > 1, multiple arguments will be consumed from the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1080 command line; all will be converted according to :attr:`~Option.type` and
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1081 stored to :attr:`~Option.dest` as a tuple. See the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1082 :ref:`optparse-standard-option-types` section.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1083
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1084 If :attr:`~Option.choices` is supplied (a list or tuple of strings), the type
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1085 defaults to ``"choice"``.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1086
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1087 If :attr:`~Option.type` is not supplied, it defaults to ``"string"``.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1088
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1089 If :attr:`~Option.dest` is not supplied, :mod:`optparse` derives a destination
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1090 from the first long option string (e.g., ``--foo-bar`` implies
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1091 ``foo_bar``). If there are no long option strings, :mod:`optparse` derives a
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1092 destination from the first short option string (e.g., ``-f`` implies ``f``).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1093
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1094 Example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1095
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1096 parser.add_option("-f")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1097 parser.add_option("-p", type="float", nargs=3, dest="point")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1098
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1099 As it parses the command line ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1100
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1101 -f foo.txt -p 1 -3.5 4 -fbar.txt
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1102
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1103 :mod:`optparse` will set ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1104
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1105 options.f = "foo.txt"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1106 options.point = (1.0, -3.5, 4.0)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1107 options.f = "bar.txt"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1108
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1109 * ``"store_const"`` [required: :attr:`~Option.const`; relevant:
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1110 :attr:`~Option.dest`]
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1111
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1112 The value :attr:`~Option.const` is stored in :attr:`~Option.dest`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1113
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1114 Example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1115
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1116 parser.add_option("-q", "--quiet",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1117 action="store_const", const=0, dest="verbose")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1118 parser.add_option("-v", "--verbose",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1119 action="store_const", const=1, dest="verbose")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1120 parser.add_option("--noisy",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1121 action="store_const", const=2, dest="verbose")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1122
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1123 If ``--noisy`` is seen, :mod:`optparse` will set ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1124
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1125 options.verbose = 2
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1126
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1127 * ``"store_true"`` [relevant: :attr:`~Option.dest`]
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1128
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1129 A special case of ``"store_const"`` that stores a true value to
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1130 :attr:`~Option.dest`.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1131
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1132 * ``"store_false"`` [relevant: :attr:`~Option.dest`]
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1133
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1134 Like ``"store_true"``, but stores a false value.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1135
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1136 Example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1137
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1138 parser.add_option("--clobber", action="store_true", dest="clobber")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1139 parser.add_option("--no-clobber", action="store_false", dest="clobber")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1140
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1141 * ``"append"`` [relevant: :attr:`~Option.type`, :attr:`~Option.dest`,
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1142 :attr:`~Option.nargs`, :attr:`~Option.choices`]
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1143
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1144 The option must be followed by an argument, which is appended to the list in
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1145 :attr:`~Option.dest`. If no default value for :attr:`~Option.dest` is
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1146 supplied, an empty list is automatically created when :mod:`optparse` first
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1147 encounters this option on the command-line. If :attr:`~Option.nargs` > 1,
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1148 multiple arguments are consumed, and a tuple of length :attr:`~Option.nargs`
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1149 is appended to :attr:`~Option.dest`.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1150
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1151 The defaults for :attr:`~Option.type` and :attr:`~Option.dest` are the same as
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1152 for the ``"store"`` action.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1153
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1154 Example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1155
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1156 parser.add_option("-t", "--tracks", action="append", type="int")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1157
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1158 If ``-t3`` is seen on the command-line, :mod:`optparse` does the equivalent
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1159 of::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1160
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1161 options.tracks = []
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1162 options.tracks.append(int("3"))
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1163
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1164 If, a little later on, ``--tracks=4`` is seen, it does::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1165
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1166 options.tracks.append(int("4"))
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1167
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1168 * ``"append_const"`` [required: :attr:`~Option.const`; relevant:
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1169 :attr:`~Option.dest`]
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1170
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1171 Like ``"store_const"``, but the value :attr:`~Option.const` is appended to
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1172 :attr:`~Option.dest`; as with ``"append"``, :attr:`~Option.dest` defaults to
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1173 ``None``, and an empty list is automatically created the first time the option
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1174 is encountered.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1175
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1176 * ``"count"`` [relevant: :attr:`~Option.dest`]
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1177
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1178 Increment the integer stored at :attr:`~Option.dest`. If no default value is
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1179 supplied, :attr:`~Option.dest` is set to zero before being incremented the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1180 first time.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1181
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1182 Example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1183
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1184 parser.add_option("-v", action="count", dest="verbosity")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1185
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1186 The first time ``-v`` is seen on the command line, :mod:`optparse` does the
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1187 equivalent of::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1188
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1189 options.verbosity = 0
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1190 options.verbosity += 1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1191
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1192 Every subsequent occurrence of ``-v`` results in ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1193
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1194 options.verbosity += 1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1195
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1196 * ``"callback"`` [required: :attr:`~Option.callback`; relevant:
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1197 :attr:`~Option.type`, :attr:`~Option.nargs`, :attr:`~Option.callback_args`,
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1198 :attr:`~Option.callback_kwargs`]
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1199
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1200 Call the function specified by :attr:`~Option.callback`, which is called as ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1201
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1202 func(option, opt_str, value, parser, args, *kwargs)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1203
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1204 See section :ref:`optparse-option-callbacks` for more detail.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1205
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1206 * ``"help"``
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1207
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1208 Prints a complete help message for all the options in the current option
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1209 parser. The help message is constructed from the ``usage`` string passed to
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1210 OptionParser's constructor and the :attr:`~Option.help` string passed to every
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1211 option.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1212
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1213 If no :attr:`~Option.help` string is supplied for an option, it will still be
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1214 listed in the help message. To omit an option entirely, use the special value
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1215 :data:`optparse.SUPPRESS_HELP`.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1216
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1217 :mod:`optparse` automatically adds a :attr:`~Option.help` option to all
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1218 OptionParsers, so you do not normally need to create one.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1219
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1220 Example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1221
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1222 from optparse import OptionParser, SUPPRESS_HELP
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1223
56002 fa91270b6087 Merged revisions 74821,74828-74831,74833,74835 via svnmerge from Georg Brandl <georg@python.org> parents: 55797 diff changeset	1224 # usually, a help option is added automatically, but that can
fa91270b6087 Merged revisions 74821,74828-74831,74833,74835 via svnmerge from Georg Brandl <georg@python.org> parents: 55797 diff changeset	1225 # be suppressed using the add_help_option argument
fa91270b6087 Merged revisions 74821,74828-74831,74833,74835 via svnmerge from Georg Brandl <georg@python.org> parents: 55797 diff changeset	1226 parser = OptionParser(add_help_option=False)
fa91270b6087 Merged revisions 74821,74828-74831,74833,74835 via svnmerge from Georg Brandl <georg@python.org> parents: 55797 diff changeset	1227
fa91270b6087 Merged revisions 74821,74828-74831,74833,74835 via svnmerge from Georg Brandl <georg@python.org> parents: 55797 diff changeset	1228 parser.add_option("-h", "--help", action="help")
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1229 parser.add_option("-v", action="store_true", dest="verbose",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1230 help="Be moderately verbose")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1231 parser.add_option("--file", dest="filename",
56002 fa91270b6087 Merged revisions 74821,74828-74831,74833,74835 via svnmerge from Georg Brandl <georg@python.org> parents: 55797 diff changeset	1232 help="Input file to read data from")
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1233 parser.add_option("--secret", help=SUPPRESS_HELP)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1234
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1235 If :mod:`optparse` sees either ``-h`` or ``--help`` on the command line,
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1236 it will print something like the following help message to stdout (assuming
58119 e54434d2e2a7 Merged revisions 77269 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58026 diff changeset	1237 ``sys.argv[0]`` is ``"foo.py"``):
e54434d2e2a7 Merged revisions 77269 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58026 diff changeset	1238
e54434d2e2a7 Merged revisions 77269 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58026 diff changeset	1239 .. code-block:: text
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1240
68009 92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	1241 Usage: foo.py [options]
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	1242
92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	1243 Options:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1244 -h, --help Show this help message and exit
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1245 -v Be moderately verbose
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1246 --file=FILENAME Input file to read data from
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1247
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1248 After printing the help message, :mod:`optparse` terminates your process with
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1249 ``sys.exit(0)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1250
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1251 * ``"version"``
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1252
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1253 Prints the version number supplied to the OptionParser to stdout and exits.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1254 The version number is actually formatted and printed by the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1255 ``print_version()`` method of OptionParser. Generally only relevant if the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1256 ``version`` argument is supplied to the OptionParser constructor. As with
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1257 :attr:`~Option.help` options, you will rarely create ``version`` options,
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1258 since :mod:`optparse` automatically adds them when needed.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1259
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1260
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1261 .. _optparse-standard-option-types:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1262
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1263 Standard option types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1264 ^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1265
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1266 :mod:`optparse` has five built-in option types: ``"string"``, ``"int"``,
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1267 ``"choice"``, ``"float"`` and ``"complex"``. If you need to add new
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1268 option types, see section :ref:`optparse-extending-optparse`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1269
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1270 Arguments to string options are not checked or converted in any way: the text on
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1271 the command line is stored in the destination (or passed to the callback) as-is.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1272
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1273 Integer arguments (type ``"int"``) are parsed as follows:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1274
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1275 * if the number starts with ``0x``, it is parsed as a hexadecimal number
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1276
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1277 * if the number starts with ``0``, it is parsed as an octal number
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1278
43737 3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43219 diff changeset	1279 * if the number starts with ``0b``, it is parsed as a binary number
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1280
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1281 * otherwise, the number is parsed as a decimal number
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1282
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1283
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1284 The conversion is done by calling :func:`int` with the appropriate base (2, 8,
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1285 10, or 16). If this fails, so will :mod:`optparse`, although with a more useful
44053 f2385d98282a Remove further mentions of long integers. Georg Brandl <georg@python.org> parents: 43737 diff changeset	1286 error message.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1287
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1288 ``"float"`` and ``"complex"`` option arguments are converted directly with
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1289 :func:`float` and :func:`complex`, with similar error-handling.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1290
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1291 ``"choice"`` options are a subtype of ``"string"`` options. The
65143 d672753a03f0 Merged revisions 85274 via svnmerge from Georg Brandl <georg@python.org> parents: 63441 diff changeset	1292 :attr:`~Option.choices` option attribute (a sequence of strings) defines the
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1293 set of allowed option arguments. :func:`optparse.check_choice` compares
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1294 user-supplied option arguments against this master list and raises
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1295 :exc:`OptionValueError` if an invalid string is given.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1296
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1297
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1298 .. _optparse-parsing-arguments:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1299
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1300 Parsing arguments
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1301 ^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1302
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1303 The whole point of creating and populating an OptionParser is to call its
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1304 :meth:`parse_args` method::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1305
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1306 (options, args) = parser.parse_args(args=None, values=None)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1307
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1308 where the input parameters are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1309
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1310 ``args``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1311 the list of arguments to process (default: ``sys.argv[1:]``)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1312
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1313 ``values``
63441 bc66e1566a19 Merged revisions 83385-83389,83391 via svnmerge from Georg Brandl <georg@python.org> parents: 60071 diff changeset	1314 a :class:`optparse.Values` object to store option arguments in (default: a
bc66e1566a19 Merged revisions 83385-83389,83391 via svnmerge from Georg Brandl <georg@python.org> parents: 60071 diff changeset	1315 new instance of :class:`Values`) -- if you give an existing object, the
bc66e1566a19 Merged revisions 83385-83389,83391 via svnmerge from Georg Brandl <georg@python.org> parents: 60071 diff changeset	1316 option defaults will not be initialized on it
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1317
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1318 and the return values are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1319
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1320 ``options``
55797 afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from Georg Brandl <georg@python.org> parents: 55611 diff changeset	1321 the same object that was passed in as ``values``, or the optparse.Values
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1322 instance created by :mod:`optparse`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1323
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1324 ``args``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1325 the leftover positional arguments after all options have been processed
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1326
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1327 The most common usage is to supply neither keyword argument. If you supply
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1328 ``values``, it will be modified with repeated :func:`setattr` calls (roughly one
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1329 for every option argument stored to an option destination) and returned by
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1330 :meth:`parse_args`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1331
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1332 If :meth:`parse_args` encounters any errors in the argument list, it calls the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1333 OptionParser's :meth:`error` method with an appropriate end-user error message.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1334 This ultimately terminates your process with an exit status of 2 (the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1335 traditional Unix exit status for command-line errors).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1336
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1337
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1338 .. _optparse-querying-manipulating-option-parser:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1339
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1340 Querying and manipulating your option parser
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1341 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1342
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1343 The default behavior of the option parser can be customized slightly, and you
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1344 can also poke around your option parser and see what's there. OptionParser
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1345 provides several methods to help you out:
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1346
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1347 .. method:: OptionParser.disable_interspersed_args()
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1348
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1349 Set parsing to stop on the first non-option. For example, if ``-a`` and
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1350 ``-b`` are both simple options that take no arguments, :mod:`optparse`
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1351 normally accepts this syntax::
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1352
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1353 prog -a arg1 -b arg2
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1354
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1355 and treats it as equivalent to ::
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1356
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1357 prog -a -b arg1 arg2
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1358
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1359 To disable this feature, call :meth:`disable_interspersed_args`. This
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1360 restores traditional Unix syntax, where option parsing stops with the first
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1361 non-option argument.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1362
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1363 Use this if you have a command processor which runs another command which has
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1364 options of its own and you want to make sure these options don't get
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1365 confused. For example, each command might have a different set of options.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1366
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1367 .. method:: OptionParser.enable_interspersed_args()
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1368
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1369 Set parsing to not stop on the first non-option, allowing interspersing
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1370 switches with command arguments. This is the default behavior.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1371
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1372 .. method:: OptionParser.get_option(opt_str)
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1373
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1374 Returns the Option instance with the option string opt_str, or ``None`` if
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1375 no options have that option string.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1376
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1377 .. method:: OptionParser.has_option(opt_str)
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1378
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1379 Return true if the OptionParser has an option with option string opt_str
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1380 (e.g., ``-q`` or ``--verbose``).
49327 4844cac08652 Devil merge! Benjamin Peterson <benjamin@python.org> parents: 49095 diff changeset	1381
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1382 .. method:: OptionParser.remove_option(opt_str)
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1383
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1384 If the :class:`OptionParser` has an option corresponding to opt_str, that
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1385 option is removed. If that option provided any other option strings, all of
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1386 those option strings become invalid. If opt_str does not occur in any
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1387 option belonging to this :class:`OptionParser`, raises :exc:`ValueError`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1388
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1389
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1390 .. _optparse-conflicts-between-options:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1391
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1392 Conflicts between options
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1393 ^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1394
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1395 If you're not careful, it's easy to define options with conflicting option
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1396 strings::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1397
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1398 parser.add_option("-n", "--dry-run", ...)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1399 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1400 parser.add_option("-n", "--noisy", ...)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1401
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1402 (This is particularly true if you've defined your own OptionParser subclass with
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1403 some standard options.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1404
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1405 Every time you add an option, :mod:`optparse` checks for conflicts with existing
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1406 options. If it finds any, it invokes the current conflict-handling mechanism.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1407 You can set the conflict-handling mechanism either in the constructor::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1408
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1409 parser = OptionParser(..., conflict_handler=handler)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1410
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1411 or with a separate call::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1412
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1413 parser.set_conflict_handler(handler)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1414
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1415 The available conflict handlers are:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1416
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1417 ``"error"`` (default)
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1418 assume option conflicts are a programming error and raise
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1419 :exc:`OptionConflictError`
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1420
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1421 ``"resolve"``
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1422 resolve option conflicts intelligently (see below)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1423
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1424
49433 8f5a8ea5ba76 Merged revisions 66670,66681,66688,66696-66699 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49327 diff changeset	1425 As an example, let's define an :class:`OptionParser` that resolves conflicts
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1426 intelligently and add conflicting options to it::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1427
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1428 parser = OptionParser(conflict_handler="resolve")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1429 parser.add_option("-n", "--dry-run", ..., help="do no harm")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1430 parser.add_option("-n", "--noisy", ..., help="be noisy")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1431
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1432 At this point, :mod:`optparse` detects that a previously-added option is already
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1433 using the ``-n`` option string. Since ``conflict_handler`` is ``"resolve"``,
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1434 it resolves the situation by removing ``-n`` from the earlier option's list of
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1435 option strings. Now ``--dry-run`` is the only way for the user to activate
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1436 that option. If the user asks for help, the help message will reflect that::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1437
68009 92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	1438 Options:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1439 --dry-run do no harm
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1440 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1441 -n, --noisy be noisy
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1442
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1443 It's possible to whittle away the option strings for a previously-added option
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1444 until there are none left, and the user has no way of invoking that option from
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1445 the command-line. In that case, :mod:`optparse` removes that option completely,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1446 so it doesn't show up in help text or anywhere else. Carrying on with our
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1447 existing OptionParser::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1448
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1449 parser.add_option("--dry-run", ..., help="new dry-run option")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1450
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1451 At this point, the original ``-n``/``--dry-run`` option is no longer
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1452 accessible, so :mod:`optparse` removes it, leaving this help text::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1453
68009 92629ccaae76 Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66959 diff changeset	1454 Options:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1455 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1456 -n, --noisy be noisy
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1457 --dry-run new dry-run option
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1458
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1459
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1460 .. _optparse-cleanup:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1461
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1462 Cleanup
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1463 ^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1464
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1465 OptionParser instances have several cyclic references. This should not be a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1466 problem for Python's garbage collector, but you may wish to break the cyclic
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1467 references explicitly by calling :meth:`~OptionParser.destroy` on your
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1468 OptionParser once you are done with it. This is particularly useful in
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1469 long-running applications where large object graphs are reachable from your
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1470 OptionParser.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1471
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1472
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1473 .. _optparse-other-methods:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1474
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1475 Other methods
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1476 ^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1477
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1478 OptionParser supports several other public methods:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1479
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1480 .. method:: OptionParser.set_usage(usage)
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1481
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1482 Set the usage string according to the rules described above for the ``usage``
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1483 constructor keyword argument. Passing ``None`` sets the default usage
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1484 string; use :data:`optparse.SUPPRESS_USAGE` to suppress a usage message.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1485
58158 fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	1486 .. method:: OptionParser.print_usage(file=None)
fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	1487
fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	1488 Print the usage message for the current program (``self.usage``) to file
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1489 (default stdout). Any occurrence of the string ``%prog`` in ``self.usage``
58158 fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	1490 is replaced with the name of the current program. Does nothing if
fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	1491 ``self.usage`` is empty or not defined.
fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	1492
fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	1493 .. method:: OptionParser.get_usage()
fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	1494
fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	1495 Same as :meth:`print_usage` but returns the usage string instead of
fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	1496 printing it.
fa2b27fa5419 Merged revisions 77308 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58119 diff changeset	1497
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1498 .. method:: OptionParser.set_defaults(dest=value, ...)
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1499
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1500 Set default values for several option destinations at once. Using
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1501 :meth:`set_defaults` is the preferred way to set default values for options,
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1502 since multiple options can share the same destination. For example, if
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1503 several "mode" options all set the same destination, any one of them can set
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1504 the default, and the last one wins::
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1505
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1506 parser.add_option("--advanced", action="store_const",
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1507 dest="mode", const="advanced",
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1508 default="novice") # overridden below
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1509 parser.add_option("--novice", action="store_const",
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1510 dest="mode", const="novice",
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1511 default="advanced") # overrides above setting
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1512
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1513 To avoid this confusion, use :meth:`set_defaults`::
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1514
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1515 parser.set_defaults(mode="advanced")
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1516 parser.add_option("--advanced", action="store_const",
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1517 dest="mode", const="advanced")
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1518 parser.add_option("--novice", action="store_const",
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1519 dest="mode", const="novice")
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1520
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1521
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1522 .. _optparse-option-callbacks:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1523
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1524 Option Callbacks
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1525 ----------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1526
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1527 When :mod:`optparse`'s built-in actions and types aren't quite enough for your
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1528 needs, you have two choices: extend :mod:`optparse` or define a callback option.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1529 Extending :mod:`optparse` is more general, but overkill for a lot of simple
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1530 cases. Quite often a simple callback is all you need.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1531
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1532 There are two steps to defining a callback option:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1533
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1534 * define the option itself using the ``"callback"`` action
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1535
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1536 * write the callback; this is a function (or method) that takes at least four
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1537 arguments, as described below
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1538
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1539
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1540 .. _optparse-defining-callback-option:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1541
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1542 Defining a callback option
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1543 ^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1544
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1545 As always, the easiest way to define a callback option is by using the
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1546 :meth:`OptionParser.add_option` method. Apart from :attr:`~Option.action`, the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1547 only option attribute you must specify is ``callback``, the function to call::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1548
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1549 parser.add_option("-c", action="callback", callback=my_callback)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1550
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1551 ``callback`` is a function (or other callable object), so you must have already
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1552 defined ``my_callback()`` when you create this callback option. In this simple
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1553 case, :mod:`optparse` doesn't even know if ``-c`` takes any arguments,
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1554 which usually means that the option takes no arguments---the mere presence of
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1555 ``-c`` on the command-line is all it needs to know. In some
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1556 circumstances, though, you might want your callback to consume an arbitrary
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1557 number of command-line arguments. This is where writing callbacks gets tricky;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1558 it's covered later in this section.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1559
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1560 :mod:`optparse` always passes four particular arguments to your callback, and it
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1561 will only pass additional arguments if you specify them via
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1562 :attr:`~Option.callback_args` and :attr:`~Option.callback_kwargs`. Thus, the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1563 minimal callback function signature is::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1564
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1565 def my_callback(option, opt, value, parser):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1566
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1567 The four arguments to a callback are described below.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1568
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1569 There are several other option attributes that you can supply when you define a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1570 callback option:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1571
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1572 :attr:`~Option.type`
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1573 has its usual meaning: as with the ``"store"`` or ``"append"`` actions, it
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1574 instructs :mod:`optparse` to consume one argument and convert it to
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1575 :attr:`~Option.type`. Rather than storing the converted value(s) anywhere,
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1576 though, :mod:`optparse` passes it to your callback function.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1577
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1578 :attr:`~Option.nargs`
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1579 also has its usual meaning: if it is supplied and > 1, :mod:`optparse` will
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1580 consume :attr:`~Option.nargs` arguments, each of which must be convertible to
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1581 :attr:`~Option.type`. It then passes a tuple of converted values to your
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1582 callback.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1583
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1584 :attr:`~Option.callback_args`
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1585 a tuple of extra positional arguments to pass to the callback
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1586
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1587 :attr:`~Option.callback_kwargs`
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1588 a dictionary of extra keyword arguments to pass to the callback
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1589
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1590
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1591 .. _optparse-how-callbacks-called:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1592
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1593 How callbacks are called
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1594 ^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1595
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1596 All callbacks are called as follows::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1597
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1598 func(option, opt_str, value, parser, args, *kwargs)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1599
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1600 where
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1601
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1602 ``option``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1603 is the Option instance that's calling the callback
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1604
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1605 ``opt_str``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1606 is the option string seen on the command-line that's triggering the callback.
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1607 (If an abbreviated long option was used, ``opt_str`` will be the full,
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1608 canonical option string---e.g. if the user puts ``--foo`` on the
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1609 command-line as an abbreviation for ``--foobar``, then ``opt_str`` will be
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1610 ``"--foobar"``.)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1611
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1612 ``value``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1613 is the argument to this option seen on the command-line. :mod:`optparse` will
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1614 only expect an argument if :attr:`~Option.type` is set; the type of ``value`` will be
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1615 the type implied by the option's type. If :attr:`~Option.type` for this option is
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1616 ``None`` (no argument expected), then ``value`` will be ``None``. If :attr:`~Option.nargs`
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1617 > 1, ``value`` will be a tuple of values of the appropriate type.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1618
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1619 ``parser``
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1620 is the OptionParser instance driving the whole thing, mainly useful because
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1621 you can access some other interesting data through its instance attributes:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1622
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1623 ``parser.largs``
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1624 the current list of leftover arguments, ie. arguments that have been
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1625 consumed but are neither options nor option arguments. Feel free to modify
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1626 ``parser.largs``, e.g. by adding more arguments to it. (This list will
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1627 become ``args``, the second return value of :meth:`parse_args`.)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1628
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1629 ``parser.rargs``
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1630 the current list of remaining arguments, ie. with ``opt_str`` and
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1631 ``value`` (if applicable) removed, and only the arguments following them
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1632 still there. Feel free to modify ``parser.rargs``, e.g. by consuming more
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1633 arguments.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1634
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1635 ``parser.values``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1636 the object where option values are by default stored (an instance of
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1637 optparse.OptionValues). This lets callbacks use the same mechanism as the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1638 rest of :mod:`optparse` for storing option values; you don't need to mess
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1639 around with globals or closures. You can also access or modify the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1640 value(s) of any options already encountered on the command-line.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1641
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1642 ``args``
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1643 is a tuple of arbitrary positional arguments supplied via the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1644 :attr:`~Option.callback_args` option attribute.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1645
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1646 ``kwargs``
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1647 is a dictionary of arbitrary keyword arguments supplied via
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1648 :attr:`~Option.callback_kwargs`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1649
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1650
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1651 .. _optparse-raising-errors-in-callback:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1652
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1653 Raising errors in a callback
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1654 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1655
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1656 The callback function should raise :exc:`OptionValueError` if there are any
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1657 problems with the option or its argument(s). :mod:`optparse` catches this and
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1658 terminates the program, printing the error message you supply to stderr. Your
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1659 message should be clear, concise, accurate, and mention the option at fault.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1660 Otherwise, the user will have a hard time figuring out what he did wrong.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1661
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1662
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1663 .. _optparse-callback-example-1:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1664
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1665 Callback example 1: trivial callback
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1666 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1667
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1668 Here's an example of a callback option that takes no arguments, and simply
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1669 records that the option was seen::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1670
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1671 def record_foo_seen(option, opt_str, value, parser):
51384 7a0525613644 Merged revisions 69350 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50571 diff changeset	1672 parser.values.saw_foo = True
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1673
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1674 parser.add_option("--foo", action="callback", callback=record_foo_seen)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1675
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1676 Of course, you could do that with the ``"store_true"`` action.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1677
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1678
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1679 .. _optparse-callback-example-2:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1680
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1681 Callback example 2: check option order
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1682 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1683
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1684 Here's a slightly more interesting example: record the fact that ``-a`` is
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1685 seen, but blow up if it comes after ``-b`` in the command-line. ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1686
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1687 def check_order(option, opt_str, value, parser):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1688 if parser.values.b:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1689 raise OptionValueError("can't use -a after -b")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1690 parser.values.a = 1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1691 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1692 parser.add_option("-a", action="callback", callback=check_order)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1693 parser.add_option("-b", action="store_true", dest="b")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1694
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1695
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1696 .. _optparse-callback-example-3:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1697
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1698 Callback example 3: check option order (generalized)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1699 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1700
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1701 If you want to re-use this callback for several similar options (set a flag, but
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1702 blow up if ``-b`` has already been seen), it needs a bit of work: the error
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1703 message and the flag that it sets must be generalized. ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1704
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1705 def check_order(option, opt_str, value, parser):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1706 if parser.values.b:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1707 raise OptionValueError("can't use %s after -b" % opt_str)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1708 setattr(parser.values, option.dest, 1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1709 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1710 parser.add_option("-a", action="callback", callback=check_order, dest='a')
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1711 parser.add_option("-b", action="store_true", dest="b")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1712 parser.add_option("-c", action="callback", callback=check_order, dest='c')
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1713
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1714
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1715 .. _optparse-callback-example-4:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1716
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1717 Callback example 4: check arbitrary condition
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1718 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1719
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1720 Of course, you could put any condition in there---you're not limited to checking
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1721 the values of already-defined options. For example, if you have options that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1722 should not be called when the moon is full, all you have to do is this::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1723
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1724 def check_moon(option, opt_str, value, parser):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1725 if is_moon_full():
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1726 raise OptionValueError("%s option invalid when moon is full"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1727 % opt_str)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1728 setattr(parser.values, option.dest, 1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1729 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1730 parser.add_option("--foo",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1731 action="callback", callback=check_moon, dest="foo")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1732
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1733 (The definition of ``is_moon_full()`` is left as an exercise for the reader.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1734
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1735
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1736 .. _optparse-callback-example-5:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1737
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1738 Callback example 5: fixed arguments
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1739 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1740
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1741 Things get slightly more interesting when you define callback options that take
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1742 a fixed number of arguments. Specifying that a callback option takes arguments
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1743 is similar to defining a ``"store"`` or ``"append"`` option: if you define
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1744 :attr:`~Option.type`, then the option takes one argument that must be
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1745 convertible to that type; if you further define :attr:`~Option.nargs`, then the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1746 option takes :attr:`~Option.nargs` arguments.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1747
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1748 Here's an example that just emulates the standard ``"store"`` action::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1749
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1750 def store_value(option, opt_str, value, parser):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1751 setattr(parser.values, option.dest, value)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1752 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1753 parser.add_option("--foo",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1754 action="callback", callback=store_value,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1755 type="int", nargs=3, dest="foo")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1756
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1757 Note that :mod:`optparse` takes care of consuming 3 arguments and converting
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1758 them to integers for you; all you have to do is store them. (Or whatever;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1759 obviously you don't need a callback for this example.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1760
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1761
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1762 .. _optparse-callback-example-6:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1763
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1764 Callback example 6: variable arguments
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1765 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1766
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1767 Things get hairy when you want an option to take a variable number of arguments.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1768 For this case, you must write a callback, as :mod:`optparse` doesn't provide any
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1769 built-in capabilities for it. And you have to deal with certain intricacies of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1770 conventional Unix command-line parsing that :mod:`optparse` normally handles for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1771 you. In particular, callbacks should implement the conventional rules for bare
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1772 ``--`` and ``-`` arguments:
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1773
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1774 * either ``--`` or ``-`` can be option arguments
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1775
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1776 * bare ``--`` (if not the argument to some option): halt command-line
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1777 processing and discard the ``--``
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1778
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1779 * bare ``-`` (if not the argument to some option): halt command-line
0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1780 processing but keep the ``-`` (append it to ``parser.largs``)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1781
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1782 If you want an option that takes a variable number of arguments, there are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1783 several subtle, tricky issues to worry about. The exact implementation you
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1784 choose will be based on which trade-offs you're willing to make for your
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1785 application (which is why :mod:`optparse` doesn't support this sort of thing
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1786 directly).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1787
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1788 Nevertheless, here's a stab at a callback for an option with variable
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1789 arguments::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1790
50250 1adfabcbe073 Merged revisions 67886-67887 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49433 diff changeset	1791 def vararg_callback(option, opt_str, value, parser):
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49433 diff changeset	1792 assert value is None
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49433 diff changeset	1793 value = []
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49433 diff changeset	1794
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49433 diff changeset	1795 def floatable(str):
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49433 diff changeset	1796 try:
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49433 diff changeset	1797 float(str)
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49433 diff changeset	1798 return True
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49433 diff changeset	1799 except ValueError:
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49433 diff changeset	1800 return False
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49433 diff changeset	1801
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49433 diff changeset	1802 for arg in parser.rargs:
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49433 diff changeset	1803 # stop on --foo like options
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49433 diff changeset	1804 if arg[:2] == "--" and len(arg) > 2:
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49433 diff changeset	1805 break
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49433 diff changeset	1806 # stop on -a, but not on -3 or -3.0
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49433 diff changeset	1807 if arg[:1] == "-" and len(arg) > 1 and not floatable(arg):
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49433 diff changeset	1808 break
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49433 diff changeset	1809 value.append(arg)
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49433 diff changeset	1810
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49433 diff changeset	1811 del parser.rargs[:len(value)]
51384 7a0525613644 Merged revisions 69350 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50571 diff changeset	1812 setattr(parser.values, option.dest, value)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1813
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1814 [...]
49095 4d148bb84a07 Merged revisions 66141,66145,66150,66180,66211,66217,66219,66226,66231,66244,66246,66249-66250,66264,66268,66272,66294,66306 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48321 diff changeset	1815 parser.add_option("-c", "--callback", dest="vararg_attr",
46664 031dfe455585 Merged revisions 62425-62429,62434-62436,62441,62444,62446-62448,62450-62455,62463,62465-62466,62469,62474,62476-62478,62480,62485,62492,62497-62498,62500,62507,62513-62514,62516,62521,62531,62535,62545-62546,62548-62551,62553-62559,62569,62574,62577,62593,62595,62604-62606,62608,62616,62626-62627,62636,62638,62644-62645,62647-62648,62651-62653,62656,62661,62663,62680,62686-62687,62696,62699-62703,62711 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45435 diff changeset	1816 action="callback", callback=vararg_callback)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1817
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1818
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1819 .. _optparse-extending-optparse:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1820
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1821 Extending :mod:`optparse`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1822 -------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1823
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1824 Since the two major controlling factors in how :mod:`optparse` interprets
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1825 command-line options are the action and type of each option, the most likely
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1826 direction of extension is to add new actions and new types.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1827
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1828
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1829 .. _optparse-adding-new-types:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1830
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1831 Adding new types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1832 ^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1833
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1834 To add new types, you need to define your own subclass of :mod:`optparse`'s
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1835 :class:`Option` class. This class has a couple of attributes that define
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1836 :mod:`optparse`'s types: :attr:`~Option.TYPES` and :attr:`~Option.TYPE_CHECKER`.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1837
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1838 .. attribute:: Option.TYPES
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1839
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1840 A tuple of type names; in your subclass, simply define a new tuple
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1841 :attr:`TYPES` that builds on the standard one.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1842
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1843 .. attribute:: Option.TYPE_CHECKER
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1844
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1845 A dictionary mapping type names to type-checking functions. A type-checking
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1846 function has the following signature::
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1847
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1848 def check_mytype(option, opt, value)
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1849
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1850 where ``option`` is an :class:`Option` instance, ``opt`` is an option string
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1851 (e.g., ``-f``), and ``value`` is the string from the command line that must
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1852 be checked and converted to your desired type. ``check_mytype()`` should
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1853 return an object of the hypothetical type ``mytype``. The value returned by
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1854 a type-checking function will wind up in the OptionValues instance returned
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1855 by :meth:`OptionParser.parse_args`, or be passed to a callback as the
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1856 ``value`` parameter.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1857
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1858 Your type-checking function should raise :exc:`OptionValueError` if it
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1859 encounters any problems. :exc:`OptionValueError` takes a single string
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1860 argument, which is passed as-is to :class:`OptionParser`'s :meth:`error`
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1861 method, which in turn prepends the program name and the string ``"error:"``
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1862 and prints everything to stderr before terminating the process.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1863
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1864 Here's a silly example that demonstrates adding a ``"complex"`` option type to
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1865 parse Python-style complex numbers on the command line. (This is even sillier
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1866 than it used to be, because :mod:`optparse` 1.3 added built-in support for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1867 complex numbers, but never mind.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1868
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1869 First, the necessary imports::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1870
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1871 from copy import copy
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1872 from optparse import Option, OptionValueError
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1873
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1874 You need to define your type-checker first, since it's referred to later (in the
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1875 :attr:`~Option.TYPE_CHECKER` class attribute of your Option subclass)::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1876
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1877 def check_complex(option, opt, value):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1878 try:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1879 return complex(value)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1880 except ValueError:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1881 raise OptionValueError(
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1882 "option %s: invalid complex value: %r" % (opt, value))
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1883
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1884 Finally, the Option subclass::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1885
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1886 class MyOption (Option):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1887 TYPES = Option.TYPES + ("complex",)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1888 TYPE_CHECKER = copy(Option.TYPE_CHECKER)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1889 TYPE_CHECKER["complex"] = check_complex
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1890
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1891 (If we didn't make a :func:`copy` of :attr:`Option.TYPE_CHECKER`, we would end
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1892 up modifying the :attr:`~Option.TYPE_CHECKER` attribute of :mod:`optparse`'s
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1893 Option class. This being Python, nothing stops you from doing that except good
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1894 manners and common sense.)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1895
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1896 That's it! Now you can write a script that uses the new option type just like
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1897 any other :mod:`optparse`\ -based script, except you have to instruct your
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1898 OptionParser to use MyOption instead of Option::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1899
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1900 parser = OptionParser(option_class=MyOption)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1901 parser.add_option("-c", type="complex")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1902
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1903 Alternately, you can build your own option list and pass it to OptionParser; if
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1904 you don't use :meth:`add_option` in the above way, you don't need to tell
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1905 OptionParser which option class to use::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1906
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1907 option_list = [MyOption("-c", action="store", type="complex", dest="c")]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1908 parser = OptionParser(option_list=option_list)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1909
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1910
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1911 .. _optparse-adding-new-actions:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1912
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1913 Adding new actions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1914 ^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1915
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1916 Adding new actions is a bit trickier, because you have to understand that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1917 :mod:`optparse` has a couple of classifications for actions:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1918
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1919 "store" actions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1920 actions that result in :mod:`optparse` storing a value to an attribute of the
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1921 current OptionValues instance; these options require a :attr:`~Option.dest`
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1922 attribute to be supplied to the Option constructor.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1923
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1924 "typed" actions
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1925 actions that take a value from the command line and expect it to be of a
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1926 certain type; or rather, a string that can be converted to a certain type.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1927 These options require a :attr:`~Option.type` attribute to the Option
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1928 constructor.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1929
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1930 These are overlapping sets: some default "store" actions are ``"store"``,
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1931 ``"store_const"``, ``"append"``, and ``"count"``, while the default "typed"
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1932 actions are ``"store"``, ``"append"``, and ``"callback"``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1933
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1934 When you add an action, you need to categorize it by listing it in at least one
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1935 of the following class attributes of Option (all are lists of strings):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1936
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1937 .. attribute:: Option.ACTIONS
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1938
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1939 All actions must be listed in ACTIONS.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1940
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1941 .. attribute:: Option.STORE_ACTIONS
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1942
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1943 "store" actions are additionally listed here.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1944
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1945 .. attribute:: Option.TYPED_ACTIONS
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1946
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1947 "typed" actions are additionally listed here.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1948
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1949 .. attribute:: Option.ALWAYS_TYPED_ACTIONS
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1950
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1951 Actions that always take a type (i.e. whose options always take a value) are
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1952 additionally listed here. The only effect of this is that :mod:`optparse`
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1953 assigns the default type, ``"string"``, to options with no explicit type
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1954 whose action is listed in :attr:`ALWAYS_TYPED_ACTIONS`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1955
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1956 In order to actually implement your new action, you must override Option's
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1957 :meth:`take_action` method and add a case that recognizes your action.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1958
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1959 For example, let's add an ``"extend"`` action. This is similar to the standard
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1960 ``"append"`` action, but instead of taking a single value from the command-line
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1961 and appending it to an existing list, ``"extend"`` will take multiple values in
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1962 a single comma-delimited string, and extend an existing list with them. That
66959 0037d65debd8 Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65143 diff changeset	1963 is, if ``--names`` is an ``"extend"`` option of type ``"string"``, the command
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1964 line ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1965
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1966 --names=foo,bar --names blah --names ding,dong
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1967
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1968 would result in a list ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1969
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1970 ["foo", "bar", "blah", "ding", "dong"]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1971
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1972 Again we define a subclass of Option::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1973
58119 e54434d2e2a7 Merged revisions 77269 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58026 diff changeset	1974 class MyOption(Option):
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1975
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1976 ACTIONS = Option.ACTIONS + ("extend",)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1977 STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1978 TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1979 ALWAYS_TYPED_ACTIONS = Option.ALWAYS_TYPED_ACTIONS + ("extend",)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1980
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1981 def take_action(self, action, dest, opt, value, values, parser):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1982 if action == "extend":
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1983 lvalue = value.split(",")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1984 values.ensure_value(dest, []).extend(lvalue)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1985 else:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1986 Option.take_action(
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1987 self, action, dest, opt, value, values, parser)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1988
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1989 Features of note:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1990
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1991 * ``"extend"`` both expects a value on the command-line and stores that value
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1992 somewhere, so it goes in both :attr:`~Option.STORE_ACTIONS` and
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1993 :attr:`~Option.TYPED_ACTIONS`.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1994
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1995 * to ensure that :mod:`optparse` assigns the default type of ``"string"`` to
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1996 ``"extend"`` actions, we put the ``"extend"`` action in
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	1997 :attr:`~Option.ALWAYS_TYPED_ACTIONS` as well.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1998
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1999 * :meth:`MyOption.take_action` implements just this one new action, and passes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2000 control back to :meth:`Option.take_action` for the standard :mod:`optparse`
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	2001 actions.
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	2002
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	2003 * ``values`` is an instance of the optparse_parser.Values class, which provides
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	2004 the very useful :meth:`ensure_value` method. :meth:`ensure_value` is
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	2005 essentially :func:`getattr` with a safety valve; it is called as ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2006
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2007 values.ensure_value(attr, value)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2008
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2009 If the ``attr`` attribute of ``values`` doesn't exist or is None, then
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	2010 ensure_value() first sets it to ``value``, and then returns 'value. This is
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	2011 very handy for actions like ``"extend"``, ``"append"``, and ``"count"``, all
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	2012 of which accumulate data in a variable and expect that variable to be of a
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	2013 certain type (a list for the first two, an integer for the latter). Using
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2014 :meth:`ensure_value` means that scripts using your action don't have to worry
56054 547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	2015 about setting a default value for the option destinations in question; they
547d41b1de97 Merged revisions 74889 via svnmerge from Georg Brandl <georg@python.org> parents: 56002 diff changeset	2016 can just leave the default as None and :meth:`ensure_value` will take care of
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2017 getting it right when it's needed.

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/optparse.rst @ 78069:a8aa77458e12 3.2