diff options
author | Georg Brandl <georg@python.org> | 2011-02-25 10:18:11 (GMT) |
---|---|---|
committer | Georg Brandl <georg@python.org> | 2011-02-25 10:18:11 (GMT) |
commit | 2774310c27c6a8f4eb0d7d35e977767fa70d144f (patch) | |
tree | 9d16c573424046bb167f2e7bf68729f5063eb8bc /Doc/library/optparse.rst | |
parent | d98934c48381a1128fc5e2d0fa1d57f9ec584041 (diff) | |
download | cpython-2774310c27c6a8f4eb0d7d35e977767fa70d144f.zip cpython-2774310c27c6a8f4eb0d7d35e977767fa70d144f.tar.gz cpython-2774310c27c6a8f4eb0d7d35e977767fa70d144f.tar.bz2 |
Merged revisions 87627,87638,87739,87760,87771,87787,87984,87986,88108,88115,88144,88165,88329,88364-88365,88369-88370,88423-88424 via svnmerge from
svn+ssh://svn.python.org/python/branches/py3k
........
r87627 | georg.brandl | 2011-01-02 15:23:43 +0100 (So, 02 Jan 2011) | 1 line
#1665333: add more docs for optparse.OptionGroup.
........
r87638 | georg.brandl | 2011-01-02 20:07:51 +0100 (So, 02 Jan 2011) | 1 line
Fix code indentation.
........
r87739 | georg.brandl | 2011-01-04 18:27:13 +0100 (Di, 04 Jan 2011) | 1 line
Fix exception catching.
........
r87760 | georg.brandl | 2011-01-05 11:59:48 +0100 (Mi, 05 Jan 2011) | 1 line
Fix duplicate end tag.
........
r87771 | georg.brandl | 2011-01-05 22:47:47 +0100 (Mi, 05 Jan 2011) | 1 line
On Py3k, -tt and -3 are no-op and unsupported respectively.
........
r87787 | georg.brandl | 2011-01-06 10:15:45 +0100 (Do, 06 Jan 2011) | 1 line
Remove doc for nonexisting parameter.
........
r87984 | georg.brandl | 2011-01-13 08:24:40 +0100 (Do, 13 Jan 2011) | 1 line
Add semicolon for consistency.
........
r87986 | georg.brandl | 2011-01-13 08:31:18 +0100 (Do, 13 Jan 2011) | 1 line
Fix the example output of count().
........
r88108 | georg.brandl | 2011-01-19 09:42:03 +0100 (Mi, 19 Jan 2011) | 1 line
Suppress trailing spaces in table paragraphs.
........
r88115 | georg.brandl | 2011-01-19 21:05:49 +0100 (Mi, 19 Jan 2011) | 1 line
#10944: add c_bool to types table.
........
r88144 | georg.brandl | 2011-01-22 23:06:24 +0100 (Sa, 22 Jan 2011) | 1 line
#10983: fix several bugs in the _tunnel implementation that seem to have missed while porting between branches. A unittest is needed!
........
r88165 | georg.brandl | 2011-01-24 20:53:18 +0100 (Mo, 24 Jan 2011) | 1 line
Typo fix.
........
r88329 | georg.brandl | 2011-02-03 08:08:25 +0100 (Do, 03 Feb 2011) | 1 line
Punctuation typos.
........
r88364 | georg.brandl | 2011-02-07 13:10:46 +0100 (Mo, 07 Feb 2011) | 1 line
#11138: fix order of fill and align specifiers.
........
r88365 | georg.brandl | 2011-02-07 13:13:58 +0100 (Mo, 07 Feb 2011) | 1 line
#8691: document that right alignment is default for numbers.
........
r88369 | georg.brandl | 2011-02-07 16:30:45 +0100 (Mo, 07 Feb 2011) | 1 line
Consistent heading spacing, and fix two typos.
........
r88370 | georg.brandl | 2011-02-07 16:44:27 +0100 (Mo, 07 Feb 2011) | 1 line
Spelling fixes.
........
r88423 | georg.brandl | 2011-02-15 13:41:17 +0100 (Di, 15 Feb 2011) | 1 line
Apply logging SocketHandler doc update by Vinay.
........
r88424 | georg.brandl | 2011-02-15 13:44:43 +0100 (Di, 15 Feb 2011) | 1 line
Remove editing slip.
........
Diffstat (limited to 'Doc/library/optparse.rst')
-rw-r--r-- | Doc/library/optparse.rst | 124 |
1 files changed, 99 insertions, 25 deletions
diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst index 06a6ae7..87ec4de 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -55,9 +55,9 @@ and :mod:`optparse` will print out a brief summary of your script's options: .. code-block:: text - usage: <yourscript> [options] + Usage: <yourscript> [options] - options: + Options: -h, --help show this help message and exit -f FILE, --file=FILE write report to FILE -q, --quiet don't print status messages to stdout @@ -486,9 +486,9 @@ following to standard output: .. code-block:: text - usage: <yourscript> [options] arg1 arg2 + Usage: <yourscript> [options] arg1 arg2 - options: + Options: -h, --help show this help message and exit -v, --verbose make lots of noise [default] -q, --quiet be vewwy quiet (I'm hunting wabbits) @@ -512,7 +512,7 @@ help message: is then printed before the detailed option help. If you don't supply a usage string, :mod:`optparse` uses a bland but sensible - default: ``"usage: %prog [options]"``, which is fine if your script doesn't + default: ``"Usage: %prog [options]"``, which is fine if your script doesn't take any positional arguments. * every option defines a help string, and doesn't worry about line-wrapping--- @@ -544,12 +544,33 @@ help message: default value. If an option has no default value (or the default value is ``None``), ``%default`` expands to ``none``. +Grouping Options +++++++++++++++++ + When dealing with many options, it is convenient to group these options for better help output. An :class:`OptionParser` can contain several option groups, each of which can contain several options. -Continuing with the parser defined above, adding an :class:`OptionGroup` to a -parser is easy:: +An option group is obtained using the class :class:`OptionGroup`: + +.. class:: OptionGroup(parser, title, description=None) + + where + + * parser is the :class:`OptionParser` instance the group will be insterted in + to + * title is the group title + * description, optional, is a long description of the group + +:class:`OptionGroup` inherits from :class:`OptionContainer` (like +:class:`OptionParser`) and so the :meth:`add_option` method can be used to add +an option to the group. + +Once all the options are declared, using the :class:`OptionParser` method +:meth:`add_option_group` the group is added to the previously defined parser. + +Continuing with the parser defined in the previous section, adding an +:class:`OptionGroup` to a parser is easy:: group = OptionGroup(parser, "Dangerous Options", "Caution: use these options at your own risk. " @@ -561,20 +582,73 @@ This would result in the following help output: .. code-block:: text - usage: [options] arg1 arg2 + Usage: <yourscript> [options] arg1 arg2 + + Options: + -h, --help show this help message and exit + -v, --verbose make lots of noise [default] + -q, --quiet be vewwy quiet (I'm hunting wabbits) + -f FILE, --filename=FILE + write output to FILE + -m MODE, --mode=MODE interaction mode: novice, intermediate, or + expert [default: intermediate] + + Dangerous Options: + Caution: use these options at your own risk. It is believed that some + of them bite. + + -g Group option. + +A bit more complete example might invole using more than one group: still +extendind the previous example:: + + group = OptionGroup(parser, "Dangerous Options", + "Caution: use these options at your own risk. " + "It is believed that some of them bite.") + group.add_option("-g", action="store_true", help="Group option.") + parser.add_option_group(group) + + group = OptionGroup(parser, "Debug Options") + group.add_option("-d", "--debug", action="store_true", + help="Print debug information") + group.add_option("-s", "--sql", action="store_true", + help="Print all SQL statements executed") + group.add_option("-e", action="store_true", help="Print every action done") + parser.add_option_group(group) + +that results in the following output: + +.. code-block:: text + + Usage: <yourscript> [options] arg1 arg2 + + Options: + -h, --help show this help message and exit + -v, --verbose make lots of noise [default] + -q, --quiet be vewwy quiet (I'm hunting wabbits) + -f FILE, --filename=FILE + write output to FILE + -m MODE, --mode=MODE interaction mode: novice, intermediate, or expert + [default: intermediate] + + Dangerous Options: + Caution: use these options at your own risk. It is believed that some + of them bite. + + -g Group option. + + Debug Options: + -d, --debug Print debug information + -s, --sql Print all SQL statements executed + -e Print every action done + +Another interesting method, in particular when working programmatically with +option groups is: - options: - -h, --help show this help message and exit - -v, --verbose make lots of noise [default] - -q, --quiet be vewwy quiet (I'm hunting wabbits) - -fFILE, --file=FILE write output to FILE - -mMODE, --mode=MODE interaction mode: one of 'novice', 'intermediate' - [default], 'expert' +.. method:: OptionParser.get_option_group(opt_str) - Dangerous Options: - Caution: use of these options is at your own risk. It is believed that - some of them bite. - -g Group option. + Return, if defined, the :class:`OptionGroup` that has the title or the long + description equals to *opt_str* .. _optparse-printing-version-string: @@ -646,14 +720,14 @@ Consider the first example above, where the user passes ``4x`` to an option that takes an integer:: $ /usr/bin/foo -n 4x - usage: foo [options] + Usage: foo [options] foo: error: option -n: invalid integer value: '4x' Or, where the user fails to pass a value at all:: $ /usr/bin/foo -n - usage: foo [options] + Usage: foo [options] foo: error: -n option requires an argument @@ -1155,9 +1229,9 @@ must specify for any option using that action. .. code-block:: text - usage: foo.py [options] + Usage: foo.py [options] - options: + Options: -h, --help Show this help message and exit -v Be moderately verbose --file=FILENAME Input file to read data from @@ -1352,7 +1426,7 @@ it resolves the situation by removing ``-n`` from the earlier option's list of option strings. Now ``--dry-run`` is the only way for the user to activate that option. If the user asks for help, the help message will reflect that:: - options: + Options: --dry-run do no harm [...] -n, --noisy be noisy @@ -1368,7 +1442,7 @@ existing OptionParser:: At this point, the original ``-n``/``--dry-run`` option is no longer accessible, so :mod:`optparse` removes it, leaving this help text:: - options: + Options: [...] -n, --noisy be noisy --dry-run new dry-run option |