Merged revisions 87627,87638,87760,87986,88108,88115,88165,88263,88329,88364-88365,88423-88424 via svnmerge from
svn+ssh://pythondev@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.
........
r87760 | georg.brandl | 2011-01-05 11:59:48 +0100 (Mi, 05 Jan 2011) | 1 line
Fix duplicate end tag.
........
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.
........
r88165 | georg.brandl | 2011-01-24 20:53:18 +0100 (Mo, 24 Jan 2011) | 1 line
Typo fix.
........
r88263 | georg.brandl | 2011-01-30 13:19:35 +0100 (So, 30 Jan 2011) | 1 line
#10680: fix mutually exclusive arguments in argument groups.
........
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.
........
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.
........
diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst
index d2f7b83..d4b121b 100644
--- a/Doc/library/optparse.rst
+++ b/Doc/library/optparse.rst
@@ -64,9 +64,9 @@
.. 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
@@ -495,9 +495,9 @@
.. 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)
@@ -521,7 +521,7 @@
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---
@@ -554,12 +554,33 @@
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. "
@@ -571,20 +592,73 @@
.. 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)
- -fFILE, --file=FILE write output to FILE
- -mMODE, --mode=MODE interaction mode: one of 'novice', 'intermediate'
- [default], 'expert'
+ 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 of these options is at your own risk. It is believed that
- some of them bite.
- -g Group option.
+ 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:
+
+.. method:: OptionParser.get_option_group(opt_str)
+
+ Return, if defined, the :class:`OptionGroup` that has the title or the long
+ description equals to *opt_str*
.. _optparse-printing-version-string:
@@ -656,14 +730,14 @@
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
@@ -1165,9 +1239,9 @@
.. 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
@@ -1362,7 +1436,7 @@
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
@@ -1378,7 +1452,7 @@
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