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

annotate Doc/library/optparse.rst @ 79675:c0a2294de787 2.7

Issue #16199: Backport 2to3 typo fix from 3.2.

author	Chris Jerdonek <chris.jerdonek@gmail.com>
date	Thu, 11 Oct 2012 16:15:46 -0700
parents	2291aff20a05
children	488957f9b664

rev	line source
59257 83ef67526011 Initial commit of the argparse library, based on argparse 1.1. Steven Bethard <steven.bethard@gmail.com> parents: 58155 diff changeset	1 :mod:`optparse` --- Parser for command line options
83ef67526011 Initial commit of the argparse library, based on argparse 1.1. Steven Bethard <steven.bethard@gmail.com> parents: 58155 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
59257 83ef67526011 Initial commit of the argparse library, based on argparse 1.1. Steven Bethard <steven.bethard@gmail.com> parents: 58155 diff changeset	5 :synopsis: Command-line option parsing library.
61877 40cad759a355 argparse documentation updates (including updates to optparse and getopt documentation that were promised in the PEP) Steven Bethard <steven.bethard@gmail.com> parents: 59940 diff changeset	6 :deprecated:
71952 b5674229d0f9 Backport source links from 3.x. Éric Araujo <merwok@netwok.org> parents: 71628 diff changeset	7 .. moduleauthor:: Greg Ward <gward@python.net>
b5674229d0f9 Backport source links from 3.x. Éric Araujo <merwok@netwok.org> parents: 71628 diff changeset	8 .. sectionauthor:: Greg Ward <gward@python.net>
b5674229d0f9 Backport source links from 3.x. Éric Araujo <merwok@netwok.org> parents: 71628 diff changeset	9
b5674229d0f9 Backport source links from 3.x. Éric Araujo <merwok@netwok.org> parents: 71628 diff changeset	10 .. versionadded:: 2.3
61877 40cad759a355 argparse documentation updates (including updates to optparse and getopt documentation that were promised in the PEP) Steven Bethard <steven.bethard@gmail.com> parents: 59940 diff changeset	11
40cad759a355 argparse documentation updates (including updates to optparse and getopt documentation that were promised in the PEP) Steven Bethard <steven.bethard@gmail.com> parents: 59940 diff changeset	12 .. deprecated:: 2.7
40cad759a355 argparse documentation updates (including updates to optparse and getopt documentation that were promised in the PEP) Steven Bethard <steven.bethard@gmail.com> parents: 59940 diff changeset	13 The :mod:`optparse` module is deprecated and will not be developed further;
40cad759a355 argparse documentation updates (including updates to optparse and getopt documentation that were promised in the PEP) Steven Bethard <steven.bethard@gmail.com> parents: 59940 diff changeset	14 development will continue with the :mod:`argparse` module.
40cad759a355 argparse documentation updates (including updates to optparse and getopt documentation that were promised in the PEP) Steven Bethard <steven.bethard@gmail.com> parents: 59940 diff changeset	15
71952 b5674229d0f9 Backport source links from 3.x. Éric Araujo <merwok@netwok.org> parents: 71628 diff changeset	16 Source code: :source:`Lib/optparse.py`
b5674229d0f9 Backport source links from 3.x. Éric Araujo <merwok@netwok.org> parents: 71628 diff changeset	17
b5674229d0f9 Backport source links from 3.x. Éric Araujo <merwok@netwok.org> parents: 71628 diff changeset	18 --------------
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	20 :mod:`optparse` is a more convenient, flexible, and powerful library for parsing
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	21 command-line options than the old :mod:`getopt` module. :mod:`optparse` uses a
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	22 more declarative style of command-line parsing: you create an instance of
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	23 :class:`OptionParser`, populate it with options, and parse the command
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	24 line. :mod:`optparse` allows users to specify options in the conventional
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	25 GNU/POSIX syntax, and additionally generates usage and help messages for you.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	26
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	27 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	28
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29 from optparse import OptionParser
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31 parser = OptionParser()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32 parser.add_option("-f", "--file", dest="filename",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33 help="write report to FILE", metavar="FILE")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34 parser.add_option("-q", "--quiet",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35 action="store_false", dest="verbose", default=True,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36 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	37
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38 (options, args) = parser.parse_args()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40 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	41 on the command-line, for example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43 <yourscript> --file=outfile -q
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	45 As it parses the command line, :mod:`optparse` sets attributes of the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	46 ``options`` object returned by :meth:`parse_args` based on user-supplied
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	47 command-line values. When :meth:`parse_args` returns from parsing this command
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	48 line, ``options.filename`` will be ``"outfile"`` and ``options.verbose`` will be
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	49 ``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	50 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	51 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	52 equivalent to the above example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54 <yourscript> -f outfile --quiet
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55 <yourscript> --quiet --file outfile
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56 <yourscript> -q -foutfile
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57 <yourscript> -qfoutfile
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 Additionally, users can run one of ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61 <yourscript> -h
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62 <yourscript> --help
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63
58117 a0fce9665f44 Merged revisions 77267 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56814 diff changeset	64 and :mod:`optparse` will print out a brief summary of your script's options:
a0fce9665f44 Merged revisions 77267 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56814 diff changeset	65
a0fce9665f44 Merged revisions 77267 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56814 diff changeset	66 .. code-block:: text
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67
68016 c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	68 Usage: <yourscript> [options]
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	69
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	70 Options:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 -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	72 -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	73 -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	74
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75 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	76 ``sys.argv[0]``).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77
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 .. _optparse-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 Background
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82 ----------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84 :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	85 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	86 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	87 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	88 section to acquaint yourself with them.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89
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 .. _optparse-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 Terminology
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 ^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96 argument
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	97 a string entered on the command-line, and passed by the shell to ``execl()``
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	98 or ``execv()``. In Python, arguments are elements of ``sys.argv[1:]``
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	99 (``sys.argv[0]`` is the name of the program being executed). Unix shells
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	100 also use the term "word".
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 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	103 ``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	104 ``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	105 ``sys.argv[1:]``".
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106
49044 12ef7a92e59b #3040: include 'dest' argument in example; trim some trailing whitespace Andrew M. Kuchling <amk@amk.ca> parents: 47681 diff changeset	107 option
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	108 an argument used to supply extra information to guide or customize the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	109 execution of a program. There are many different syntaxes for options; the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	110 traditional Unix syntax is a hyphen ("-") followed by a single letter,
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	111 e.g. ``-x`` or ``-F``. Also, traditional Unix syntax allows multiple
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	112 options to be merged into a single argument, e.g. ``-x -F`` is equivalent
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	113 to ``-xF``. The GNU project introduced ``--`` followed by a series of
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	114 hyphen-separated words, e.g. ``--file`` or ``--dry-run``. These are the
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	115 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	116
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117 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	118
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	119 * 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	120 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	121
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	122 * 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	123 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	124 program)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126 * a plus sign followed by a single letter, or a few letters, or a word, e.g.
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	127 ``+f``, ``+rgb``
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	128
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	129 * a slash followed by a letter, or a few letters, or a word, e.g. ``/f``,
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	130 ``/file``
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	132 These option syntaxes are not supported by :mod:`optparse`, and they never
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	133 will be. This is deliberate: the first three are non-standard on any
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	134 environment, and the last only makes sense if you're exclusively targeting
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	135 VMS, MS-DOS, and/or Windows.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137 option argument
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	138 an argument that follows an option, is closely associated with that option,
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	139 and is consumed from the argument list when that option is. With
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	140 :mod:`optparse`, option arguments may either be in a separate argument from
58117 a0fce9665f44 Merged revisions 77267 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56814 diff changeset	141 their option:
a0fce9665f44 Merged revisions 77267 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56814 diff changeset	142
a0fce9665f44 Merged revisions 77267 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56814 diff changeset	143 .. code-block:: text
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145 -f foo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146 --file foo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147
58117 a0fce9665f44 Merged revisions 77267 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56814 diff changeset	148 or included in the same argument:
a0fce9665f44 Merged revisions 77267 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56814 diff changeset	149
a0fce9665f44 Merged revisions 77267 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56814 diff changeset	150 .. code-block:: text
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 -ffoo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153 --file=foo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	155 Typically, a given option either takes an argument or it doesn't. Lots of
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	156 people want an "optional option arguments" feature, meaning that some options
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	157 will take an argument if they see it, and won't if they don't. This is
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	158 somewhat controversial, because it makes parsing ambiguous: if ``-a`` takes
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	159 an optional argument and ``-b`` is another option entirely, how do we
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	160 interpret ``-ab``? Because of this ambiguity, :mod:`optparse` does not
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	161 support this feature.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163 positional argument
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164 something leftover in the argument list after options have been parsed, i.e.
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	165 after options and their arguments have been parsed and removed from the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	166 argument list.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168 required option
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169 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	170 "required option" is self-contradictory in English. :mod:`optparse` doesn't
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	171 prevent you from implementing required options, but doesn't give you much
59831 38e9b9da0164 Merged revisions 76538,76559,76882-76883,76886,76891-76892,76920,76924-76925,77081,77084,77086,77092 via svnmerge from Georg Brandl <georg@python.org> parents: 58156 diff changeset	172 help at it either.
42604 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 For example, consider this hypothetical command-line::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	175
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	176 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	177
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	178 ``-v`` and ``--report`` are both options. Assuming that ``--report``
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	179 takes one argument, ``/tmp/report.txt`` is an option argument. ``foo`` and
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	180 ``bar`` are positional arguments.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	181
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 .. _optparse-what-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 What are options for?
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186 ^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188 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	189 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	190 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	191 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	192 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	193 ``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	194 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	195
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196 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	197 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	198 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	199 positional arguments are for.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201 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	202 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	203 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	204 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	205 does not require any options at all::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207 cp SOURCE DEST
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208 cp SOURCE ... DEST-DIR
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210 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	211 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	212 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	213 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	214 ``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	215 directory.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216
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 .. _optparse-what-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 What are positional arguments for?
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223 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	224 absolutely, positively requires to run.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226 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	227 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	228 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	229 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	230 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	231 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	232 of them will simply give up.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234 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	235 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	236 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	237 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	238 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	239 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	240 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	241 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	242
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 .. _optparse-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 Tutorial
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247 --------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249 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	250 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	251 any :mod:`optparse`\ -based program.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	252
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253 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	254 program, create an OptionParser instance::
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 from optparse import 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 parser = OptionParser()
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 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	261
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 parser.add_option(opt_str, ...,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263 attr=value, ...)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	265 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	266 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	267 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	268
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269 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	270 string, e.g.::
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 parser.add_option("-f", "--file", ...)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	274 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	275 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	276 string overall.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277
79025 2291aff20a05 #15831: document multiple signatures on different lines. Patch by Chris Jerdonek. Ezio Melotti <ezio.melotti@gmail.com> parents: 78893 diff changeset	278 The option strings passed to :meth:`OptionParser.add_option` are effectively
2291aff20a05 #15831: document multiple signatures on different lines. Patch by Chris Jerdonek. Ezio Melotti <ezio.melotti@gmail.com> parents: 78893 diff changeset	279 labels for the
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280 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	281 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	282 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	283
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284 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	285 program's command line::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287 (options, args) = parser.parse_args()
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 (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	290 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	291
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	292 :meth:`parse_args` returns two values:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	293
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294 * ``options``, an object containing values for all of your options---e.g. if
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	295 ``--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	296 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	297 option
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	298
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	299 * ``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	300
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	301 This tutorial section only covers the four most important option attributes:
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	302 :attr:`~Option.action`, :attr:`~Option.type`, :attr:`~Option.dest`
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	303 (destination), and :attr:`~Option.help`. Of these, :attr:`~Option.action` is the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	304 most fundamental.
42604 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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	307 .. _optparse-understanding-option-actions:
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 Understanding option actions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312 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	313 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	314 adding new actions is an advanced topic covered in section
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	315 :ref:`optparse-extending-optparse`. Most actions tell :mod:`optparse` to store
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	316 a value in some variable---for example, take a string from the command line and
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	317 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	318
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319 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	320
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322 .. _optparse-store-action:
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 store action
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325 ^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327 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	328 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	329 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	330
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331 For example::
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 parser.add_option("-f", "--file",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334 action="store", type="string", dest="filename")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336 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	337
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338 args = ["-f", "foo.txt"]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	339 (options, args) = parser.parse_args(args)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	341 When :mod:`optparse` sees the option string ``-f``, it consumes the next
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	342 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	343 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	344
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345 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	346 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	347
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348 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	349
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	350 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	351 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	352
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	353 Let's parse another fake command-line. This time, we'll jam the option argument
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	354 right up against the option: since ``-n42`` (one argument) is equivalent to
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	355 ``-n 42`` (two arguments), the code ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357 (options, args) = parser.parse_args(["-n42"])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358 print options.num
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	360 will print ``42``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	361
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362 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	363 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	364 be a lot shorter::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	365
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	366 parser.add_option("-f", "--file", dest="filename")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	367
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	368 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	369 default from the option strings: if the first long option string is
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	370 ``--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	371 long option strings, :mod:`optparse` looks at the first short option string: the
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	372 default destination for ``-f`` is ``f``.
42604 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 :mod:`optparse` also includes built-in ``long`` and ``complex`` types. Adding
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	375 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	376
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	377
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	378 .. _optparse-handling-boolean-options:
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 Handling boolean (flag) options
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	381 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	382
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	383 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	384 ---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	385 ``store_true`` and ``store_false``. For example, you might have a ``verbose``
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	386 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	387
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	388 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	389 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	390
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391 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	392 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	393 see below.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	394
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	395 When :mod:`optparse` encounters ``-v`` on the command line, it sets
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	396 ``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	397 ``options.verbose`` is set to ``False``.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400 .. _optparse-other-actions:
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 Other actions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	403 ^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	404
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405 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	406
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	407 ``"store_const"``
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408 store a constant value
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	410 ``"append"``
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411 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	412
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	413 ``"count"``
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414 increment a counter by one
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	415
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	416 ``"callback"``
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417 call a specified function
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 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	420 and section :ref:`optparse-option-callbacks`.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	423 .. _optparse-default-values:
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 Default values
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	426 ^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428 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	429 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	430 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	431 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	432 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	433 command line is parsed.
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 First, consider the verbose/quiet example. If we want :mod:`optparse` to set
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	436 ``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	437
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	438 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	439 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	440
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	441 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	442 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	443 exactly equivalent::
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 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	446 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	447
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	448 Consider this::
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 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	451 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	452
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	453 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	454 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	455
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	456 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	457 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	458
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	459 parser.set_defaults(verbose=True)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	460 parser.add_option(...)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	461 (options, args) = parser.parse_args()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	462
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	463 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	464 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	465 values, not both.
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	468 .. _optparse-generating-help:
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 Generating help
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	471 ^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	472
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	473 :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	474 useful for creating user-friendly command-line interfaces. All you have to do
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	475 is supply a :attr:`~Option.help` value for each option, and optionally a short
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	476 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	477 user-friendly (documented) options::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	478
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	479 usage = "usage: %prog [options] arg1 arg2"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	480 parser = OptionParser(usage=usage)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	481 parser.add_option("-v", "--verbose",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	482 action="store_true", dest="verbose", default=True,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	483 help="make lots of noise [default]")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	484 parser.add_option("-q", "--quiet",
49044 12ef7a92e59b #3040: include 'dest' argument in example; trim some trailing whitespace Andrew M. Kuchling <amk@amk.ca> parents: 47681 diff changeset	485 action="store_false", dest="verbose",
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	486 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	487 parser.add_option("-f", "--filename",
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	488 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	489 parser.add_option("-m", "--mode",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	490 default="intermediate",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	491 help="interaction mode: novice, intermediate, "
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	492 "or expert [default: %default]")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	493
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	494 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	495 command-line, or if you just call :meth:`parser.print_help`, it prints the
58117 a0fce9665f44 Merged revisions 77267 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56814 diff changeset	496 following to standard output:
a0fce9665f44 Merged revisions 77267 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56814 diff changeset	497
a0fce9665f44 Merged revisions 77267 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56814 diff changeset	498 .. code-block:: text
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499
68016 c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	500 Usage: <yourscript> [options] arg1 arg2
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	501
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	502 Options:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	503 -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	504 -v, --verbose make lots of noise [default]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	505 -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	506 -f FILE, --filename=FILE
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	507 write output to FILE
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	508 -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	509 expert [default: intermediate]
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 (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	512 printing the help text.)
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 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	515 help message:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	516
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	517 * the script defines its own usage message::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	518
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	519 usage = "usage: %prog [options] arg1 arg2"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	520
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	521 :mod:`optparse` expands ``%prog`` in the usage string to the name of the
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	522 current program, i.e. ``os.path.basename(sys.argv[0])``. The expanded string
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	523 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	524
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	525 If you don't supply a usage string, :mod:`optparse` uses a bland but sensible
68016 c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	526 default: ``"Usage: %prog [options]"``, which is fine if your script doesn't
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	527 take any positional arguments.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	528
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	529 * 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	530 :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	531 good.
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 * 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	534 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	535
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	536 -m MODE, --mode=MODE
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	537
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	538 Here, "MODE" is called the meta-variable: it stands for the argument that the
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	539 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	540 :mod:`optparse` converts the destination variable name to uppercase and uses
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	541 that for the meta-variable. Sometimes, that's not what you want---for
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	542 example, the ``--filename`` option explicitly sets ``metavar="FILE"``,
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	543 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	544
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	545 -f FILE, --filename=FILE
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	546
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	547 This is important for more than just saving space, though: the manually
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	548 written help text uses the meta-variable ``FILE`` to clue the user in that
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	549 there's a connection between the semi-formal syntax ``-f FILE`` and the informal
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	550 semantic description "write output to FILE". This is a simple but effective
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	551 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	552
46078 47c2ffc38d1d #2476: document that %default feature is new in 2.4. Georg Brandl <georg@python.org> parents: 45423 diff changeset	553 .. versionadded:: 2.4
47c2ffc38d1d #2476: document that %default feature is new in 2.4. Georg Brandl <georg@python.org> parents: 45423 diff changeset	554 Options that have a default value can include ``%default`` in the help
47c2ffc38d1d #2476: document that %default feature is new in 2.4. Georg Brandl <georg@python.org> parents: 45423 diff changeset	555 string---\ :mod:`optparse` will replace it with :func:`str` of the option's
47c2ffc38d1d #2476: document that %default feature is new in 2.4. Georg Brandl <georg@python.org> parents: 45423 diff changeset	556 default value. If an option has no default value (or the default value is
47c2ffc38d1d #2476: document that %default feature is new in 2.4. Georg Brandl <georg@python.org> parents: 45423 diff changeset	557 ``None``), ``%default`` expands to ``none``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	558
68016 c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	559 Grouping Options
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	560 ++++++++++++++++
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	561
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	562 When dealing with many options, it is convenient to group these options for
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	563 better help output. An :class:`OptionParser` can contain several option groups,
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	564 each of which can contain several options.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	565
68016 c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	566 An option group is obtained using the class :class:`OptionGroup`:
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	567
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	568 .. class:: OptionGroup(parser, title, description=None)
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	569
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	570 where
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	571
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	572 * parser is the :class:`OptionParser` instance the group will be insterted in
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	573 to
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	574 * title is the group title
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	575 * description, optional, is a long description of the group
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	576
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	577 :class:`OptionGroup` inherits from :class:`OptionContainer` (like
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	578 :class:`OptionParser`) and so the :meth:`add_option` method can be used to add
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	579 an option to the group.
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	580
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	581 Once all the options are declared, using the :class:`OptionParser` method
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	582 :meth:`add_option_group` the group is added to the previously defined parser.
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	583
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	584 Continuing with the parser defined in the previous section, adding an
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	585 :class:`OptionGroup` to a parser is easy::
44794 d8c13ecb6e85 Bug 1296: restore text describing OptionGroup Andrew M. Kuchling <amk@amk.ca> parents: 44383 diff changeset	586
d8c13ecb6e85 Bug 1296: restore text describing OptionGroup Andrew M. Kuchling <amk@amk.ca> parents: 44383 diff changeset	587 group = OptionGroup(parser, "Dangerous Options",
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50257 diff changeset	588 "Caution: use these options at your own risk. "
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50257 diff changeset	589 "It is believed that some of them bite.")
44794 d8c13ecb6e85 Bug 1296: restore text describing OptionGroup Andrew M. Kuchling <amk@amk.ca> parents: 44383 diff changeset	590 group.add_option("-g", action="store_true", help="Group option.")
d8c13ecb6e85 Bug 1296: restore text describing OptionGroup Andrew M. Kuchling <amk@amk.ca> parents: 44383 diff changeset	591 parser.add_option_group(group)
d8c13ecb6e85 Bug 1296: restore text describing OptionGroup Andrew M. Kuchling <amk@amk.ca> parents: 44383 diff changeset	592
58117 a0fce9665f44 Merged revisions 77267 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56814 diff changeset	593 This would result in the following help output:
a0fce9665f44 Merged revisions 77267 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56814 diff changeset	594
a0fce9665f44 Merged revisions 77267 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56814 diff changeset	595 .. code-block:: text
44794 d8c13ecb6e85 Bug 1296: restore text describing OptionGroup Andrew M. Kuchling <amk@amk.ca> parents: 44383 diff changeset	596
68016 c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	597 Usage: <yourscript> [options] arg1 arg2
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	598
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	599 Options:
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	600 -h, --help show this help message and exit
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	601 -v, --verbose make lots of noise [default]
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	602 -q, --quiet be vewwy quiet (I'm hunting wabbits)
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	603 -f FILE, --filename=FILE
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	604 write output to FILE
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	605 -m MODE, --mode=MODE interaction mode: novice, intermediate, or
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	606 expert [default: intermediate]
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	607
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	608 Dangerous Options:
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	609 Caution: use these options at your own risk. It is believed that some
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	610 of them bite.
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	611
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	612 -g Group option.
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	613
73585 2a3b60d28f6c fixing typos in optparse doc Eli Bendersky <eliben@gmail.com> parents: 71952 diff changeset	614 A bit more complete example might involve using more than one group: still
2a3b60d28f6c fixing typos in optparse doc Eli Bendersky <eliben@gmail.com> parents: 71952 diff changeset	615 extending the previous example::
68016 c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	616
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	617 group = OptionGroup(parser, "Dangerous Options",
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	618 "Caution: use these options at your own risk. "
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	619 "It is believed that some of them bite.")
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	620 group.add_option("-g", action="store_true", help="Group option.")
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	621 parser.add_option_group(group)
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	622
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	623 group = OptionGroup(parser, "Debug Options")
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	624 group.add_option("-d", "--debug", action="store_true",
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	625 help="Print debug information")
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	626 group.add_option("-s", "--sql", action="store_true",
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	627 help="Print all SQL statements executed")
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	628 group.add_option("-e", action="store_true", help="Print every action done")
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	629 parser.add_option_group(group)
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	630
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	631 that results in the following output:
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	632
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	633 .. code-block:: text
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	634
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	635 Usage: <yourscript> [options] arg1 arg2
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	636
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	637 Options:
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	638 -h, --help show this help message and exit
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	639 -v, --verbose make lots of noise [default]
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	640 -q, --quiet be vewwy quiet (I'm hunting wabbits)
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	641 -f FILE, --filename=FILE
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	642 write output to FILE
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	643 -m MODE, --mode=MODE interaction mode: novice, intermediate, or expert
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	644 [default: intermediate]
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	645
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	646 Dangerous Options:
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	647 Caution: use these options at your own risk. It is believed that some
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	648 of them bite.
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	649
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	650 -g Group option.
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	651
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	652 Debug Options:
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	653 -d, --debug Print debug information
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	654 -s, --sql Print all SQL statements executed
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	655 -e Print every action done
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	656
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	657 Another interesting method, in particular when working programmatically with
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	658 option groups is:
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	659
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	660 .. method:: OptionParser.get_option_group(opt_str)
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	661
71628 5a248fcfa112 Issue #11699: fix documentation of OptionParser.get_option_group. Patch by Petri Lehtinen Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	662 Return the :class:`OptionGroup` to which the short or long option
5a248fcfa112 Issue #11699: fix documentation of OptionParser.get_option_group. Patch by Petri Lehtinen Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	663 string opt_str (e.g. ``'-o'`` or ``'--option'``) belongs. If
5a248fcfa112 Issue #11699: fix documentation of OptionParser.get_option_group. Patch by Petri Lehtinen Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	664 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	665
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	666 .. _optparse-printing-version-string:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	667
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	668 Printing a version string
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	669 ^^^^^^^^^^^^^^^^^^^^^^^^^
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 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	672 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	673 argument to OptionParser::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	674
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	675 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	676
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	677 ``%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	678 ``version`` can contain anything you like. When you supply it, :mod:`optparse`
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	679 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	680 this option on the command line, it expands your ``version`` string (by
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	681 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	682
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	683 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	684
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	685 $ /usr/bin/foo --version
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	686 foo 1.0
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	687
58156 0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	688 The following two methods can be used to print and get the ``version`` string:
0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	689
0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	690 .. method:: OptionParser.print_version(file=None)
0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	691
0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	692 Print the version message for the current program (``self.version``) to
0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	693 file (default stdout). As with :meth:`print_usage`, any occurrence
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	694 of ``%prog`` in ``self.version`` is replaced with the name of the current
58156 0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	695 program. Does nothing if ``self.version`` is empty or undefined.
0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	696
0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	697 .. method:: OptionParser.get_version()
0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	698
0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	699 Same as :meth:`print_version` but returns the version string instead of
0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	700 printing it.
0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	701
42604 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 .. _optparse-how-optparse-handles-errors:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	704
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	705 How :mod:`optparse` handles errors
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	706 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	707
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	708 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	709 programmer errors and user errors. Programmer errors are usually erroneous
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	710 calls to :func:`OptionParser.add_option`, e.g. invalid option strings, unknown
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	711 option attributes, missing option attributes, etc. These are dealt with in the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	712 usual way: raise an exception (either :exc:`optparse.OptionError` or
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	713 :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	714
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	715 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	716 no matter how stable your code is. :mod:`optparse` can automatically detect
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	717 some user errors, such as bad option arguments (passing ``-n 4x`` where
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	718 ``-n`` takes an integer argument), missing arguments (``-n`` at the end
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	719 of the command line, where ``-n`` takes an argument of any type). Also,
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	720 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	721 condition::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	722
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	723 (options, args) = parser.parse_args()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	724 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	725 if options.a and options.b:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	726 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	727
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	728 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	729 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	730 error status 2.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	731
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	732 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	733 that takes an integer::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	734
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	735 $ /usr/bin/foo -n 4x
68016 c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	736 Usage: foo [options]
42604 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 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	739
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	740 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	741
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	742 $ /usr/bin/foo -n
68016 c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	743 Usage: foo [options]
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	744
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	745 foo: error: -n option requires an argument
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	746
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	747 :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	748 option involved in the error; be sure to do the same when calling
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	749 :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	750
47681 6434dd704d60 Clarification. Georg Brandl <georg@python.org> parents: 46538 diff changeset	751 If :mod:`optparse`'s default error-handling behaviour does not suit your needs,
56814 127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from Georg Brandl <georg@python.org> parents: 56051 diff changeset	752 you'll need to subclass OptionParser and override its :meth:`~OptionParser.exit`
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from Georg Brandl <georg@python.org> parents: 56051 diff changeset	753 and/or :meth:`~OptionParser.error` methods.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	754
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 .. _optparse-putting-it-all-together:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	757
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	758 Putting it all together
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	759 ^^^^^^^^^^^^^^^^^^^^^^^
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 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	762
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	763 from optparse import OptionParser
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	764 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	765 def main():
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	766 usage = "usage: %prog [options] arg"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	767 parser = OptionParser(usage)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	768 parser.add_option("-f", "--file", dest="filename",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	769 help="read data from FILENAME")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	770 parser.add_option("-v", "--verbose",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	771 action="store_true", dest="verbose")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	772 parser.add_option("-q", "--quiet",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	773 action="store_false", dest="verbose")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	774 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	775 (options, args) = parser.parse_args()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	776 if len(args) != 1:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	777 parser.error("incorrect number of arguments")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	778 if options.verbose:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	779 print "reading %s..." % options.filename
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 if __name__ == "__main__":
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	783 main()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	784
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 .. _optparse-reference-guide:
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 Reference Guide
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
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 .. _optparse-creating-parser:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	793
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	794 Creating the parser
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	795 ^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	796
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	797 The first step in using :mod:`optparse` is to create an OptionParser instance.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	798
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	799 .. class:: OptionParser(...)
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	800
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	801 The OptionParser constructor has no required arguments, but a number of
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	802 optional keyword arguments. You should always pass them as keyword
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	803 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	804
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	805 ``usage`` (default: ``"%prog [options]"``)
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	806 The usage summary to print when your program is run incorrectly or with a
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	807 help option. When :mod:`optparse` prints the usage string, it expands
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	808 ``%prog`` to ``os.path.basename(sys.argv[0])`` (or to ``prog`` if you
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	809 passed that keyword argument). To suppress a usage message, pass the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	810 special value :data:`optparse.SUPPRESS_USAGE`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	811
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	812 ``option_list`` (default: ``[]``)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	813 A list of Option objects to populate the parser with. The options in
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	814 ``option_list`` are added after any options in ``standard_option_list`` (a
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	815 class attribute that may be set by OptionParser subclasses), but before
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	816 any version or help options. Deprecated; use :meth:`add_option` after
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	817 creating the parser instead.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	818
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	819 ``option_class`` (default: optparse.Option)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	820 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	821
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	822 ``version`` (default: ``None``)
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	823 A version string to print when the user supplies a version option. If you
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	824 supply a true value for ``version``, :mod:`optparse` automatically adds a
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	825 version option with the single option string ``--version``. The
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	826 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	827
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	828 ``conflict_handler`` (default: ``"error"``)
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	829 Specifies what to do when options with conflicting option strings are
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	830 added to the parser; see section
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	831 :ref:`optparse-conflicts-between-options`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	832
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	833 ``description`` (default: ``None``)
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	834 A paragraph of text giving a brief overview of your program.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	835 :mod:`optparse` reformats this paragraph to fit the current terminal width
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	836 and prints it when the user requests help (after ``usage``, but before the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	837 list of options).
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	838
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	839 ``formatter`` (default: a new :class:`IndentedHelpFormatter`)
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	840 An instance of optparse.HelpFormatter that will be used for printing help
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	841 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	842 IndentedHelpFormatter and TitledHelpFormatter.
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 ``add_help_option`` (default: ``True``)
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	845 If true, :mod:`optparse` will add a help option (with option strings ``-h``
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	846 and ``--help``) to the parser.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	847
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	848 ``prog``
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	849 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	850 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	851
59942 a702648c8f41 Merged revisions 79329 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 59831 diff changeset	852 ``epilog`` (default: ``None``)
a702648c8f41 Merged revisions 79329 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 59831 diff changeset	853 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	854
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	855 .. _optparse-populating-parser:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	856
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	857 Populating the parser
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	858 ^^^^^^^^^^^^^^^^^^^^^
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 There are several ways to populate the parser with options. The preferred way
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	861 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	862 :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	863
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	864 * 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	865
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	866 * pass it any combination of positional and keyword arguments that are
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	867 acceptable to :func:`make_option` (i.e., to the Option constructor), and it
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	868 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	869
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	870 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	871 the OptionParser constructor, as in::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	872
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	873 option_list = [
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	874 make_option("-f", "--filename",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	875 action="store", type="string", dest="filename"),
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	876 make_option("-q", "--quiet",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	877 action="store_false", dest="verbose"),
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	878 ]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	879 parser = OptionParser(option_list=option_list)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	880
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	881 (: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	882 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	883 :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	884 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	885
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 .. _optparse-defining-options:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	888
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	889 Defining options
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	890 ^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	891
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	892 Each Option instance represents a set of synonymous command-line option strings,
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	893 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	894 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	895
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	896 The canonical way to create an :class:`Option` instance is with the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	897 :meth:`add_option` method of :class:`OptionParser`.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	898
79025 2291aff20a05 #15831: document multiple signatures on different lines. Patch by Chris Jerdonek. Ezio Melotti <ezio.melotti@gmail.com> parents: 78893 diff changeset	899 .. method:: OptionParser.add_option(option)
2291aff20a05 #15831: document multiple signatures on different lines. Patch by Chris Jerdonek. Ezio Melotti <ezio.melotti@gmail.com> parents: 78893 diff changeset	900 OptionParser.add_option(*opt_str, attr=value, ...)
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	901
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	902 To define an option with only a short option string::
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	903
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	904 parser.add_option("-f", attr=value, ...)
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	905
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	906 And to define an option with only a long option string::
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	907
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	908 parser.add_option("--foo", attr=value, ...)
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	909
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	910 The keyword arguments define attributes of the new Option object. The most
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	911 important option attribute is :attr:`~Option.action`, and it largely
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	912 determines which other attributes are relevant or required. If you pass
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	913 irrelevant option attributes, or fail to pass required ones, :mod:`optparse`
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	914 raises an :exc:`OptionError` exception explaining your mistake.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	915
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	916 An option's action determines what :mod:`optparse` does when it encounters
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	917 this option on the command-line. The standard option actions hard-coded into
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	918 :mod:`optparse` are:
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	919
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	920 ``"store"``
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	921 store this option's argument (default)
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	922
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	923 ``"store_const"``
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	924 store a constant value
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	925
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	926 ``"store_true"``
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	927 store a true value
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	928
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	929 ``"store_false"``
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	930 store a false value
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	931
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	932 ``"append"``
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	933 append this option's argument to a list
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	934
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	935 ``"append_const"``
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	936 append a constant value to a list
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	937
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	938 ``"count"``
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	939 increment a counter by one
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	940
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	941 ``"callback"``
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	942 call a specified function
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	943
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	944 ``"help"``
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	945 print a usage message including all options and the documentation for them
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	946
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	947 (If you don't supply an action, the default is ``"store"``. For this action,
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	948 you may also supply :attr:`~Option.type` and :attr:`~Option.dest` option
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	949 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	950
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	951 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	952 :mod:`optparse` always creates a special object for this, conventionally called
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	953 ``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	954 arguments (and various other values) are stored as attributes of this object,
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	955 according to the :attr:`~Option.dest` (destination) option attribute.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	956
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	957 For example, when you call ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	958
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	959 parser.parse_args()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	960
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	961 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	962
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	963 options = Values()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	964
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	965 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	966
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	967 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	968
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	969 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	970
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	971 -ffoo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	972 -f foo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	973 --file=foo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	974 --file foo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	975
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	976 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	977
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	978 options.filename = "foo"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	979
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	980 The :attr:`~Option.type` and :attr:`~Option.dest` option attributes are almost
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	981 as important as :attr:`~Option.action`, but :attr:`~Option.action` is the only
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	982 one that makes sense for all options.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	983
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	984
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	985 .. _optparse-option-attributes:
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	986
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	987 Option attributes
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	988 ^^^^^^^^^^^^^^^^^
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	989
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	990 The following option attributes may be passed as keyword arguments to
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	991 :meth:`OptionParser.add_option`. If you pass an option attribute that is not
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	992 relevant to a particular option, or fail to pass a required option attribute,
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	993 :mod:`optparse` raises :exc:`OptionError`.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	994
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	995 .. attribute:: Option.action
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	996
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	997 (default: ``"store"``)
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	998
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	999 Determines :mod:`optparse`'s behaviour when this option is seen on the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1000 command line; the available options are documented :ref:`here
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1001 <optparse-standard-option-actions>`.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1002
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1003 .. attribute:: Option.type
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1004
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1005 (default: ``"string"``)
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1006
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1007 The argument type expected by this option (e.g., ``"string"`` or ``"int"``);
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1008 the available option types are documented :ref:`here
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1009 <optparse-standard-option-types>`.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1010
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1011 .. attribute:: Option.dest
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1012
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1013 (default: derived from option strings)
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1014
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1015 If the option's action implies writing or modifying a value somewhere, this
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1016 tells :mod:`optparse` where to write it: :attr:`~Option.dest` names an
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1017 attribute of the ``options`` object that :mod:`optparse` builds as it parses
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1018 the command line.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1019
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1020 .. attribute:: Option.default
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1021
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1022 The value to use for this option's destination if the option is not seen on
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1023 the command line. See also :meth:`OptionParser.set_defaults`.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1024
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1025 .. attribute:: Option.nargs
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1026
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1027 (default: 1)
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1028
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1029 How many arguments of type :attr:`~Option.type` should be consumed when this
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1030 option is seen. If > 1, :mod:`optparse` will store a tuple of values to
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1031 :attr:`~Option.dest`.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1032
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1033 .. attribute:: Option.const
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1034
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1035 For actions that store a constant value, the constant value to store.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1036
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1037 .. attribute:: Option.choices
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1038
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1039 For options of type ``"choice"``, the list of strings the user may choose
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1040 from.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1041
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1042 .. attribute:: Option.callback
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1043
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1044 For options with action ``"callback"``, the callable to call when this option
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1045 is seen. See section :ref:`optparse-option-callbacks` for detail on the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1046 arguments passed to the callable.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1047
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1048 .. attribute:: Option.callback_args
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1049 Option.callback_kwargs
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1050
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1051 Additional positional and keyword arguments to pass to ``callback`` after the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1052 four standard callback arguments.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1053
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1054 .. attribute:: Option.help
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1055
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1056 Help text to print for this option when listing all available options after
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1057 the user supplies a :attr:`~Option.help` option (such as ``--help``). If
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1058 no help text is supplied, the option will be listed without help text. To
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1059 hide this option, use the special value :data:`optparse.SUPPRESS_HELP`.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1060
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1061 .. attribute:: Option.metavar
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1062
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1063 (default: derived from option strings)
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1064
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1065 Stand-in for the option argument(s) to use when printing help text. See
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1066 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	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 .. _optparse-standard-option-actions:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1070
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1071 Standard option actions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1072 ^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1073
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1074 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	1075 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	1076 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	1077 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	1078
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1079 * ``"store"`` [relevant: :attr:`~Option.type`, :attr:`~Option.dest`,
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1080 :attr:`~Option.nargs`, :attr:`~Option.choices`]
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1081
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1082 The option must be followed by an argument, which is converted to a value
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1083 according to :attr:`~Option.type` and stored in :attr:`~Option.dest`. If
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1084 :attr:`~Option.nargs` > 1, multiple arguments will be consumed from the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1085 command line; all will be converted according to :attr:`~Option.type` and
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1086 stored to :attr:`~Option.dest` as a tuple. See the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1087 :ref:`optparse-standard-option-types` section.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1088
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1089 If :attr:`~Option.choices` is supplied (a list or tuple of strings), the type
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1090 defaults to ``"choice"``.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1091
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1092 If :attr:`~Option.type` is not supplied, it defaults to ``"string"``.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1093
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1094 If :attr:`~Option.dest` is not supplied, :mod:`optparse` derives a destination
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1095 from the first long option string (e.g., ``--foo-bar`` implies
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1096 ``foo_bar``). If there are no long option strings, :mod:`optparse` derives a
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1097 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	1098
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1099 Example::
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 parser.add_option("-f")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1102 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	1103
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1104 As it parses the command line ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1105
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1106 -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	1107
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1108 :mod:`optparse` will set ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1109
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1110 options.f = "foo.txt"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1111 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	1112 options.f = "bar.txt"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1113
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1114 * ``"store_const"`` [required: :attr:`~Option.const`; relevant:
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1115 :attr:`~Option.dest`]
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1116
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1117 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	1118
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1119 Example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1120
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1121 parser.add_option("-q", "--quiet",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1122 action="store_const", const=0, dest="verbose")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1123 parser.add_option("-v", "--verbose",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1124 action="store_const", const=1, dest="verbose")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1125 parser.add_option("--noisy",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1126 action="store_const", const=2, dest="verbose")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1127
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1128 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	1129
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1130 options.verbose = 2
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1131
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1132 * ``"store_true"`` [relevant: :attr:`~Option.dest`]
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1133
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1134 A special case of ``"store_const"`` that stores a true value to
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1135 :attr:`~Option.dest`.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1136
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1137 * ``"store_false"`` [relevant: :attr:`~Option.dest`]
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1138
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1139 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	1140
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1141 Example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1142
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1143 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	1144 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	1145
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1146 * ``"append"`` [relevant: :attr:`~Option.type`, :attr:`~Option.dest`,
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1147 :attr:`~Option.nargs`, :attr:`~Option.choices`]
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1148
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1149 The option must be followed by an argument, which is appended to the list in
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1150 :attr:`~Option.dest`. If no default value for :attr:`~Option.dest` is
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1151 supplied, an empty list is automatically created when :mod:`optparse` first
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1152 encounters this option on the command-line. If :attr:`~Option.nargs` > 1,
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1153 multiple arguments are consumed, and a tuple of length :attr:`~Option.nargs`
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1154 is appended to :attr:`~Option.dest`.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1155
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1156 The defaults for :attr:`~Option.type` and :attr:`~Option.dest` are the same as
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1157 for the ``"store"`` action.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1158
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1159 Example::
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 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	1162
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1163 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	1164 of::
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 = []
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1167 options.tracks.append(int("3"))
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1168
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1169 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	1170
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1171 options.tracks.append(int("4"))
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1172
78893 79f6d4aff39d closes #5088: document behavior of optparse defaults with 'append' action. R David Murray <rdmurray@bitdance.com> parents: 73585 diff changeset	1173 The ``append`` action calls the ``append`` method on the current value of the
79f6d4aff39d closes #5088: document behavior of optparse defaults with 'append' action. R David Murray <rdmurray@bitdance.com> parents: 73585 diff changeset	1174 option. This means that any default value specified must have an ``append``
79f6d4aff39d closes #5088: document behavior of optparse defaults with 'append' action. R David Murray <rdmurray@bitdance.com> parents: 73585 diff changeset	1175 method. It also means that if the default value is non-empty, the default
79f6d4aff39d closes #5088: document behavior of optparse defaults with 'append' action. R David Murray <rdmurray@bitdance.com> parents: 73585 diff changeset	1176 elements will be present in the parsed value for the option, with any values
79f6d4aff39d closes #5088: document behavior of optparse defaults with 'append' action. R David Murray <rdmurray@bitdance.com> parents: 73585 diff changeset	1177 from the command line appended after those default values::
79f6d4aff39d closes #5088: document behavior of optparse defaults with 'append' action. R David Murray <rdmurray@bitdance.com> parents: 73585 diff changeset	1178
79f6d4aff39d closes #5088: document behavior of optparse defaults with 'append' action. R David Murray <rdmurray@bitdance.com> parents: 73585 diff changeset	1179 >>> parser.add_option("--files", action="append", default=['~/.mypkg/defaults'])
79f6d4aff39d closes #5088: document behavior of optparse defaults with 'append' action. R David Murray <rdmurray@bitdance.com> parents: 73585 diff changeset	1180 >>> opts, args = parser.parse_args(['--files', 'overrides.mypkg'])
79f6d4aff39d closes #5088: document behavior of optparse defaults with 'append' action. R David Murray <rdmurray@bitdance.com> parents: 73585 diff changeset	1181 >>> opts.files
79f6d4aff39d closes #5088: document behavior of optparse defaults with 'append' action. R David Murray <rdmurray@bitdance.com> parents: 73585 diff changeset	1182 ['~/.mypkg/defaults', 'overrides.mypkg']
79f6d4aff39d closes #5088: document behavior of optparse defaults with 'append' action. R David Murray <rdmurray@bitdance.com> parents: 73585 diff changeset	1183
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1184 * ``"append_const"`` [required: :attr:`~Option.const`; relevant:
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1185 :attr:`~Option.dest`]
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1186
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1187 Like ``"store_const"``, but the value :attr:`~Option.const` is appended to
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1188 :attr:`~Option.dest`; as with ``"append"``, :attr:`~Option.dest` defaults to
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1189 ``None``, and an empty list is automatically created the first time the option
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1190 is encountered.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1191
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1192 * ``"count"`` [relevant: :attr:`~Option.dest`]
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1193
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1194 Increment the integer stored at :attr:`~Option.dest`. If no default value is
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1195 supplied, :attr:`~Option.dest` is set to zero before being incremented the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1196 first time.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1197
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1198 Example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1199
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1200 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	1201
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1202 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	1203 equivalent of::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1204
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1205 options.verbosity = 0
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1206 options.verbosity += 1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1207
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1208 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	1209
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1210 options.verbosity += 1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1211
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1212 * ``"callback"`` [required: :attr:`~Option.callback`; relevant:
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1213 :attr:`~Option.type`, :attr:`~Option.nargs`, :attr:`~Option.callback_args`,
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1214 :attr:`~Option.callback_kwargs`]
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1215
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1216 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	1217
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1218 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	1219
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1220 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	1221
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1222 * ``"help"``
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1223
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1224 Prints a complete help message for all the options in the current option
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1225 parser. The help message is constructed from the ``usage`` string passed to
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1226 OptionParser's constructor and the :attr:`~Option.help` string passed to every
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1227 option.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1228
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1229 If no :attr:`~Option.help` string is supplied for an option, it will still be
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1230 listed in the help message. To omit an option entirely, use the special value
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1231 :data:`optparse.SUPPRESS_HELP`.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1232
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1233 :mod:`optparse` automatically adds a :attr:`~Option.help` option to all
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1234 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	1235
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1236 Example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1237
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1238 from optparse import OptionParser, SUPPRESS_HELP
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1239
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1240 # usually, a help option is added automatically, but that can
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1241 # be suppressed using the add_help_option argument
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1242 parser = OptionParser(add_help_option=False)
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1243
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1244 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	1245 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	1246 help="Be moderately verbose")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1247 parser.add_option("--file", dest="filename",
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1248 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	1249 parser.add_option("--secret", help=SUPPRESS_HELP)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1250
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1251 If :mod:`optparse` sees either ``-h`` or ``--help`` on the command line,
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1252 it will print something like the following help message to stdout (assuming
58117 a0fce9665f44 Merged revisions 77267 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56814 diff changeset	1253 ``sys.argv[0]`` is ``"foo.py"``):
a0fce9665f44 Merged revisions 77267 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56814 diff changeset	1254
a0fce9665f44 Merged revisions 77267 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56814 diff changeset	1255 .. code-block:: text
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1256
68016 c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	1257 Usage: foo.py [options]
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	1258
c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	1259 Options:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1260 -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	1261 -v Be moderately verbose
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1262 --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	1263
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1264 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	1265 ``sys.exit(0)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1266
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1267 * ``"version"``
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1268
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1269 Prints the version number supplied to the OptionParser to stdout and exits.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1270 The version number is actually formatted and printed by the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1271 ``print_version()`` method of OptionParser. Generally only relevant if the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1272 ``version`` argument is supplied to the OptionParser constructor. As with
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1273 :attr:`~Option.help` options, you will rarely create ``version`` options,
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1274 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	1275
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 .. _optparse-standard-option-types:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1278
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1279 Standard option types
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
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1282 :mod:`optparse` has six built-in option types: ``"string"``, ``"int"``,
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1283 ``"long"``, ``"choice"``, ``"float"`` and ``"complex"``. If you need to add new
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1284 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	1285
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1286 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	1287 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	1288
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1289 Integer arguments (type ``"int"`` or ``"long"``) are parsed as follows:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1290
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1291 * 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	1292
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1293 * 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	1294
43428 b4e688fd6602 Fix typo and double word. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1295 * 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	1296
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1297 * 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	1298
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1299
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1300 The conversion is done by calling either :func:`int` or :func:`long` with the
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1301 appropriate base (2, 8, 10, or 16). If this fails, so will :mod:`optparse`,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1302 although with a more useful error message.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1303
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1304 ``"float"`` and ``"complex"`` option arguments are converted directly with
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1305 :func:`float` and :func:`complex`, with similar error-handling.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1306
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1307 ``"choice"`` options are a subtype of ``"string"`` options. The
65144 7018261f2ac1 Merged revisions 85274 via svnmerge from Georg Brandl <georg@python.org> parents: 63440 diff changeset	1308 :attr:`~Option.choices` option attribute (a sequence of strings) defines the
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1309 set of allowed option arguments. :func:`optparse.check_choice` compares
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1310 user-supplied option arguments against this master list and raises
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1311 :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	1312
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1313
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1314 .. _optparse-parsing-arguments:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1315
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1316 Parsing arguments
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1319 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	1320 :meth:`parse_args` method::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1321
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1322 (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	1323
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1324 where the input parameters are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1325
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1326 ``args``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1327 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	1328
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1329 ``values``
63511 61ad81a774c5 Merged revisions 83421,83424 via svnmerge from Georg Brandl <georg@python.org> parents: 59942 diff changeset	1330 a :class:`optparse.Values` object to store option arguments in (default: a
61ad81a774c5 Merged revisions 83421,83424 via svnmerge from Georg Brandl <georg@python.org> parents: 59942 diff changeset	1331 new instance of :class:`Values`) -- if you give an existing object, the
61ad81a774c5 Merged revisions 83421,83424 via svnmerge from Georg Brandl <georg@python.org> parents: 59942 diff changeset	1332 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	1333
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1334 and the return values are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1335
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1336 ``options``
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1337 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	1338 instance created by :mod:`optparse`
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 ``args``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1341 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	1342
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1343 The most common usage is to supply neither keyword argument. If you supply
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1344 ``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	1345 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	1346 :meth:`parse_args`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1347
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1348 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	1349 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	1350 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	1351 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	1352
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1353
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1354 .. _optparse-querying-manipulating-option-parser:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1355
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1356 Querying and manipulating your option parser
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1357 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1358
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1359 The default behavior of the option parser can be customized slightly, and you
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1360 can also poke around your option parser and see what's there. OptionParser
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1361 provides several methods to help you out:
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1362
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1363 .. method:: OptionParser.disable_interspersed_args()
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1364
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1365 Set parsing to stop on the first non-option. For example, if ``-a`` and
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1366 ``-b`` are both simple options that take no arguments, :mod:`optparse`
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1367 normally accepts this syntax::
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1368
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1369 prog -a arg1 -b arg2
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1370
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1371 and treats it as equivalent to ::
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1372
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1373 prog -a -b arg1 arg2
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1374
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1375 To disable this feature, call :meth:`disable_interspersed_args`. This
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1376 restores traditional Unix syntax, where option parsing stops with the first
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1377 non-option argument.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1378
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1379 Use this if you have a command processor which runs another command which has
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1380 options of its own and you want to make sure these options don't get
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1381 confused. For example, each command might have a different set of options.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1382
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1383 .. method:: OptionParser.enable_interspersed_args()
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1384
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1385 Set parsing to not stop on the first non-option, allowing interspersing
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1386 switches with command arguments. This is the default behavior.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1387
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1388 .. method:: OptionParser.get_option(opt_str)
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1389
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1390 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	1391 no options have that option string.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1392
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1393 .. method:: OptionParser.has_option(opt_str)
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1394
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1395 Return true if the OptionParser has an option with option string opt_str
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1396 (e.g., ``-q`` or ``--verbose``).
49324 755f34ab438b #1415508: Document two functions Andrew M. Kuchling <amk@amk.ca> parents: 49085 diff changeset	1397
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1398 .. method:: OptionParser.remove_option(opt_str)
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1399
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1400 If the :class:`OptionParser` has an option corresponding to opt_str, that
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1401 option is removed. If that option provided any other option strings, all of
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1402 those option strings become invalid. If opt_str does not occur in any
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1403 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	1404
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1405
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1406 .. _optparse-conflicts-between-options:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1407
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1408 Conflicts between options
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1409 ^^^^^^^^^^^^^^^^^^^^^^^^^
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 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	1412 strings::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1413
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1414 parser.add_option("-n", "--dry-run", ...)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1415 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1416 parser.add_option("-n", "--noisy", ...)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1417
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1418 (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	1419 some standard options.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1420
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1421 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	1422 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	1423 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	1424
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1425 parser = OptionParser(..., conflict_handler=handler)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1426
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1427 or with a separate call::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1428
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1429 parser.set_conflict_handler(handler)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1430
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1431 The available conflict handlers are:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1432
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1433 ``"error"`` (default)
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1434 assume option conflicts are a programming error and raise
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1435 :exc:`OptionConflictError`
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1436
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1437 ``"resolve"``
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1438 resolve option conflicts intelligently (see below)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1439
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1440
49357 6765946e1ac4 Markup fixes. (optparse.rst probably needs an entire revision pass.) Andrew M. Kuchling <amk@amk.ca> parents: 49324 diff changeset	1441 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	1442 intelligently and add conflicting options to it::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1443
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1444 parser = OptionParser(conflict_handler="resolve")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1445 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	1446 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	1447
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1448 At this point, :mod:`optparse` detects that a previously-added option is already
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1449 using the ``-n`` option string. Since ``conflict_handler`` is ``"resolve"``,
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1450 it resolves the situation by removing ``-n`` from the earlier option's list of
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1451 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	1452 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	1453
68016 c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	1454 Options:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1455 --dry-run do no harm
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1456 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1457 -n, --noisy be noisy
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 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	1460 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	1461 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	1462 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	1463 existing OptionParser::
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 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	1466
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1467 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	1468 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	1469
68016 c7c76cfbdb4e Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from Georg Brandl <georg@python.org> parents: 66962 diff changeset	1470 Options:
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 -n, --noisy be noisy
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1473 --dry-run new dry-run option
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1476 .. _optparse-cleanup:
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 Cleanup
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1479 ^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1480
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1481 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	1482 problem for Python's garbage collector, but you may wish to break the cyclic
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1483 references explicitly by calling :meth:`~OptionParser.destroy` on your
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1484 OptionParser once you are done with it. This is particularly useful in
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1485 long-running applications where large object graphs are reachable from your
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1486 OptionParser.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1487
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1488
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1489 .. _optparse-other-methods:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1490
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1491 Other methods
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1492 ^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1493
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1494 OptionParser supports several other public methods:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1495
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1496 .. method:: OptionParser.set_usage(usage)
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1497
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1498 Set the usage string according to the rules described above for the ``usage``
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1499 constructor keyword argument. Passing ``None`` sets the default usage
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1500 string; use :data:`optparse.SUPPRESS_USAGE` to suppress a usage message.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1501
58156 0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	1502 .. method:: OptionParser.print_usage(file=None)
0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	1503
0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	1504 Print the usage message for the current program (``self.usage``) to file
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1505 (default stdout). Any occurrence of the string ``%prog`` in ``self.usage``
58156 0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	1506 is replaced with the name of the current program. Does nothing if
0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	1507 ``self.usage`` is empty or not defined.
0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	1508
0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	1509 .. method:: OptionParser.get_usage()
0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	1510
0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	1511 Same as :meth:`print_usage` but returns the usage string instead of
0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	1512 printing it.
0fe25e07b77b Merged revisions 77306 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 58117 diff changeset	1513
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1514 .. method:: OptionParser.set_defaults(dest=value, ...)
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1515
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1516 Set default values for several option destinations at once. Using
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1517 :meth:`set_defaults` is the preferred way to set default values for options,
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1518 since multiple options can share the same destination. For example, if
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1519 several "mode" options all set the same destination, any one of them can set
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1520 the default, and the last one wins::
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1521
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1522 parser.add_option("--advanced", action="store_const",
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1523 dest="mode", const="advanced",
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1524 default="novice") # overridden below
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1525 parser.add_option("--novice", action="store_const",
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1526 dest="mode", const="novice",
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1527 default="advanced") # overrides above setting
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1528
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1529 To avoid this confusion, use :meth:`set_defaults`::
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1530
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1531 parser.set_defaults(mode="advanced")
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1532 parser.add_option("--advanced", action="store_const",
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1533 dest="mode", const="advanced")
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1534 parser.add_option("--novice", action="store_const",
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1535 dest="mode", const="novice")
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1536
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1537
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1538 .. _optparse-option-callbacks:
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 Option Callbacks
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1543 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	1544 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	1545 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	1546 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	1547
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1548 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	1549
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1550 * 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	1551
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1552 * 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	1553 arguments, as described below
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1554
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1555
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1556 .. _optparse-defining-callback-option:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1557
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1558 Defining a callback option
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1561 As always, the easiest way to define a callback option is by using the
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1562 :meth:`OptionParser.add_option` method. Apart from :attr:`~Option.action`, the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1563 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	1564
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1565 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	1566
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1567 ``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	1568 defined ``my_callback()`` when you create this callback option. In this simple
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1569 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	1570 which usually means that the option takes no arguments---the mere presence of
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1571 ``-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	1572 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	1573 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	1574 it's covered later in this section.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1575
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1576 :mod:`optparse` always passes four particular arguments to your callback, and it
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1577 will only pass additional arguments if you specify them via
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1578 :attr:`~Option.callback_args` and :attr:`~Option.callback_kwargs`. Thus, the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1579 minimal callback function signature is::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1580
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1581 def my_callback(option, opt, value, parser):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1582
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1583 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	1584
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1585 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	1586 callback option:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1587
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1588 :attr:`~Option.type`
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1589 has its usual meaning: as with the ``"store"`` or ``"append"`` actions, it
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1590 instructs :mod:`optparse` to consume one argument and convert it to
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1591 :attr:`~Option.type`. Rather than storing the converted value(s) anywhere,
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1592 though, :mod:`optparse` passes it to your callback function.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1593
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1594 :attr:`~Option.nargs`
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1595 also has its usual meaning: if it is supplied and > 1, :mod:`optparse` will
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1596 consume :attr:`~Option.nargs` arguments, each of which must be convertible to
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1597 :attr:`~Option.type`. It then passes a tuple of converted values to your
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1598 callback.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1599
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1600 :attr:`~Option.callback_args`
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1601 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	1602
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1603 :attr:`~Option.callback_kwargs`
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1604 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	1605
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1606
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1607 .. _optparse-how-callbacks-called:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1608
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1609 How callbacks are called
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1610 ^^^^^^^^^^^^^^^^^^^^^^^^
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 All callbacks are called as follows::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1613
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1614 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	1615
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1616 where
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1617
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1618 ``option``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1619 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	1620
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1621 ``opt_str``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1622 is the option string seen on the command-line that's triggering the callback.
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1623 (If an abbreviated long option was used, ``opt_str`` will be the full,
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1624 canonical option string---e.g. if the user puts ``--foo`` on the
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1625 command-line as an abbreviation for ``--foobar``, then ``opt_str`` will be
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1626 ``"--foobar"``.)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1627
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1628 ``value``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1629 is the argument to this option seen on the command-line. :mod:`optparse` will
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1630 only expect an argument if :attr:`~Option.type` is set; the type of ``value`` will be
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1631 the type implied by the option's type. If :attr:`~Option.type` for this option is
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1632 ``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	1633 > 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	1634
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1635 ``parser``
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1636 is the OptionParser instance driving the whole thing, mainly useful because
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1637 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	1638
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1639 ``parser.largs``
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1640 the current list of leftover arguments, ie. arguments that have been
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1641 consumed but are neither options nor option arguments. Feel free to modify
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1642 ``parser.largs``, e.g. by adding more arguments to it. (This list will
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1643 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	1644
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1645 ``parser.rargs``
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1646 the current list of remaining arguments, ie. with ``opt_str`` and
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1647 ``value`` (if applicable) removed, and only the arguments following them
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1648 still there. Feel free to modify ``parser.rargs``, e.g. by consuming more
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1649 arguments.
42604 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 ``parser.values``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1652 the object where option values are by default stored (an instance of
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1653 optparse.OptionValues). This lets callbacks use the same mechanism as the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1654 rest of :mod:`optparse` for storing option values; you don't need to mess
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1655 around with globals or closures. You can also access or modify the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1656 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	1657
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1658 ``args``
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1659 is a tuple of arbitrary positional arguments supplied via the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1660 :attr:`~Option.callback_args` option attribute.
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 ``kwargs``
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1663 is a dictionary of arbitrary keyword arguments supplied via
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1664 :attr:`~Option.callback_kwargs`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1665
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 .. _optparse-raising-errors-in-callback:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1668
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1669 Raising errors in a callback
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
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1672 The callback function should raise :exc:`OptionValueError` if there are any
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1673 problems with the option or its argument(s). :mod:`optparse` catches this and
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1674 terminates the program, printing the error message you supply to stderr. Your
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1675 message should be clear, concise, accurate, and mention the option at fault.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1676 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	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-1:
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 1: trivial callback
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1684 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	1685 records that the option was seen::
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 record_foo_seen(option, opt_str, value, parser):
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	1688 parser.values.saw_foo = True
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1689
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1690 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	1691
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1692 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	1693
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 .. _optparse-callback-example-2:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1696
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1697 Callback example 2: check option order
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1698 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1699
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1700 Here's a slightly more interesting example: record the fact that ``-a`` is
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1701 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	1702
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1703 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	1704 if parser.values.b:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1705 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	1706 parser.values.a = 1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1707 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1708 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	1709 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	1710
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1711
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1712 .. _optparse-callback-example-3:
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 Callback example 3: check option order (generalized)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1715 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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 If you want to re-use this callback for several similar options (set a flag, but
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1718 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	1719 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	1720
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1721 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	1722 if parser.values.b:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1723 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	1724 setattr(parser.values, option.dest, 1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1725 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1726 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	1727 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	1728 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	1729
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1730
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1731 .. _optparse-callback-example-4:
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 Callback example 4: check arbitrary condition
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 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	1737 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	1738 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	1739
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1740 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	1741 if is_moon_full():
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1742 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	1743 % opt_str)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1744 setattr(parser.values, option.dest, 1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1745 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1746 parser.add_option("--foo",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1747 action="callback", callback=check_moon, dest="foo")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1748
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1749 (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	1750
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1751
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1752 .. _optparse-callback-example-5:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1753
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1754 Callback example 5: fixed arguments
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1755 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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 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	1758 a fixed number of arguments. Specifying that a callback option takes arguments
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1759 is similar to defining a ``"store"`` or ``"append"`` option: if you define
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1760 :attr:`~Option.type`, then the option takes one argument that must be
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1761 convertible to that type; if you further define :attr:`~Option.nargs`, then the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1762 option takes :attr:`~Option.nargs` arguments.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1763
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1764 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	1765
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1766 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	1767 setattr(parser.values, option.dest, value)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1768 [...]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1769 parser.add_option("--foo",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1770 action="callback", callback=store_value,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1771 type="int", nargs=3, dest="foo")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1772
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1773 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	1774 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	1775 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	1776
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1777
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1778 .. _optparse-callback-example-6:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1779
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1780 Callback example 6: variable arguments
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1783 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	1784 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	1785 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	1786 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	1787 you. In particular, callbacks should implement the conventional rules for bare
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1788 ``--`` and ``-`` arguments:
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1789
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1790 * either ``--`` or ``-`` can be option arguments
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1791
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1792 * bare ``--`` (if not the argument to some option): halt command-line
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1793 processing and discard the ``--``
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1794
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1795 * bare ``-`` (if not the argument to some option): halt command-line
59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1796 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	1797
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1798 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	1799 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	1800 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	1801 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	1802 directly).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1803
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1804 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	1805 arguments::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1806
50257 e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49357 diff changeset	1807 def vararg_callback(option, opt_str, value, parser):
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49357 diff changeset	1808 assert value is None
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49357 diff changeset	1809 value = []
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49357 diff changeset	1810
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49357 diff changeset	1811 def floatable(str):
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49357 diff changeset	1812 try:
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49357 diff changeset	1813 float(str)
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49357 diff changeset	1814 return True
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49357 diff changeset	1815 except ValueError:
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49357 diff changeset	1816 return False
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49357 diff changeset	1817
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49357 diff changeset	1818 for arg in parser.rargs:
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49357 diff changeset	1819 # stop on --foo like options
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49357 diff changeset	1820 if arg[:2] == "--" and len(arg) > 2:
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49357 diff changeset	1821 break
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49357 diff changeset	1822 # stop on -a, but not on -3 or -3.0
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49357 diff changeset	1823 if arg[:1] == "-" and len(arg) > 1 and not floatable(arg):
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49357 diff changeset	1824 break
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49357 diff changeset	1825 value.append(arg)
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49357 diff changeset	1826
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49357 diff changeset	1827 del parser.rargs[:len(value)]
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	1828 setattr(parser.values, option.dest, value)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1829
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1830 [...]
49044 12ef7a92e59b #3040: include 'dest' argument in example; trim some trailing whitespace Andrew M. Kuchling <amk@amk.ca> parents: 47681 diff changeset	1831 parser.add_option("-c", "--callback", dest="vararg_attr",
46538 3c6a25e4dbb5 #2673 Fix example typo in optparse docs Benjamin Peterson <benjamin@python.org> parents: 46078 diff changeset	1832 action="callback", callback=vararg_callback)
42604 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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1835 .. _optparse-extending-optparse:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1836
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1837 Extending :mod:`optparse`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1838 -------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1839
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1840 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	1841 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	1842 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	1843
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1844
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1845 .. _optparse-adding-new-types:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1846
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1847 Adding new types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1848 ^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1849
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1850 To add new types, you need to define your own subclass of :mod:`optparse`'s
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1851 :class:`Option` class. This class has a couple of attributes that define
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1852 :mod:`optparse`'s types: :attr:`~Option.TYPES` and :attr:`~Option.TYPE_CHECKER`.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1853
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1854 .. attribute:: Option.TYPES
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1855
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1856 A tuple of type names; in your subclass, simply define a new tuple
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1857 :attr:`TYPES` that builds on the standard one.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1858
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1859 .. attribute:: Option.TYPE_CHECKER
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1860
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1861 A dictionary mapping type names to type-checking functions. A type-checking
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1862 function has the following signature::
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1863
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1864 def check_mytype(option, opt, value)
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1865
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1866 where ``option`` is an :class:`Option` instance, ``opt`` is an option string
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1867 (e.g., ``-f``), and ``value`` is the string from the command line that must
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1868 be checked and converted to your desired type. ``check_mytype()`` should
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1869 return an object of the hypothetical type ``mytype``. The value returned by
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1870 a type-checking function will wind up in the OptionValues instance returned
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1871 by :meth:`OptionParser.parse_args`, or be passed to a callback as the
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1872 ``value`` parameter.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1873
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1874 Your type-checking function should raise :exc:`OptionValueError` if it
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1875 encounters any problems. :exc:`OptionValueError` takes a single string
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1876 argument, which is passed as-is to :class:`OptionParser`'s :meth:`error`
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1877 method, which in turn prepends the program name and the string ``"error:"``
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1878 and prints everything to stderr before terminating the process.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1879
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1880 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	1881 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	1882 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	1883 complex numbers, but never mind.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1884
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1885 First, the necessary imports::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1886
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1887 from copy import copy
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1888 from optparse import Option, OptionValueError
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1889
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1890 You need to define your type-checker first, since it's referred to later (in the
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1891 :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	1892
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1893 def check_complex(option, opt, value):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1894 try:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1895 return complex(value)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1896 except ValueError:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1897 raise OptionValueError(
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1898 "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	1899
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1900 Finally, the Option subclass::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1901
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1902 class MyOption (Option):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1903 TYPES = Option.TYPES + ("complex",)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1904 TYPE_CHECKER = copy(Option.TYPE_CHECKER)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1905 TYPE_CHECKER["complex"] = check_complex
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 (If we didn't make a :func:`copy` of :attr:`Option.TYPE_CHECKER`, we would end
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1908 up modifying the :attr:`~Option.TYPE_CHECKER` attribute of :mod:`optparse`'s
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1909 Option class. This being Python, nothing stops you from doing that except good
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1910 manners and common sense.)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1911
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1912 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	1913 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	1914 OptionParser to use MyOption instead of Option::
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 parser = OptionParser(option_class=MyOption)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1917 parser.add_option("-c", type="complex")
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 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	1920 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	1921 OptionParser which option class to use::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1922
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1923 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	1924 parser = OptionParser(option_list=option_list)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1925
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1926
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1927 .. _optparse-adding-new-actions:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1928
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1929 Adding new actions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1930 ^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1931
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1932 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	1933 :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	1934
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1935 "store" actions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1936 actions that result in :mod:`optparse` storing a value to an attribute of the
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1937 current OptionValues instance; these options require a :attr:`~Option.dest`
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1938 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	1939
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1940 "typed" actions
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1941 actions that take a value from the command line and expect it to be of a
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1942 certain type; or rather, a string that can be converted to a certain type.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1943 These options require a :attr:`~Option.type` attribute to the Option
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1944 constructor.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1945
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1946 These are overlapping sets: some default "store" actions are ``"store"``,
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1947 ``"store_const"``, ``"append"``, and ``"count"``, while the default "typed"
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1948 actions are ``"store"``, ``"append"``, and ``"callback"``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1949
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1950 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	1951 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	1952
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1953 .. attribute:: Option.ACTIONS
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1954
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1955 All actions must be listed in ACTIONS.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1956
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1957 .. attribute:: Option.STORE_ACTIONS
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1958
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1959 "store" actions are additionally listed here.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1960
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1961 .. attribute:: Option.TYPED_ACTIONS
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1962
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1963 "typed" actions are additionally listed here.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1964
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1965 .. attribute:: Option.ALWAYS_TYPED_ACTIONS
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1966
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1967 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	1968 additionally listed here. The only effect of this is that :mod:`optparse`
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1969 assigns the default type, ``"string"``, to options with no explicit type
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1970 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	1971
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1972 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	1973 :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	1974
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1975 For example, let's add an ``"extend"`` action. This is similar to the standard
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1976 ``"append"`` action, but instead of taking a single value from the command-line
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1977 and appending it to an existing list, ``"extend"`` will take multiple values in
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1978 a single comma-delimited string, and extend an existing list with them. That
66962 59e230297bff Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 65144 diff changeset	1979 is, if ``--names`` is an ``"extend"`` option of type ``"string"``, the command
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	1980 line ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1981
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1982 --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	1983
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1984 would result in a list ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1985
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1986 ["foo", "bar", "blah", "ding", "dong"]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1987
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1988 Again we define a subclass of Option::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1989
58117 a0fce9665f44 Merged revisions 77267 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56814 diff changeset	1990 class MyOption(Option):
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1991
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1992 ACTIONS = Option.ACTIONS + ("extend",)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1993 STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1994 TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1995 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	1996
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1997 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	1998 if action == "extend":
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1999 lvalue = value.split(",")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2000 values.ensure_value(dest, []).extend(lvalue)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2001 else:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2002 Option.take_action(
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2003 self, action, dest, opt, value, values, parser)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2004
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2005 Features of note:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2006
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	2007 * ``"extend"`` both expects a value on the command-line and stores that value
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	2008 somewhere, so it goes in both :attr:`~Option.STORE_ACTIONS` and
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	2009 :attr:`~Option.TYPED_ACTIONS`.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	2010
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	2011 * to ensure that :mod:`optparse` assigns the default type of ``"string"`` to
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	2012 ``"extend"`` actions, we put the ``"extend"`` action in
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	2013 :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	2014
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2015 * :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	2016 control back to :meth:`Option.take_action` for the standard :mod:`optparse`
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	2017 actions.
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	2018
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	2019 * ``values`` is an instance of the optparse_parser.Values class, which provides
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	2020 the very useful :meth:`ensure_value` method. :meth:`ensure_value` is
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	2021 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	2022
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2023 values.ensure_value(attr, value)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2024
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2025 If the ``attr`` attribute of ``values`` doesn't exist or is None, then
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	2026 ensure_value() first sets it to ``value``, and then returns 'value. This is
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	2027 very handy for actions like ``"extend"``, ``"append"``, and ``"count"``, all
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	2028 of which accumulate data in a variable and expect that variable to be of a
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	2029 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	2030 :meth:`ensure_value` means that scripts using your action don't have to worry
56051 2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	2031 about setting a default value for the option destinations in question; they
2ea1fc268542 Merged revisions 74621,74823-74824,74868,74877-74878 via svnmerge from Georg Brandl <georg@python.org> parents: 54350 diff changeset	2032 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	2033 getting it right when it's needed.

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/optparse.rst @ 79675:c0a2294de787 2.7