From 280460271df4ebc3d3129754b4f327a118b0c3b0 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 25 Feb 2011 11:01:04 +0000 Subject: [PATCH] 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. ........ --- Doc/ACKS.txt | 1 + Doc/library/collections.rst | 4 +- Doc/library/ctypes.rst | 5 ++ Doc/library/optparse.rst | 124 ++++++++++++++++++++------ Doc/library/ssl.rst | 25 +++--- Doc/library/string.rst | 8 +- Doc/tools/sphinxext/indexcontent.html | 2 +- Doc/tools/sphinxext/static/basic.css | 4 + Misc/NEWS | 3 + 9 files changed, 131 insertions(+), 45 deletions(-) diff --git a/Doc/ACKS.txt b/Doc/ACKS.txt index 4bab21bae5f..2aa031607e1 100644 --- a/Doc/ACKS.txt +++ b/Doc/ACKS.txt @@ -128,6 +128,7 @@ docs@python.org), and we'll be glad to correct the problem. * Andrew MacIntyre * Vladimir Marangozov * Vincent Marchetti + * Westley Martínez * Laura Matson * Daniel May * Rebecca McCreary diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index ab4cb770d29..38d9fa5c6ef 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -870,7 +870,7 @@ ABC Inherits Abstract Methods Mixin :class:`Sized` ``__len__`` :class:`Callable` ``__call__`` -:class:`Sequence` :class:`Sized`, ``__getitem__`` ``__contains__``. ``__iter__``, ``__reversed__``. +:class:`Sequence` :class:`Sized`, ``__getitem__`` ``__contains__``. ``__iter__``, ``__reversed__``, :class:`Iterable`, ``index``, and ``count`` :class:`Container` @@ -879,7 +879,7 @@ ABC Inherits Abstract Methods Mixin and ``insert`` ``remove``, and ``__iadd__`` :class:`Set` :class:`Sized`, ``__le__``, ``__lt__``, ``__eq__``, ``__ne__``, - :class:`Iterable`, ``__gt__``, ``__ge__``, ``__and__``, ``__or__`` + :class:`Iterable`, ``__gt__``, ``__ge__``, ``__and__``, ``__or__``, :class:`Container` ``__sub__``, ``__xor__``, and ``isdisjoint`` :class:`MutableSet` :class:`Set` ``add`` and Inherited Set methods and diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 631a0fb1759..77eef481c43 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -220,6 +220,8 @@ Fundamental data types +----------------------+----------------------------------------+----------------------------+ | ctypes type | C type | Python type | +======================+========================================+============================+ +| :class:`c_bool` | :c:type:`_Bool` | bool (1) | ++----------------------+----------------------------------------+----------------------------+ | :class:`c_char` | :ctype:`char` | 1-character string | +----------------------+----------------------------------------+----------------------------+ | :class:`c_wchar` | :ctype:`wchar_t` | 1-character unicode string | @@ -258,6 +260,9 @@ Fundamental data types | :class:`c_void_p` | :ctype:`void *` | int/long or ``None`` | +----------------------+----------------------------------------+----------------------------+ +(1) + The constructor accepts any object with a truth value. + All these types can be created by calling them with an optional initializer of the correct type and value:: diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst index d2f7b83e208..d4b121bc8dc 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -64,9 +64,9 @@ and :mod:`optparse` will print out a brief summary of your script's options: .. code-block:: text - usage: [options] + Usage: [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 @@ following to standard output: .. code-block:: text - usage: [options] arg1 arg2 + Usage: [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 @@ 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--- @@ -554,12 +554,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. " @@ -571,20 +592,73 @@ This would result in the following help output: .. code-block:: text - usage: [options] arg1 arg2 + Usage: [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: [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 @@ 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 @@ -1165,9 +1239,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 @@ -1362,7 +1436,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 @@ -1378,7 +1452,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 diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index e69492874b6..a7e78bd6e21 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -505,11 +505,11 @@ To test for the presence of SSL support in a Python installation, user code should use the following idiom:: try: - import ssl + import ssl except ImportError: - pass + pass else: - [ do something that requires SSL support ] + ... # do something that requires SSL support Client-side operation ^^^^^^^^^^^^^^^^^^^^^ @@ -598,16 +598,15 @@ Then you'd read data from the ``connstream`` and do something with it till you are finished with the client (or the client is finished with you):: def deal_with_client(connstream): - - data = connstream.read() - # null data means the client is finished with us - while data: - if not do_something(connstream, data): - # we'll assume do_something returns False - # when we're finished with client - break - data = connstream.read() - # finished with client + data = connstream.read() + # null data means the client is finished with us + while data: + if not do_something(connstream, data): + # we'll assume do_something returns False + # when we're finished with client + break + data = connstream.read() + # finished with client And go back to listening for new client connections. diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 51178094627..59ac1163cf0 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -123,7 +123,7 @@ string formatting behaviors using the same implementation as the built-in The :class:`Formatter` class has the following public methods: - .. method:: format(format_string, *args, *kwargs) + .. method:: format(format_string, *args, **kwargs) :meth:`format` is the primary API method. It takes a format template string, and an arbitrary set of positional and keyword argument. @@ -341,10 +341,10 @@ The meaning of the various alignment options is as follows: | Option | Meaning | +=========+==========================================================+ | ``'<'`` | Forces the field to be left-aligned within the available | - | | space (this is the default). | + | | space (this is the default for most objects). | +---------+----------------------------------------------------------+ | ``'>'`` | Forces the field to be right-aligned within the | - | | available space. | + | | available space (this is the default for numbers). | +---------+----------------------------------------------------------+ | ``'='`` | Forces the padding to be placed after the sign (if any) | | | but before the digits. This is used for printing fields | @@ -615,7 +615,7 @@ Using type-specific formatting:: Nesting arguments and more complex examples:: >>> for align, text in zip('<^>', ['left', 'center', 'right']): - ... '{0:{align}{fill}16}'.format(text, fill=align, align=align) + ... '{0:{fill}{align}16}'.format(text, fill=align, align=align) ... 'left<<<<<<<<<<<<' '^^^^^center^^^^^' diff --git a/Doc/tools/sphinxext/indexcontent.html b/Doc/tools/sphinxext/indexcontent.html index 10a070c6ab3..30963c36dce 100644 --- a/Doc/tools/sphinxext/indexcontent.html +++ b/Doc/tools/sphinxext/indexcontent.html @@ -4,7 +4,7 @@

What's new in Python {{ version }}?
- or all "What's new" documents since 2.0

+ or all "What's new" documents since 2.0

Tutorial
start here

Library Reference
diff --git a/Doc/tools/sphinxext/static/basic.css b/Doc/tools/sphinxext/static/basic.css index 7ba8b55ce95..2b47622ab84 100644 --- a/Doc/tools/sphinxext/static/basic.css +++ b/Doc/tools/sphinxext/static/basic.css @@ -257,6 +257,10 @@ table.docutils td, table.docutils th { background-color: #eef; } +table.docutils td p.last, table.docutils th p.last { + margin-bottom: 0; +} + table.field-list td, table.field-list th { border: 0 !important; } diff --git a/Misc/NEWS b/Misc/NEWS index 7e796eff59b..d58350b2864 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -37,6 +37,9 @@ Core and Builtins Library ------- +- Issue #10680: Fix mutually exclusive arguments for argument groups in + argparse. + - Issue #4681: Allow mmap() to work on file sizes and offsets larger than 4GB, even on 32-bit builds. Initial patch by Ross Lagerwall, adapted for 32-bit Windows.