Merged revisions...

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.
........

Doc/ACKS.txt

@@ -130,6 +130,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

Doc/library/collections.rst

@@ -918,7 +918,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`
 
@@ -927,7 +927,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

Doc/library/ctypes.rst

@@ -216,6 +216,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 bytes object   |
 +----------------------+----------------------------------------+----------------------------+
 | :class:`c_wchar`     | :ctype:`wchar_t`                       | 1-character string         |
@@ -254,6 +256,9 @@ Fundamental data types
 | :class:`c_void_p`    | :ctype:`void *`                        | int 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::
 

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

Doc/library/ssl.rst

@@ -460,11 +460,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
 ^^^^^^^^^^^^^^^^^^^^^
@@ -553,16 +553,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.
 

Doc/library/string.rst

@@ -86,7 +86,7 @@ implementation as the built-in :meth:`format` method.
 
    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.
@@ -306,10 +306,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 |
@@ -582,7 +582,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^^^^^'

Doc/tools/sphinxext/indexcontent.html

@@ -4,7 +4,7 @@
   <table class="contentstable" align="center"><tr>
     <td width="50%">
       <p class="biglink"><a class="biglink" href="{{ pathto("whatsnew/" + version) }}">What's new in Python {{ version }}?</a><br/>
-         <span class="linkdescr">or <a href="{{ pathto("whatsnew/index") }}">all "What's new" documents</a> since 2.0</span></span></p>
+         <span class="linkdescr">or <a href="{{ pathto("whatsnew/index") }}">all "What's new" documents</a> since 2.0</span></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("tutorial/index") }}">Tutorial</a><br/>
          <span class="linkdescr">start here</span></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("library/index") }}">Library Reference</a><br/>

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;
 }
@@ -342,7 +346,7 @@ p.deprecated {
 }
 
 .footnote:target  {
-    background-color: #ffa
+    background-color: #ffa;
 }
 
 .impl-detail {

Lib/email/charset.py

@@ -294,7 +294,7 @@ class Charset:
         """Header-encode a string by converting it first to bytes.
 
         This is similar to `header_encode()` except that the string is fit
-        into maximum line lengths as given by the arguments.
+        into maximum line lengths as given by the argument.
 
         :param string: A unicode string for the header.  It must be possible
             to encode this string to bytes using the character set's
@@ -305,8 +305,6 @@ class Charset:
             and should never be exhausted.  The maximum line lengths should
             not count the RFC 2047 chrome.  These line lengths are only a
             hint; the splitter does the best it can.
-        :param firstmaxlen: The maximum line length of the first line.  If
-            None (the default), then `maxlen` is used for the first line.
         :return: Lines of encoded strings, each with RFC 2047 chrome.
         """
         # See which encoding we should use.

Lib/http/client.py

@@ -663,6 +663,7 @@ class HTTPConnection:
         self._method = None
         self._tunnel_host = None
         self._tunnel_port = None
+        self._tunnel_headers = {}
 
         self._set_hostport(host, port)
         if strict is not None:
@@ -698,13 +699,14 @@ class HTTPConnection:
 
     def _tunnel(self):
         self._set_hostport(self._tunnel_host, self._tunnel_port)
-        connect_str = "CONNECT %s:%d HTTP/1.0\r\n" %(self.host, self.port)
+        connect_str = "CONNECT %s:%d HTTP/1.0\r\n" % (self.host, self.port)
         connect_bytes = connect_str.encode("ascii")
         self.send(connect_bytes)
-        for header, value in self._tunnel_headers.iteritems():
+        for header, value in self._tunnel_headers.items():
             header_str = "%s: %s\r\n" % (header, value)
             header_bytes = header_str.encode("ascii")
             self.send(header_bytes)
+        self.send(b'\r\n')
 
         response = self.response_class(self.sock, strict = self.strict,
                                        method = self._method)