merge 2.7.4 release branch

Doc/c-api/unicode.rst

@@ -252,6 +252,8 @@ APIs:
    .. % because not all compilers support the %z width modifier -- we fake it
    .. % when necessary via interpolating PY_FORMAT_SIZE_T.
 
+   .. tabularcolumns:: |l|l|L|
+
    +-------------------+---------------------+--------------------------------+
    | Format Characters | Type                | Comment                        |
    +===================+=====================+================================+

Doc/distutils/apiref.rst

@@ -26,6 +26,8 @@ setup script). Indirectly provides the  :class:`distutils.dist.Distribution` and
    The setup function takes a large number of arguments. These are laid out in the
    following table.
 
+   .. tabularcolumns:: |l|L|L|
+
    +--------------------+--------------------------------+-------------------------------------------------------------+
    | argument name      | value                          | type                                                        |
    +====================+================================+=============================================================+
@@ -125,6 +127,8 @@ setup script). Indirectly provides the  :class:`distutils.dist.Distribution` and
 
    *stop_after* tells :func:`setup` when to stop processing; possible  values:
 
+   .. tabularcolumns:: |l|L|
+
    +---------------+---------------------------------------------+
    | value         | description                                 |
    +===============+=============================================+
@@ -165,6 +169,8 @@ the full reference.
    The Extension class describes a single C or C++extension module in a setup
    script. It accepts the following keyword arguments in its constructor
 
+   .. tabularcolumns:: |l|L|l|
+
    +------------------------+--------------------------------+---------------------------+
    | argument name          | value                          | type                      |
    +========================+================================+===========================+
@@ -1556,6 +1562,8 @@ lines, and joining lines with backslashes.
 
    The options are all boolean, and affect the values returned by :meth:`readline`
 
+   .. tabularcolumns:: |l|L|l|
+
    +------------------+--------------------------------+---------+
    | option name      | description                    | default |
    +==================+================================+=========+

Doc/faq/extending.rst

@@ -2,7 +2,9 @@
 Extending/Embedding FAQ
 =======================
 
-.. contents::
+.. only:: html
+
+   .. contents::
 
 .. highlight:: c
 

Doc/faq/general.rst

@@ -4,7 +4,10 @@
 General Python FAQ
 ==================
 
-.. contents::
+.. only:: html
+
+   .. contents::
+
 
 General Information
 ===================

Doc/faq/gui.rst

@@ -4,7 +4,9 @@
 Graphic User Interface FAQ
 ==========================
 
-.. contents::
+.. only:: html
+
+   .. contents::
 
 What platform-independent GUI toolkits exist for Python?
 ========================================================

Doc/faq/library.rst

@@ -4,7 +4,9 @@
 Library and Extension FAQ
 =========================
 
-.. contents::
+.. only:: html
+
+   .. contents::
 
 General Library Questions
 =========================

Doc/faq/programming.rst

@@ -4,7 +4,9 @@
 Programming FAQ
 ===============
 
-.. contents::
+.. only:: html
+
+   .. contents::
 
 General Questions
 =================

Doc/faq/windows.rst

@@ -6,7 +6,9 @@
 Python on Windows FAQ
 =====================
 
-.. contents::
+.. only:: html
+
+   .. contents::
 
 How do I run a Python program under Windows?
 --------------------------------------------

Doc/howto/argparse.rst

@@ -11,7 +11,7 @@ recommended command-line parsing module in the Python standard library.
 
 .. note::
 
-   There's two other modules that fulfill the same task, namely
+   There are two other modules that fulfill the same task, namely
    :mod:`getopt` (an equivalent for :c:func:`getopt` from the C
    language) and the deprecated :mod:`optparse`.
    Note also that :mod:`argparse` is based on :mod:`optparse`,
@@ -668,7 +668,7 @@ Conflicting options
 So far, we have been working with two methods of an
 :class:`argparse.ArgumentParser` instance. Let's introduce a third one,
 :meth:`add_mutually_exclusive_group`. It allows for us to specify options that
-conflict with each other. Let's also change the rest of the program make the
+conflict with each other. Let's also change the rest of the program to make the
 new functionality makes more sense:
 we'll introduce the ``--quiet`` option,
 which will be the opposite of the ``--verbose`` one::

Doc/howto/logging-cookbook.rst

@@ -773,7 +773,7 @@ UTF-8, then you need to do the following:
 
       u'ASCII section\ufeffUnicode section'
 
-   The Unicode code point ``u'\feff```, when encoded using UTF-8, will be
+   The Unicode code point ``u'\ufeff'``, when encoded using UTF-8, will be
    encoded as a UTF-8 BOM -- the byte-string ``'\xef\xbb\xbf'``.
 
 #. Replace the ASCII section with whatever placeholders you like, but make sure

Doc/howto/logging.rst

@@ -63,6 +63,8 @@ The logging functions are named after the level or severity of the events
 they are used to track. The standard levels and their applicability are
 described below (in increasing order of severity):
 
+.. tabularcolumns:: |l|L|
+
 +--------------+---------------------------------------------+
 | Level        | When it's used                              |
 +==============+=============================================+

Doc/install/index.rst

@@ -235,6 +235,8 @@ by how you built/installed Python itself.  On Unix (and Mac OS X, which is also
 Unix-based), it also depends on whether the module distribution being installed
 is pure Python or contains extensions ("non-pure"):
 
+.. tabularcolumns:: |l|l|l|l|
+
 +-----------------+-----------------------------------------------------+--------------------------------------------------+-------+
 | Platform        | Standard installation location                      | Default value                                    | Notes |
 +=================+=====================================================+==================================================+=======+

Doc/library/codecs.rst

@@ -320,6 +320,8 @@ To simplify and standardize error handling, the :meth:`encode` and
 providing the *errors* string argument.  The following string values are defined
 and implemented by all standard Python codecs:
 
+.. tabularcolumns:: |l|L|
+
 +-------------------------+-----------------------------------------------+
 | Value                   | Meaning                                       |
 +=========================+===============================================+
@@ -887,6 +889,8 @@ particular, the following variants typically exist:
 
 * an IBM PC code page, which is ASCII compatible
 
+.. tabularcolumns:: |l|p{0.3\linewidth}|p{0.3\linewidth}|
+
 +-----------------+--------------------------------+--------------------------------+
 | Codec           | Aliases                        | Languages                      |
 +=================+================================+================================+
@@ -1103,6 +1107,8 @@ For the codecs listed below, the result in the "encoding" direction is always a
 byte string. The result of the "decoding" direction is listed as operand type in
 the table.
 
+.. tabularcolumns:: |l|p{0.3\linewidth}|l|p{0.3\linewidth}|
+
 +--------------------+---------------------------+----------------+---------------------------+
 | Codec              | Aliases                   | Operand type   | Purpose                   |
 +====================+===========================+================+===========================+

Doc/library/datetime.rst

@@ -555,6 +555,13 @@ Instance methods:
    section :ref:`strftime-strptime-behavior`.
 
 
+.. method:: date.__format__(format)
+
+   Same as :meth:`.date.strftime`. This makes it possible to specify format
+   string for a :class:`.date` object when using :meth:`str.format`.
+   See section :ref:`strftime-strptime-behavior`.
+
+
 Example of counting days to an event::
 
     >>> import time
@@ -605,6 +612,8 @@ Example of working with :class:`date`:
     '11/03/02'
     >>> d.strftime("%A %d. %B %Y")
     'Monday 11. March 2002'
+    >>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, "day", "month")
+    'The day is 11, the month is March.'
 
 
 .. _datetime-datetime:
@@ -1044,6 +1053,13 @@ Instance methods:
    string.  See section :ref:`strftime-strptime-behavior`.
 
 
+.. method:: datetime.__format__(format)
+
+   Same as :meth:`.datetime.strftime`.  This makes it possible to specify format
+   string for a :class:`.datetime` object when using :meth:`str.format`.
+   See section :ref:`strftime-strptime-behavior`.
+
+
 Examples of working with datetime objects:
 
 .. doctest::
@@ -1088,6 +1104,8 @@ Examples of working with datetime objects:
     >>> # Formatting datetime
     >>> dt.strftime("%A, %d. %B %Y %I:%M%p")
     'Tuesday, 21. November 2006 04:30PM'
+    >>> 'The {1} is {0:%d}, the {2} is {0:%B}, the {3} is {0:%I:%M%p}.'.format(dt, "day", "month", "time")
+    'The day is 21, the month is November, the time is 04:30PM.'
 
 Using datetime with tzinfo:
 
@@ -1268,6 +1286,13 @@ Instance methods:
    See section :ref:`strftime-strptime-behavior`.
 
 
+.. method:: time.__format__(format)
+
+   Same as :meth:`.time.strftime`. This makes it possible to specify format string
+   for a :class:`.time` object when using :meth:`str.format`.
+   See section :ref:`strftime-strptime-behavior`.
+
+
 .. method:: time.utcoffset()
 
    If :attr:`tzinfo` is ``None``, returns ``None``, else returns
@@ -1314,6 +1339,8 @@ Example:
     'Europe/Prague'
     >>> t.strftime("%H:%M:%S %Z")
     '12:10:30 Europe/Prague'
+    >>> 'The {} is {:%H:%M}.'.format("time", t)
+    'The time is 12:10.'
 
 
 .. _datetime-tzinfo:

Doc/library/email.mime.rst

@@ -199,3 +199,12 @@ Here are the classes:
       Transfer Encoding now happens implicitly based on the *_charset*
       argument.
 
+   Unless the ``_charset`` parameter is explicitly set to ``None``, the
+   MIMEText object created will have both a :mailheader:`Content-Type` header
+   with a ``charset`` parameter, and a :mailheader:`Content-Transfer-Endcoding`
+   header.  This means that a subsequent ``set_payload`` call will not result
+   in an encoded payload, even if a charset is passed in the ``set_payload``
+   command.  You can "reset" this behavior by deleting the
+   ``Content-Transfer-Encoding`` header, after which a ``set_payload`` call
+   will automatically encode the new payload (and add a new
+   :mailheader:`Content-Transfer-Encoding` header).

Doc/library/itertools.rst

@@ -828,6 +828,18 @@ which incur interpreter overhead.
        indices = sorted(random.randrange(n) for i in xrange(r))
        return tuple(pool[i] for i in indices)
 
+   def tee_lookahead(t, i):
+       """Inspect the i-th upcomping value from a tee object
+          while leaving the tee object at its current position.
+
+          Raise an IndexError if the underlying iterator doesn't
+          have enough values.
+
+       """
+       for value in islice(t.__copy__(), i, None):
+           return value
+       raise IndexError(i)
+
 Note, many of the above recipes can be optimized by replacing global lookups
 with local variables defined as default values.  For example, the
 *dotproduct* recipe can be written as::

Doc/library/json.rst

@@ -125,7 +125,8 @@ Basic Usage
                    default=None, sort_keys=False, **kw)
 
    Serialize *obj* as a JSON formatted stream to *fp* (a ``.write()``-supporting
-   :term:`file-like object`).
+   :term:`file-like object`) using this :ref:`conversion table
+   <py-to-json-table>`.
 
    If *skipkeys* is ``True`` (default: ``False``), then dict keys that are not
    of a basic type (:class:`str`, :class:`unicode`, :class:`int`, :class:`long`,
@@ -188,9 +189,10 @@ Basic Usage
                     indent=None, separators=None, encoding="utf-8", \
                     default=None, sort_keys=False, **kw)
 
-   Serialize *obj* to a JSON formatted :class:`str`.  If *ensure_ascii* is
-   ``False``, the result may contain non-ASCII characters and the return value
-   may be a :class:`unicode` instance.
+   Serialize *obj* to a JSON formatted :class:`str` using this :ref:`conversion
+   table <py-to-json-table>`.  If *ensure_ascii* is ``False``, the result may
+   contain non-ASCII characters and the return value may be a :class:`unicode`
+   instance.
 
    The arguments have the same meaning as in :func:`dump`.
 
@@ -206,7 +208,8 @@ Basic Usage
 .. function:: load(fp[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, **kw]]]]]]]])
 
    Deserialize *fp* (a ``.read()``-supporting :term:`file-like object`
-   containing a JSON document) to a Python object.
+   containing a JSON document) to a Python object using this :ref:`conversion
+   table <json-to-py-table>`.
 
    If the contents of *fp* are encoded with an ASCII based encoding other than
    UTF-8 (e.g. latin-1), then an appropriate *encoding* name must be specified.
@@ -257,7 +260,8 @@ Basic Usage
 .. function:: loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, **kw]]]]]]]])
 
    Deserialize *s* (a :class:`str` or :class:`unicode` instance containing a JSON
-   document) to a Python object.
+   document) to a Python object using this :ref:`conversion table
+   <json-to-py-table>`.
 
    If *s* is a :class:`str` instance and is encoded with an ASCII based encoding
    other than UTF-8 (e.g. latin-1), then an appropriate *encoding* name must be
@@ -276,6 +280,8 @@ Encoders and Decoders
 
    Performs the following translations in decoding by default:
 
+   .. _json-to-py-table:
+
    +---------------+-------------------+
    | JSON          | Python            |
    +===============+===================+
@@ -364,6 +370,8 @@ Encoders and Decoders
 
    Supports the following objects and types by default:
 
+   .. _py-to-json-table:
+
    +-------------------+---------------+
    | Python            | JSON          |
    +===================+===============+

Doc/library/locale.rst

@@ -59,6 +59,8 @@ The :mod:`locale` module defines the following exception and functions:
    Returns the database of the local conventions as a dictionary. This dictionary
    has the following strings as keys:
 
+   .. tabularcolumns:: |l|l|L|
+
    +----------------------+-------------------------------------+--------------------------------+
    | Category             | Key                                 | Meaning                        |
    +======================+=====================================+================================+

Doc/library/logging.rst

@@ -893,6 +893,8 @@ functions.
 
    The following keyword arguments are supported.
 
+   .. tabularcolumns:: |l|L|
+
    +--------------+---------------------------------------------+
    | Format       | Description                                 |
    +==============+=============================================+

Doc/library/socket.rst

@@ -72,7 +72,7 @@ numeric address in *host* portion.
    tuple, and the fields depend on the address type. The general tuple form is
    ``(addr_type, v1, v2, v3 [, scope])``, where:
 
-   - *addr_type* is one of :const;`TIPC_ADDR_NAMESEQ`, :const:`TIPC_ADDR_NAME`,
+   - *addr_type* is one of :const:`TIPC_ADDR_NAMESEQ`, :const:`TIPC_ADDR_NAME`,
      or :const:`TIPC_ADDR_ID`.
    - *scope* is one of :const:`TIPC_ZONE_SCOPE`, :const:`TIPC_CLUSTER_SCOPE`,
      and :const:`TIPC_NODE_SCOPE`.

Doc/library/ssl.rst

@@ -298,14 +298,30 @@ Functions, Constants, and Exceptions
 SSLSocket Objects
 -----------------
 
-.. method:: SSLSocket.read([nbytes=1024])
-
-   Reads up to ``nbytes`` bytes from the SSL-encrypted channel and returns them.
-
-.. method:: SSLSocket.write(data)
-
-   Writes the ``data`` to the other side of the connection, using the SSL
-   channel to encrypt.  Returns the number of bytes written.
+SSL sockets provide the following methods of :ref:`socket-objects`:
+
+- :meth:`~socket.socket.accept()`
+- :meth:`~socket.socket.bind()`
+- :meth:`~socket.socket.close()`
+- :meth:`~socket.socket.connect()`
+- :meth:`~socket.socket.fileno()`
+- :meth:`~socket.socket.getpeername()`, :meth:`~socket.socket.getsockname()`
+- :meth:`~socket.socket.getsockopt()`, :meth:`~socket.socket.setsockopt()`
+- :meth:`~socket.socket.gettimeout()`, :meth:`~socket.socket.settimeout()`,
+  :meth:`~socket.socket.setblocking()`
+- :meth:`~socket.socket.listen()`
+- :meth:`~socket.socket.makefile()`
+- :meth:`~socket.socket.recv()`, :meth:`~socket.socket.recv_into()`
+  (but passing a non-zero ``flags`` argument is not allowed)
+- :meth:`~socket.socket.send()`, :meth:`~socket.socket.sendall()` (with
+  the same limitation)
+- :meth:`~socket.socket.shutdown()`
+
+However, since the SSL (and TLS) protocol has its own framing atop
+of TCP, the SSL sockets abstraction can, in certain respects, diverge from
+the specification of normal, OS-level sockets.
+
+SSL sockets also have the following additional methods and attributes:
 
 .. method:: SSLSocket.getpeercert(binary_form=False)
 

Doc/library/stdtypes.rst

@@ -1738,9 +1738,10 @@ The constructors for both classes work the same:
            frozenset([iterable])
 
    Return a new set or frozenset object whose elements are taken from
-   *iterable*.  The elements of a set must be hashable.  To represent sets of
-   sets, the inner sets must be :class:`frozenset` objects.  If *iterable* is
-   not specified, a new empty set is returned.
+   *iterable*.  The elements of a set must be :term:`hashable`.  To
+   represent sets of sets, the inner sets must be :class:`frozenset`
+   objects.  If *iterable* is not specified, a new empty set is
+   returned.
 
    Instances of :class:`set` and :class:`frozenset` provide the following
    operations:

Doc/library/subprocess.rst

@@ -145,6 +145,8 @@ use cases, the underlying :class:`Popen` interface can be used directly.
 
    .. versionadded:: 2.7
 
+   ..
+
    .. warning::
 
       Invoking the system shell with ``shell=True`` can be a security hazard
@@ -225,7 +227,7 @@ default values. The arguments that are most commonly needed are:
 
    When *stdout* or *stderr* are pipes and *universal_newlines* is
    ``True`` then all line endings will be converted to ``'\n'`` as described
-   for the :term:`universal newlines` `'U'`` mode argument to :func:`open`.
+   for the :term:`universal newlines` ``'U'`` mode argument to :func:`open`.
 
    If *shell* is ``True``, the specified command will be executed through
    the shell.  This can be useful if you are using Python primarily for the

Doc/library/sys.rst

@@ -302,6 +302,8 @@ always available.
    5.2.4.2.2 of the 1999 ISO/IEC C standard [C99]_, 'Characteristics of
    floating types', for details.
 
+   .. tabularcolumns:: |l|l|L|
+
    +---------------------+----------------+--------------------------------------------------+
    | attribute           | float.h macro  | explanation                                      |
    +=====================+================+==================================================+
@@ -599,6 +601,8 @@ always available.
    A struct sequence that holds information about Python's
    internal representation of integers.  The attributes are read only.
 
+   .. tabularcolumns:: |l|L|
+
    +-------------------------+----------------------------------------------+
    | Attribute               | Explanation                                  |
    +=========================+==============================================+
@@ -774,7 +778,7 @@ always available.
    independent Python files are installed; by default, this is the string
    ``'/usr/local'``.  This can be set at build time with the ``--prefix``
    argument to the :program:`configure` script.  The main collection of Python
-   library modules is installed in the directory :file:`{prefix}/lib/python{X.Y}``
+   library modules is installed in the directory :file:`{prefix}/lib/python{X.Y}`
    while the platform independent header files (all except :file:`pyconfig.h`) are
    stored in :file:`{prefix}/include/python{X.Y}`, where *X.Y* is the version
    number of Python, for example ``2.7``.

Doc/library/time.rst

@@ -547,8 +547,8 @@ The module defines the following functions and data items:
       More object-oriented interface to dates and times.
 
    Module :mod:`locale`
-      Internationalization services.  The locale settings can affect the return values
-      for some of  the functions in the :mod:`time` module.
+      Internationalization services.  The locale setting affects the interpretation
+      of many format specifiers in :func:`strftime` and :func:`strptime`.
 
    Module :mod:`calendar`
       General calendar-related functions.   :func:`timegm` is the inverse of

Doc/library/turtle.rst

@@ -2173,9 +2173,11 @@ It contains:
 
 The demoscripts are:
 
+.. tabularcolumns:: |l|L|L|
+
 +----------------+------------------------------+-----------------------+
 | Name           | Description                  | Features              |
-+----------------+------------------------------+-----------------------+
++================+==============================+=======================+
 | bytedesign     | complex classical            | :func:`tracer`, delay,|
 |                | turtlegraphics pattern       | :func:`update`        |
 +----------------+------------------------------+-----------------------+

Doc/library/unittest.rst

@@ -638,7 +638,7 @@ the test unless the passed object has a certain attribute::
    def skipUnlessHasattr(obj, attr):
        if hasattr(obj, attr):
            return lambda func: func
-       return unittest.skip("{0!r} doesn't have {1!r}".format(obj, attr))
+       return unittest.skip("{!r} doesn't have {!r}".format(obj, attr))
 
 The following decorators implement test skipping and expected failures:
 
@@ -660,6 +660,13 @@ The following decorators implement test skipping and expected failures:
    Mark the test as an expected failure.  If the test fails when run, the test
    is not counted as a failure.
 
+.. exception:: SkipTest(reason)
+
+   This exception is raised to skip a test.
+
+   Usually you can use :meth:`TestCase.skipTest` or one of the skipping
+   decorators instead of raising this directly.
+
 Skipped tests will not have :meth:`setUp` or :meth:`tearDown` run around them.
 Skipped classes will not have :meth:`setUpClass` or :meth:`tearDownClass` run.
 
@@ -1956,7 +1963,7 @@ then you must call up to them yourself. The implementations in
 If an exception is raised during a ``setUpClass`` then the tests in the class
 are not run and the ``tearDownClass`` is not run. Skipped classes will not
 have ``setUpClass`` or ``tearDownClass`` run. If the exception is a
-``SkipTest`` exception then the class will be reported as having been skipped
+:exc:`SkipTest` exception then the class will be reported as having been skipped
 instead of as an error.
 
 
@@ -1973,7 +1980,7 @@ These should be implemented as functions::
 
 If an exception is raised in a ``setUpModule`` then none of the tests in the
 module will be run and the ``tearDownModule`` will not be run. If the exception is a
-``SkipTest`` exception then the module will be reported as having been skipped
+:exc:`SkipTest` exception then the module will be reported as having been skipped
 instead of as an error.
 
 

Doc/library/warnings.rst

@@ -57,6 +57,8 @@ There are a number of built-in exceptions that represent warning categories.
 This categorization is useful to be able to filter out groups of warnings.  The
 following warnings category classes are currently defined:
 
+.. tabularcolumns:: |l|p{0.6\linewidth}|
+
 +----------------------------------+-----------------------------------------------+
 | Class                            | Description                                   |
 +==================================+===============================================+

Doc/library/xml.etree.elementtree.rst

@@ -312,6 +312,8 @@ module.  We'll be using the ``countrydata`` XML document from the
 Supported XPath syntax
 ^^^^^^^^^^^^^^^^^^^^^^
 
+.. tabularcolumns:: |l|L|
+
 +-----------------------+------------------------------------------------------+
 | Syntax                | Meaning                                              |
 +=======================+======================================================+

Doc/reference/datamodel.rst

@@ -481,6 +481,8 @@ Callable types
 
       Special attributes:
 
+      .. tabularcolumns:: |l|L|l|
+
       +-----------------------+-------------------------------+-----------+
       | Attribute             | Meaning                       |           |
       +=======================+===============================+===========+

Doc/reference/expressions.rst

@@ -1370,7 +1370,7 @@ groups from right to left).
 | :keyword:`not` ``x``                          | Boolean NOT                         |
 +-----------------------------------------------+-------------------------------------+
 | :keyword:`in`, :keyword:`not in`,             | Comparisons, including membership   |
-| :keyword:`is`, :keyword:`is not`, ``<``,      | tests and identity tests,           |
+| :keyword:`is`, :keyword:`is not`, ``<``,      | tests and identity tests            |
 | ``<=``, ``>``, ``>=``, ``<>``, ``!=``, ``==`` |                                     |
 +-----------------------------------------------+-------------------------------------+
 | ``|``                                         | Bitwise OR                          |

Doc/reference/simple_stmts.rst

@@ -737,7 +737,7 @@ can be found but the path exists then a value of ``None`` is
 stored in :data:`sys.path_importer_cache` to signify that an implicit,
 file-based finder that handles modules stored as individual files should be
 used for that path. If the path does not exist then a finder which always
-returns `None`` is placed in the cache for the path.
+returns ``None`` is placed in the cache for the path.
 
 .. index::
     single: loader

Doc/tools/sphinxext/suspicious.py

@@ -66,6 +66,10 @@ class Rule:
                                # None -> don't care
         self.issue = issue     # the markup fragment that triggered this rule
         self.line = line       # text of the container element (single line only)
+        self.used = False
+
+    def __repr__(self):
+        return '{0.docname},,{0.issue},{0.line}'.format(self)
 
 
 
@@ -105,6 +109,12 @@ class CheckSuspiciousMarkupBuilder(Builder):
         doctree.walk(visitor)
 
     def finish(self):
+        unused_rules = [rule for rule in self.rules if not rule.used]
+        if unused_rules:
+            self.warn('Found %s/%s unused rules:' %
+                      (len(unused_rules), len(self.rules)))
+            for rule in unused_rules:
+                self.info(repr(rule))
         return
 
     def check_issue(self, line, lineno, issue):
@@ -129,6 +139,7 @@ class CheckSuspiciousMarkupBuilder(Builder):
             if (rule.lineno is not None) and \
                 abs(rule.lineno - lineno) > 5: continue
             # if it came this far, the rule matched
+            rule.used = True
             return True
         return False
 

Lib/_abcoll.py

@@ -74,6 +74,7 @@ class Iterator(Iterable):
 
     @abstractmethod
     def next(self):
+        'Return the next item from the iterator. When exhausted, raise StopIteration'
         raise StopIteration
 
     def __iter__(self):
@@ -194,6 +195,7 @@ class Set(Sized, Iterable, Container):
         return self._from_iterable(value for value in other if value in self)
 
     def isdisjoint(self, other):
+        'Return True if two sets have a null intersection.'
         for value in other:
             if value in self:
                 return False
@@ -259,6 +261,16 @@ Set.register(frozenset)
 
 
 class MutableSet(Set):
+    """A mutable set is a finite, iterable container.
+
+    This class provides concrete generic implementations of all
+    methods except for __contains__, __iter__, __len__,
+    add(), and discard().
+
+    To override the comparisons (presumably for speed, as the
+    semantics are fixed), all you have to do is redefine __le__ and
+    then the other operations will automatically follow suit.
+    """
 
     @abstractmethod
     def add(self, value):
@@ -333,11 +345,20 @@ MutableSet.register(set)
 
 class Mapping(Sized, Iterable, Container):
 
+    """A Mapping is a generic container for associating key/value
+    pairs.
+
+    This class provides concrete generic implementations of all
+    methods except for __getitem__, __iter__, and __len__.
+
+    """
+
     @abstractmethod
     def __getitem__(self, key):
         raise KeyError
 
     def get(self, key, default=None):
+        'D.get(k[,d]) -> D[k] if k in D, else d.  d defaults to None.'
         try:
             return self[key]
         except KeyError:
@@ -352,23 +373,29 @@ class Mapping(Sized, Iterable, Container):
             return True
 
     def iterkeys(self):
+        'D.iterkeys() -> an iterator over the keys of D'
         return iter(self)
 
     def itervalues(self):
+        'D.itervalues() -> an iterator over the values of D'
         for key in self:
             yield self[key]
 
     def iteritems(self):
+        'D.iteritems() -> an iterator over the (key, value) items of D'
         for key in self:
             yield (key, self[key])
 
     def keys(self):
+        "D.keys() -> list of D's keys"
         return list(self)
 
     def items(self):
+        "D.items() -> list of D's (key, value) pairs, as 2-tuples"
         return [(key, self[key]) for key in self]
 
     def values(self):
+        "D.values() -> list of D's values"
         return [self[key] for key in self]
 
     # Mappings are not hashable by default, but subclasses can change this
@@ -443,6 +470,15 @@ class ValuesView(MappingView):
 
 class MutableMapping(Mapping):
 
+    """A MutableMapping is a generic container for associating
+    key/value pairs.
+
+    This class provides concrete generic implementations of all
+    methods except for __getitem__, __setitem__, __delitem__,
+    __iter__, and __len__.
+
+    """
+
     @abstractmethod
     def __setitem__(self, key, value):
         raise KeyError
@@ -454,6 +490,9 @@ class MutableMapping(Mapping):
     __marker = object()
 
     def pop(self, key, default=__marker):
+        '''D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
+          If key is not found, d is returned if given, otherwise KeyError is raised.
+        '''
         try:
             value = self[key]
         except KeyError:
@@ -465,6 +504,9 @@ class MutableMapping(Mapping):
             return value
 
     def popitem(self):
+        '''D.popitem() -> (k, v), remove and return some (key, value) pair
+           as a 2-tuple; but raise KeyError if D is empty.
+        '''
         try:
             key = next(iter(self))
         except StopIteration:
@@ -474,6 +516,7 @@ class MutableMapping(Mapping):
         return key, value
 
     def clear(self):
+        'D.clear() -> None.  Remove all items from D.'
         try:
             while True:
                 self.popitem()
@@ -481,6 +524,11 @@ class MutableMapping(Mapping):
             pass
 
     def update(*args, **kwds):
+        ''' D.update([E, ]**F) -> None.  Update D from mapping/iterable E and F.
+            If E present and has a .keys() method, does:     for k in E: D[k] = E[k]
+            If E present and lacks .keys() method, does:     for (k, v) in E: D[k] = v
+            In either case, this is followed by: for k, v in F.items(): D[k] = v
+        '''
         if len(args) > 2:
             raise TypeError("update() takes at most 2 positional "
                             "arguments ({} given)".format(len(args)))
@@ -502,6 +550,7 @@ class MutableMapping(Mapping):
             self[key] = value
 
     def setdefault(self, key, default=None):
+        'D.setdefault(k[,d]) -> D.get(k,d), also set D[k]=d if k not in D'
         try:
             return self[key]
         except KeyError:
@@ -546,12 +595,16 @@ class Sequence(Sized, Iterable, Container):
             yield self[i]
 
     def index(self, value):
+        '''S.index(value) -> integer -- return first index of value.
+           Raises ValueError if the value is not present.
+        '''
         for i, v in enumerate(self):
             if v == value:
                 return i
         raise ValueError
 
     def count(self, value):
+        'S.count(value) -> integer -- return number of occurrences of value'
         return sum(1 for v in self if v == value)
 
 Sequence.register(tuple)
@@ -562,6 +615,13 @@ Sequence.register(xrange)
 
 class MutableSequence(Sequence):
 
+    """All the operations on a read-only sequence.
+
+    Concrete subclasses must provide __new__ or __init__,
+    __getitem__, __setitem__, __delitem__, __len__, and insert().
+
+    """
+
     @abstractmethod
     def __setitem__(self, index, value):
         raise IndexError
@@ -572,26 +632,36 @@ class MutableSequence(Sequence):
 
     @abstractmethod
     def insert(self, index, value):
+        'S.insert(index, object) -- insert object before index'
         raise IndexError
 
     def append(self, value):
+        'S.append(object) -- append object to the end of the sequence'
         self.insert(len(self), value)
 
     def reverse(self):
+        'S.reverse() -- reverse *IN PLACE*'
         n = len(self)
         for i in range(n//2):
             self[i], self[n-i-1] = self[n-i-1], self[i]
 
     def extend(self, values):
+        'S.extend(iterable) -- extend sequence by appending elements from the iterable'
         for v in values:
             self.append(v)
 
     def pop(self, index=-1):
+        '''S.pop([index]) -> item -- remove and return item at index (default last).
+           Raise IndexError if list is empty or index is out of range.
+        '''
         v = self[index]
         del self[index]
         return v
 
     def remove(self, value):
+        '''S.remove(value) -- remove first occurrence of value.
+           Raise ValueError if the value is not present.
+        '''
         del self[self.index(value)]
 
     def __iadd__(self, values):

Lib/idlelib/MultiCall.py

@@ -171,8 +171,9 @@ class _ComplexBinder:
                     break
             ishandlerrunning[:] = []
             # Call all functions in doafterhandler and remove them from list
-            while doafterhandler:
-                doafterhandler.pop()()
+            for f in doafterhandler:
+                f()
+            doafterhandler[:] = []
             if r:
                 return r
         return handler

Lib/idlelib/NEWS.txt

+What's New in IDLE 2.7.5?
+=========================
+
+- Issue #17390: Display Python version on Idle title bar.
+  Initial patch by Edmond Burnett.
+
+
 What's New in IDLE 2.7.4?
 =========================
 

Lib/idlelib/PyShell.py

@@ -15,6 +15,7 @@ import io
 
 import linecache
 from code import InteractiveInterpreter
+from platform import python_version
 
 try:
     from Tkinter import *
@@ -115,12 +116,13 @@ class PyShellEditorWindow(EditorWindow):
         self.breakpointPath = os.path.join(idleConf.GetUserCfgDir(),
                                            'breakpoints.lst')
         # whenever a file is changed, restore breakpoints
-        if self.io.filename: self.restore_file_breaks()
         def filename_changed_hook(old_hook=self.io.filename_change_hook,
                                   self=self):
             self.restore_file_breaks()
             old_hook()
         self.io.set_filename_change_hook(filename_changed_hook)
+        if self.io.filename:
+            self.restore_file_breaks()
 
     rmenu_specs = [
         ("Cut", "<<cut>>", "rmenu_check_cut"),
@@ -236,6 +238,9 @@ class PyShellEditorWindow(EditorWindow):
 
     def restore_file_breaks(self):
         self.text.update()   # this enables setting "BREAK" tags to be visible
+        if self.io is None:
+            # can happen if IDLE closes due to the .update() call
+            return
         filename = self.io.filename
         if filename is None:
             return
@@ -464,6 +469,7 @@ class ModifiedInterpreter(InteractiveInterpreter):
             self.display_no_subprocess_error()
             return None
         self.transfer_path(with_cwd=with_cwd)
+        console.stop_readline()
         # annotate restart in shell window and mark it
         console.text.delete("iomark", "end-1c")
         if was_executing:
@@ -821,7 +827,7 @@ class ModifiedInterpreter(InteractiveInterpreter):
 
 class PyShell(OutputWindow):
 
-    shell_title = "Python Shell"
+    shell_title = "Python " + python_version() + " Shell"
 
     # Override classes
     ColorDelegator = ModifiedColorDelegator
@@ -903,6 +909,7 @@ class PyShell(OutputWindow):
     canceled = False
     endoffile = False
     closing = False
+    _stop_readline_flag = False
 
     def set_warning_stream(self, stream):
         global warning_stream
@@ -978,8 +985,7 @@ class PyShell(OutputWindow):
                 parent=self.text)
             if response is False:
                 return "cancel"
-        if self.reading:
-            self.top.quit()
+        self.stop_readline()
         self.canceled = True
         self.closing = True
         # Wait for poll_subprocess() rescheduling to stop
@@ -1031,6 +1037,12 @@ class PyShell(OutputWindow):
         Tkinter._default_root = None # 03Jan04 KBK What's this?
         return True
 
+    def stop_readline(self):
+        if not self.reading:  # no nested mainloop to exit.
+            return
+        self._stop_readline_flag = True
+        self.top.quit()
+
     def readline(self):
         save = self.reading
         try:
@@ -1038,6 +1050,9 @@ class PyShell(OutputWindow):
             self.top.mainloop()  # nested mainloop()
         finally:
             self.reading = save
+        if self._stop_readline_flag:
+            self._stop_readline_flag = False
+            return ""
         line = self.text.get("iomark", "end-1c")
         if len(line) == 0:  # may be EOF if we quit our mainloop with Ctrl-C
             line = "\n"
@@ -1413,7 +1428,7 @@ def main():
     global flist, root, use_subprocess
 
     use_subprocess = True
-    enable_shell = True
+    enable_shell = False
     enable_edit = False
     debug = False
     cmd = None
@@ -1434,7 +1449,6 @@ def main():
             enable_shell = True
         if o == '-e':
             enable_edit = True
-            enable_shell = False
         if o == '-h':
             sys.stdout.write(usage_msg)
             sys.exit()
@@ -1485,6 +1499,7 @@ def main():
     edit_start = idleConf.GetOption('main', 'General',
                                     'editor-on-startup', type='bool')
     enable_edit = enable_edit or edit_start
+    enable_shell = enable_shell or not enable_edit
     # start editor and/or shell windows:
     root = Tk(className="Idle")
 

Lib/idlelib/rpc.py

@@ -144,7 +144,7 @@ class SocketIO(object):
 
     def exithook(self):
         "override for specific exit action"
-        os._exit()
+        os._exit(0)
 
     def debug(self, *args):
         if not self.debugging:

Lib/inspect.py

@@ -525,7 +525,7 @@ def findsource(object):
 
     file = getfile(object)
     sourcefile = getsourcefile(object)
-    if not sourcefile and file[0] + file[-1] != '<>':
+    if not sourcefile and file[:1] + file[-1:] != '<>':
         raise IOError('source code not available')
     file = sourcefile if sourcefile else file
 

Lib/logging/config.py

@@ -379,6 +379,12 @@ class BaseConfigurator(object):
     def __init__(self, config):
         self.config = ConvertingDict(config)
         self.config.configurator = self
+        # Issue 12718: winpdb replaces __import__ with a Python function, which
+        # ends up being treated as a bound method. To avoid problems, we
+        # set the importer on the instance, but leave it defined in the class
+        # so existing code doesn't break
+        if type(__import__) == types.FunctionType:
+            self.importer = __import__
 
     def resolve(self, s):
         """

Lib/smtplib.py

@@ -276,12 +276,12 @@ class SMTP:
         """
         self.debuglevel = debuglevel
 
-    def _get_socket(self, port, host, timeout):
+    def _get_socket(self, host, port, timeout):
         # This makes it simpler for SMTP_SSL to use the SMTP connect code
         # and just alter the socket connection bit.
         if self.debuglevel > 0:
             print>>stderr, 'connect:', (host, port)
-        return socket.create_connection((port, host), timeout)
+        return socket.create_connection((host, port), timeout)
 
     def connect(self, host='localhost', port=0):
         """Connect to a host on a given port.

Lib/test/test_inspect.py

@@ -404,6 +404,12 @@ class TestBuggyCases(GetSourceBase):
         self.assertEqual(inspect.findsource(co), (lines,0))
         self.assertEqual(inspect.getsource(co), lines[0])
 
+    def test_findsource_without_filename(self):
+        for fname in ['', '<string>']:
+            co = compile('x=1', fname, "exec")
+            self.assertRaises(IOError, inspect.findsource, co)
+            self.assertRaises(IOError, inspect.getsource, co)
+
 
 class _BrokenDataDescriptor(object):
     """

Lib/test/test_kqueue.py

@@ -96,11 +96,6 @@ class TestKQueue(unittest.TestCase):
             pass # FreeBSD doesn't raise an exception here
         server, addr = serverSocket.accept()
 
-        if sys.platform.startswith("darwin"):
-            flags = select.KQ_EV_ADD | select.KQ_EV_ENABLE
-        else:
-            flags = 0
-
         kq = select.kqueue()
         kq2 = select.kqueue.fromfd(kq.fileno())
 
@@ -122,11 +117,10 @@ class TestKQueue(unittest.TestCase):
         kq2.control([ev], 0)
 
         events = kq.control(None, 4, 1)
-        events = [(e.ident, e.filter, e.flags) for e in events]
-        events.sort()
-        self.assertEqual(events, [
-            (client.fileno(), select.KQ_FILTER_WRITE, flags),
-            (server.fileno(), select.KQ_FILTER_WRITE, flags)])
+        events = set((e.ident, e.filter) for e in events)
+        self.assertEqual(events, set([
+            (client.fileno(), select.KQ_FILTER_WRITE),
+            (server.fileno(), select.KQ_FILTER_WRITE)]))
 
         client.send("Hello!")
         server.send("world!!!")
@@ -140,14 +134,12 @@ class TestKQueue(unittest.TestCase):
         else:
             self.fail('timeout waiting for event notifications')
 
-        events = [(e.ident, e.filter, e.flags) for e in events]
-        events.sort()
-
-        self.assertEqual(events, [
-            (client.fileno(), select.KQ_FILTER_WRITE, flags),
-            (client.fileno(), select.KQ_FILTER_READ, flags),
-            (server.fileno(), select.KQ_FILTER_WRITE, flags),
-            (server.fileno(), select.KQ_FILTER_READ, flags)])
+        events = set((e.ident, e.filter) for e in events)
+        self.assertEqual(events, set([
+            (client.fileno(), select.KQ_FILTER_WRITE),
+            (client.fileno(), select.KQ_FILTER_READ),
+            (server.fileno(), select.KQ_FILTER_WRITE),
+            (server.fileno(), select.KQ_FILTER_READ)]))
 
         # Remove completely client, and server read part
         ev = select.kevent(client.fileno(),
@@ -164,10 +156,9 @@ class TestKQueue(unittest.TestCase):
         kq.control([ev], 0, 0)
 
         events = kq.control([], 4, 0.99)
-        events = [(e.ident, e.filter, e.flags) for e in events]
-        events.sort()
-        self.assertEqual(events, [
-            (server.fileno(), select.KQ_FILTER_WRITE, flags)])
+        events = set((e.ident, e.filter) for e in events)
+        self.assertEqual(events, set([
+            (server.fileno(), select.KQ_FILTER_WRITE)]))
 
         client.close()
         server.close()

Lib/test/test_queue.py

@@ -43,6 +43,9 @@ class _TriggerThread(threading.Thread):
 
 class BlockingTestMixin:
 
+    def tearDown(self):
+        self.t = None
+
     def do_blocking_test(self, block_func, block_args, trigger_func, trigger_args):
         self.t = _TriggerThread(trigger_func, trigger_args)
         self.t.start()
@@ -222,7 +225,7 @@ class FailingQueue(Queue.Queue):
             raise FailingQueueException, "You Lose"
         return Queue.Queue._get(self)
 
-class FailingQueueTest(unittest.TestCase, BlockingTestMixin):
+class FailingQueueTest(BlockingTestMixin, unittest.TestCase):
 
     def failing_queue_test(self, q):
         if not q.empty():

Lib/test/test_urllib2_localnet.py

@@ -489,6 +489,11 @@ class TestUrlopen(BaseTestCase):
     def test_bad_address(self):
         # Make sure proper exception is raised when connecting to a bogus
         # address.
+
+        # as indicated by the comment below, this might fail with some ISP,
+        # so we run the test only when -unetwork/-uall is specified to
+        # mitigate the problem a bit (see #17564)
+        test_support.requires('network')
         self.assertRaises(IOError,
                           # Given that both VeriSign and various ISPs have in
                           # the past or are presently hijacking various invalid

Lib/unittest/case.py

@@ -26,7 +26,7 @@ class SkipTest(Exception):
     """
     Raise this exception in a test to skip it.
 
-    Usually you can use TestResult.skip() or one of the skipping decorators
+    Usually you can use TestCase.skipTest() or one of the skipping decorators
     instead of raising this directly.
     """
     pass
@@ -150,24 +150,23 @@ class TestCase(object):
     should not change the signature of their __init__ method, since instances
     of the classes are instantiated automatically by parts of the framework
     in order to be run.
-    """
 
-    # This attribute determines which exception will be raised when
-    # the instance's assertion methods fail; test methods raising this
-    # exception will be deemed to have 'failed' rather than 'errored'
+    When subclassing TestCase, you can set these attributes:
+    * failureException: determines which exception will be raised when
+        the instance's assertion methods fail; test methods raising this
+        exception will be deemed to have 'failed' rather than 'errored'.
+    * longMessage: determines whether long messages (including repr of
+        objects used in assert methods) will be printed on failure in *addition*
+        to any explicit message passed.
+    * maxDiff: sets the maximum length of a diff in failure messages
+        by assert methods using difflib. It is looked up as an instance
+        attribute so can be configured by individual tests if required.
+    """
 
     failureException = AssertionError
 
-    # This attribute determines whether long messages (including repr of
-    # objects used in assert methods) will be printed on failure in *addition*
-    # to any explicit message passed.
-
     longMessage = False
 
-    # This attribute sets the maximum length of a diff in failure messages
-    # by assert methods using difflib. It is looked up as an instance attribute
-    # so can be configured by individual tests if required.
-
     maxDiff = 80*8
 
     # If a string is longer than _diffThreshold, use normal comparison instead

Misc/ACKS

@@ -761,6 +761,7 @@ Peter Parente
 Alexandre Parenteau
 Dan Parisien
 William Park
+Heikki Partanen
 Harri Pasanen
 Randy Pausch
 Samuele Pedroni
@@ -992,6 +993,7 @@ Monty Taylor
 Amy Taylor
 Anatoly Techtonik
 Mikhail Terekhov
+Victor Terrón
 Richard M. Tew
 Tobias Thelen
 Lowe Thiderman

Misc/NEWS

 Python News
 +++++++++++
 
+What's New in Python 2.7.5?
+===========================
+
+*Release date: XXXX-XX-XX*
+
+Core and Builtins
+-----------------
+
+Library
+-------
+
+- Issue #14254: IDLE now handles readline correctly across shell restarts.
+
+- Issue #17614: IDLE no longer raises exception when quickly closing a file.
+
+- Issue #13163: Rename operands in smtplib.SMTP._get_socket to correct names;
+  fixes otherwise misleading output in tracebacks and when when debug is on.
+
+- Issue #6698: IDLE now opens just an editor window when configured to do so.
+
+- Issue #8900: Using keyboard shortcuts in IDLE to open a file no longer
+  raises an exception.
+
+- Issue #6649: Fixed missing exit status in IDLE. Patch by Guilherme Polo.
+
+- Issue #17526: fix an IndexError raised while passing code without filename to
+  inspect.findsource().  Initial patch by Tyler Doyle.
+
+Documentation
+-------------
+
+- Issue #15940: Specify effect of locale on time functions.
+
+
 What's New in Python 2.7.4?
 ===========================
 
@@ -249,6 +283,9 @@ Core and Builtins
 Library
 -------
 
+- Issue #12718: Fix interaction with winpdb overriding __import__ by setting
+  importer attribute on BaseConfigurator instance.
+  
 - Issue #17521: Corrected non-enabling of logger following two calls to
   fileConfig().