Merged revisions...

Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk

........
  r74861 | benjamin.peterson | 2009-09-17 05:18:28 +0200 (Do, 17 Sep 2009) | 1 line

  pep 8 defaults
........
  r74862 | brett.cannon | 2009-09-17 05:24:45 +0200 (Do, 17 Sep 2009) | 1 line

  Note in the intro to Extending... that ctypes can be a simpler, more portable solution than custom C code.
........
  r74863 | benjamin.peterson | 2009-09-17 05:27:33 +0200 (Do, 17 Sep 2009) | 1 line

  rationalize a bit
........
  r74876 | georg.brandl | 2009-09-17 18:15:53 +0200 (Do, 17 Sep 2009) | 1 line

  #6932: remove paragraph that advises relying on __del__ being called.
........
  r74896 | georg.brandl | 2009-09-18 09:22:41 +0200 (Fr, 18 Sep 2009) | 1 line

  #6936: for interactive use, quit() is just fine.
........
  r74930 | georg.brandl | 2009-09-18 23:21:41 +0200 (Fr, 18 Sep 2009) | 1 line

  #6925: rewrite docs for locals() and vars() a bit.
........
  r74933 | georg.brandl | 2009-09-18 23:35:59 +0200 (Fr, 18 Sep 2009) | 1 line

  #6930: clarify description about byteorder handling in UTF decoder routines.
........
  r74952 | georg.brandl | 2009-09-19 12:42:34 +0200 (Sa, 19 Sep 2009) | 1 line

  #6946: fix duplicate index entries for datetime classes.
........
  r74953 | georg.brandl | 2009-09-19 14:04:16 +0200 (Sa, 19 Sep 2009) | 1 line

  Fix references to threading.enumerate().
........
  r75015 | georg.brandl | 2009-09-22 12:55:08 +0200 (Di, 22 Sep 2009) | 1 line

  Fix encoding name.
........
  r75019 | vinay.sajip | 2009-09-22 19:23:41 +0200 (Di, 22 Sep 2009) | 1 line

  Fixed a typo, and added sections on optimization and using arbitrary objects as messages.
........
  r75260 | andrew.kuchling | 2009-10-05 23:24:20 +0200 (Mo, 05 Okt 2009) | 1 line

  Wording fix
........
  r75261 | andrew.kuchling | 2009-10-05 23:24:35 +0200 (Mo, 05 Okt 2009) | 1 line

  Fix narkup
........
  r75262 | andrew.kuchling | 2009-10-05 23:25:03 +0200 (Mo, 05 Okt 2009) | 1 line

  Document 'skip' parameter to constructor
........
  r75263 | andrew.kuchling | 2009-10-05 23:25:35 +0200 (Mo, 05 Okt 2009) | 1 line

  Note side benefit of socket.create_connection()
........
  r75265 | andrew.kuchling | 2009-10-06 00:31:11 +0200 (Di, 06 Okt 2009) | 1 line

  Reword sentence
........
  r75266 | andrew.kuchling | 2009-10-06 00:32:48 +0200 (Di, 06 Okt 2009) | 1 line

  Use standard comma punctuation; reword some sentences in the docs
........
  r75289 | mark.dickinson | 2009-10-08 22:02:25 +0200 (Do, 08 Okt 2009) | 2 lines

  Issue #7051:  Clarify behaviour of 'g' and 'G'-style formatting.
........

Doc/c-api/unicode.rst

@@ -414,10 +414,13 @@ These are the UTF-32 codec APIs:
       *byteorder == 0:  native order
       *byteorder == 1:  big endian
 
-   and then switches if the first four bytes of the input data are a byte order mark
-   (BOM) and the specified byte order is native order.  This BOM is not copied into
-   the resulting Unicode string.  After completion, *\*byteorder* is set to the
-   current byte order at the end of input data.
+   If ``*byteorder`` is zero, and the first four bytes of the input data are a
+   byte order mark (BOM), the decoder switches to this byte order and the BOM is
+   not copied into the resulting Unicode string.  If ``*byteorder`` is ``-1`` or
+   ``1``, any byte order mark is copied to the output.
+
+   After completion, *\*byteorder* is set to the current byte order at the end
+   of input data.
 
    In a narrow build codepoints outside the BMP will be decoded as surrogate pairs.
 
@@ -442,8 +445,7 @@ These are the UTF-32 codec APIs:
 .. cfunction:: PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
 
    Return a Python bytes object holding the UTF-32 encoded value of the Unicode
-   data in *s*.  If *byteorder* is not ``0``, output is written according to the
-   following byte order::
+   data in *s*.  Output is written according to the following byte order::
 
       byteorder == -1: little endian
       byteorder == 0:  native byte order (writes a BOM mark)
@@ -487,10 +489,14 @@ These are the UTF-16 codec APIs:
       *byteorder == 0:  native order
       *byteorder == 1:  big endian
 
-   and then switches if the first two bytes of the input data are a byte order mark
-   (BOM) and the specified byte order is native order.  This BOM is not copied into
-   the resulting Unicode string.  After completion, *\*byteorder* is set to the
-   current byte order at the.
+   If ``*byteorder`` is zero, and the first two bytes of the input data are a
+   byte order mark (BOM), the decoder switches to this byte order and the BOM is
+   not copied into the resulting Unicode string.  If ``*byteorder`` is ``-1`` or
+   ``1``, any byte order mark is copied to the output (where it will result in
+   either a ``\ufeff`` or a ``\ufffe`` character).
+
+   After completion, *\*byteorder* is set to the current byte order at the end
+   of input data.
 
    If *byteorder* is *NULL*, the codec starts in native order mode.
 
@@ -520,8 +526,7 @@ These are the UTF-16 codec APIs:
 .. cfunction:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
 
    Return a Python string object holding the UTF-16 encoded value of the Unicode
-   data in *s*.  If *byteorder* is not ``0``, output is written according to the
-   following byte order::
+   data in *s*.  Output is written according to the following byte order::
 
       byteorder == -1: little endian
       byteorder == 0:  native byte order (writes a BOM mark)

Doc/documenting/markup.rst

@@ -597,8 +597,10 @@ units as well as normal text:
    An important bit of information about an API that a user should be aware of
    when using whatever bit of API the warning pertains to.  The content of the
    directive should be written in complete sentences and include all appropriate
-   punctuation.  This should only be chosen over ``note`` for information
-   regarding the possibility of crashes, data loss, or security implications.
+   punctuation.  In the interest of not scaring users away from pages filled
+   with warnings, this directive should only be chosen over ``note`` for
+   information regarding the possibility of crashes, data loss, or security
+   implications.
 
 .. describe:: versionadded
 

Doc/extending/extending.rst

@@ -20,6 +20,13 @@ source file by including the header ``"Python.h"``.
 The compilation of an extension module depends on its intended use as well as on
 your system setup; details are given in later chapters.
 
+Do note that if your use case is calling C library functions or system calls,
+you should consider using the :mod:`ctypes` module rather than writing custom
+C code. Not only does :mod:`ctypes` let you write Python code to interface
+with C code, but it is more portable between implementations of Python than
+writing and compiling an extension module which typically ties you to CPython.
+
+
 
 .. _extending-simpleexample:
 

Doc/library/bdb.rst

@@ -62,14 +62,22 @@ The :mod:`bdb` module also defines two classes:
       * The breakpoint hit count.
 
 
-.. class:: Bdb()
+.. class:: Bdb(skip=None)
 
-   The :class:`Bdb` acts as a generic Python debugger base class.
+   The :class:`Bdb` class acts as a generic Python debugger base class.
 
    This class takes care of the details of the trace facility; a derived class
    should implement user interaction.  The standard debugger class
    (:class:`pdb.Pdb`) is an example.
 
+   The *skip* argument, if given, must be an iterable of glob-style
+   module name patterns.  The debugger will not step into frames that
+   originate in a module that matches one of these patterns. Whether a
+   frame is considered to originate in a certain module is determined
+   by the ``__name__`` in the frame globals.
+
+   .. versionadded:: 2.7
+      The *skip* argument.
 
    The following methods of :class:`Bdb` normally don't need to be overridden.
 

Doc/library/codecs.rst

@@ -958,7 +958,7 @@ particular, the following variants typically exist:
 +-----------------+--------------------------------+--------------------------------+
 | cp1255          | windows-1255                   | Hebrew                         |
 +-----------------+--------------------------------+--------------------------------+
-| cp1256          | windows1256                    | Arabic                         |
+| cp1256          | windows-1256                   | Arabic                         |
 +-----------------+--------------------------------+--------------------------------+
 | cp1257          | windows-1257                   | Baltic languages               |
 +-----------------+--------------------------------+--------------------------------+

Doc/library/datetime.rst

@@ -65,6 +65,7 @@ Available Types
 
 
 .. class:: date
+   :noindex:
 
    An idealized naive date, assuming the current Gregorian calendar always was, and
    always will be, in effect. Attributes: :attr:`year`, :attr:`month`, and
@@ -72,6 +73,7 @@ Available Types
 
 
 .. class:: time
+   :noindex:
 
    An idealized time, independent of any particular day, assuming that every day
    has exactly 24\*60\*60 seconds (there is no notion of "leap seconds" here).
@@ -80,6 +82,7 @@ Available Types
 
 
 .. class:: datetime
+   :noindex:
 
    A combination of a date and a time. Attributes: :attr:`year`, :attr:`month`,
    :attr:`day`, :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`,
@@ -87,6 +90,7 @@ Available Types
 
 
 .. class:: timedelta
+   :noindex:
 
    A duration expressing the difference between two :class:`date`, :class:`time`,
    or :class:`datetime` instances to microsecond resolution.

Doc/library/functions.rst

@@ -637,15 +637,13 @@ available.  They are listed here in alphabetical order.
 .. function:: locals()
 
    Update and return a dictionary representing the current local symbol table.
+   Free variables are returned by :func:`locals` when it is called in function
+   blocks, but not in class blocks.
 
    .. note::
 
-      The contents of this dictionary should not be modified; changes may not affect
-      the values of local variables used by the interpreter.
-
-   Free variables are returned by :func:`locals` when it is called in a function block.
-   Modifications of free variables may not affect the values used by the
-   interpreter.  Free variables are not returned in class blocks.
+      The contents of this dictionary should not be modified; changes may not
+      affect the values of local and free variables used by the interpreter.
 
 
 .. function:: long([x[, base]])
@@ -1357,10 +1355,10 @@ available.  They are listed here in alphabetical order.
 
 .. function:: vars([object])
 
-   Without arguments, return a dictionary corresponding to the current local symbol
-   table.  With a module, class or class instance object as argument (or anything
-   else that has a :attr:`__dict__` attribute), returns a dictionary corresponding
-   to the object's symbol table.
+   Without an argument, act like :func:`locals`.
+
+   With a module, class or class instance object as argument (or anything else that
+   has a :attr:`__dict__` attribute), return that attribute.
 
    .. note::
 

Doc/library/logging.rst

@@ -59,7 +59,7 @@ default handler so that debug messages are written to a file::
 
    import logging
    LOG_FILENAME = '/tmp/logging_example.out'
-   logging.basicConfig(filename=LOG_FILENAME,level=logging.DEBUG,)
+   logging.basicConfig(filename=LOG_FILENAME,level=logging.DEBUG)
 
    logging.debug('This message should go to the log file')
 
@@ -1499,6 +1499,53 @@ printed on the console; on the server side, you should see something like::
       69 myapp.area2     WARNING  Jail zesty vixen who grabbed pay from quack.
       69 myapp.area2     ERROR    The five boxing wizards jump quickly.
 
+Using arbitrary objects as messages
+-----------------------------------
+
+In the preceding sections and examples, it has been assumed that the message
+passed when logging the event is a string. However, this is not the only
+possibility. You can pass an arbitrary object as a message, and its
+:meth:`__str__` method will be called when the logging system needs to convert
+it to a string representation. In fact, if you want to, you can avoid
+computing a string representation altogether - for example, the
+:class:`SocketHandler` emits an event by pickling it and sending it over the
+wire.
+
+Optimization
+------------
+
+Formatting of message arguments is deferred until it cannot be avoided.
+However, computing the arguments passed to the logging method can also be
+expensive, and you may want to avoid doing it if the logger will just throw
+away your event. To decide what to do, you can call the :meth:`isEnabledFor`
+method which takes a level argument and returns true if the event would be
+created by the Logger for that level of call. You can write code like this::
+
+    if logger.isEnabledFor(logging.DEBUG):
+        logger.debug("Message with %s, %s", expensive_func1(),
+                                            expensive_func2())
+
+so that if the logger's threshold is set above ``DEBUG``, the calls to
+:func:`expensive_func1` and :func:`expensive_func2` are never made.
+
+There are other optimizations which can be made for specific applications which
+need more precise control over what logging information is collected. Here's a
+list of things you can do to avoid processing during logging which you don't
+need:
+
++-----------------------------------------------+----------------------------------------+
+| What you don't want to collect                | How to avoid collecting it             |
++===============================================+========================================+
+| Information about where calls were made from. | Set ``logging._srcfile`` to ``None``.  |
++-----------------------------------------------+----------------------------------------+
+| Threading information.                        | Set ``logging.logThreads`` to ``0``.   |
++-----------------------------------------------+----------------------------------------+
+| Process information.                          | Set ``logging.logProcesses`` to ``0``. |
++-----------------------------------------------+----------------------------------------+
+
+Also note that the core logging module only includes the basic handlers. If
+you don't import :mod:`logging.handlers` and :mod:`logging.config`, they won't
+take up any memory.
 
 .. _handler:
 

Doc/library/pdb.rst

@@ -53,7 +53,16 @@ useful than quitting the debugger upon program's exit.
 .. versionadded:: 2.4
    Restarting post-mortem behavior added.
 
-Typical usage to inspect a crashed program is::
+The typical usage to break into the debugger from a running program is to
+insert ::
+
+   import pdb; pdb.set_trace()
+
+at the location you want to break into the debugger.  You can then step through
+the code following this statement, and continue running without the debugger using
+the ``c`` command.
+
+The typical usage to inspect a crashed program is::
 
    >>> import pdb
    >>> import mymodule

Doc/library/shelve.rst

@@ -30,27 +30,39 @@ lots of shared  sub-objects.  The keys are ordinary strings.
 
    Because of Python semantics, a shelf cannot know when a mutable
    persistent-dictionary entry is modified.  By default modified objects are
-   written only when assigned to the shelf (see :ref:`shelve-example`).  If
-   the optional *writeback* parameter is set to *True*, all entries accessed
-   are cached in memory, and written back at close time; this can make it
-   handier to mutate mutable entries in the persistent dictionary, but, if
-   many entries are accessed, it can consume vast amounts of memory for the
-   cache, and it can make the close operation very slow since all accessed
-   entries are written back (there is no way to determine which accessed
-   entries are mutable, nor which ones were actually mutated).
+   written only when assigned to the shelf (see :ref:`shelve-example`).  If the
+   optional *writeback* parameter is set to *True*, all entries accessed are
+   cached in memory, and written back on :meth:`sync` and :meth:`close`; this
+   can make it handier to mutate mutable entries in the persistent dictionary,
+   but, if many entries are accessed, it can consume vast amounts of memory for
+   the cache, and it can make the close operation very slow since all accessed
+   entries are written back (there is no way to determine which accessed entries
+   are mutable, nor which ones were actually mutated).
+
+   .. note::
+
+      Do not rely on the shelf being closed automatically; always call
+      :meth:`close` explicitly when you don't need it any more, or use a
+      :keyword:`with` statement with :func:`contextlib.closing`.
+
 
 Shelf objects support all methods supported by dictionaries.  This eases the
 transition from dictionary based scripts to those requiring persistent storage.
 
-One additional method is supported:
-
+Two additional methods are supported:
 
 .. method:: Shelf.sync()
 
-   Write back all entries in the cache if the shelf was opened with *writeback* set
-   to *True*. Also empty the cache and synchronize the persistent dictionary on
-   disk, if feasible.  This is called automatically when the shelf is closed with
-   :meth:`close`.
+   Write back all entries in the cache if the shelf was opened with *writeback*
+   set to :const:`True`.  Also empty the cache and synchronize the persistent
+   dictionary on disk, if feasible.  This is called automatically when the shelf
+   is closed with :meth:`close`.
+
+.. method:: Shelf.close()
+
+   Synchronize and close the persistent *dict* object.  Operations on a closed
+   shelf will fail with a :exc:`ValueError`.
+
 
 .. seealso::
 
@@ -75,11 +87,6 @@ Restrictions
   database should be fairly small, and in rare cases key collisions may cause the
   database to refuse updates.
 
-* Depending on the implementation, closing a persistent dictionary may or may
-  not be necessary to flush changes to disk.  The :meth:`__del__` method of the
-  :class:`Shelf` class calls the :meth:`close` method, so the programmer generally
-  need not do this explicitly.
-
 * The :mod:`shelve` module does not support *concurrent* read/write access to
   shelved objects.  (Multiple simultaneous read accesses are safe.)  When a
   program has a shelf open for writing, no other program should have it open for

Doc/library/string.rst

@@ -435,15 +435,33 @@ The available presentation types for floating point and decimal values are:
    +---------+----------------------------------------------------------+
    | ``'F'`` | Fixed point. Same as ``'f'``.                            |
    +---------+----------------------------------------------------------+
-   | ``'g'`` | General format. This prints the number as a fixed-point  |
-   |         | number, unless the number is too large, in which case    |
-   |         | it switches to ``'e'`` exponent notation. Infinity and   |
-   |         | NaN values are formatted as ``inf``, ``-inf`` and        |
-   |         | ``nan``, respectively.                                   |
+   | ``'g'`` | General format.  For a given precision ``p >= 1``,       |
+   |         | this rounds the number to ``p`` significant digits and   |
+   |         | then formats the result in either fixed-point format     |
+   |         | or in scientific notation, depending on its magnitude.   |
+   |         |                                                          |
+   |         | The precise rules are as follows: suppose that the       |
+   |         | result formatted with presentation type ``'e'`` and      |
+   |         | precision ``p-1`` would have exponent ``exp``.  Then     |
+   |         | if ``-4 <= exp < p``, the number is formatted            |
+   |         | with presentation type ``'f'`` and precision             |
+   |         | ``p-1-exp``.  Otherwise, the number is formatted         |
+   |         | with presentation type ``'e'`` and precision ``p-1``.    |
+   |         | In both cases insignificant trailing zeros are removed   |
+   |         | from the significand, and the decimal point is also      |
+   |         | removed if there are no remaining digits following it.   |
+   |         |                                                          |
+   |         | Postive and negative infinity, positive and negative     |
+   |         | zero, and nans, are formatted as ``inf``, ``-inf``,      |
+   |         | ``0``, ``-0`` and ``nan`` respectively, regardless of    |
+   |         | the precision.                                           |
+   |         |                                                          |
+   |         | A precision of ``0`` is treated as equivalent to a       |
+   |         | precision of ``1``.                                      |
    +---------+----------------------------------------------------------+
    | ``'G'`` | General format. Same as ``'g'`` except switches to       |
-   |         | ``'E'`` if the number gets to large. The representations |
-   |         | of infinity and NaN are uppercased, too.                 |
+   |         | ``'E'`` if the number gets too large. The                |
+   |         | representations of infinity and NaN are uppercased, too. |
    +---------+----------------------------------------------------------+
    | ``'n'`` | Number. This is the same as ``'g'``, except that it uses |
    |         | the current locale setting to insert the appropriate     |

Doc/library/termios.rst

@@ -90,7 +90,7 @@ technique using a separate :func:`tcgetattr` call and a :keyword:`try` ...
 :keyword:`finally` statement to ensure that the old tty attributes are restored
 exactly no matter what happens::
 
-   def getpass(prompt = "Password: "):
+   def getpass(prompt="Password: "):
        import termios, sys
        fd = sys.stdin.fileno()
        old = termios.tcgetattr(fd)

Doc/library/threading.rst

@@ -33,7 +33,7 @@ This module defines the following functions and objects:
               activeCount()
 
    Return the number of :class:`Thread` objects currently alive.  The returned
-   count is equal to the length of the list returned by :func:`enumerate`.
+   count is equal to the length of the list returned by :func:`.enumerate`.
 
 
 .. function:: Condition()
@@ -321,7 +321,7 @@ impossible to detect the termination of alien threads.
 
       Roughly, a thread is alive from the moment the :meth:`start` method
       returns until its :meth:`run` method terminates. The module function
-      :func:`enumerate` returns a list of all alive threads.
+      :func:`.enumerate` returns a list of all alive threads.
 
    .. method:: isDaemon()
                setDaemon()

Doc/tutorial/interpreter.rst

@@ -31,7 +31,7 @@ command into the command prompt in a DOS box::
 Typing an end-of-file character (:kbd:`Control-D` on Unix, :kbd:`Control-Z` on
 Windows) at the primary prompt causes the interpreter to exit with a zero exit
 status.  If that doesn't work, you can exit the interpreter by typing the
-following commands: ``import sys; sys.exit()``.
+following command: ``quit()``.
 
 The interpreter's line-editing features usually aren't very sophisticated.  On
 Unix, whoever installed the interpreter may have enabled support for the GNU

Doc/whatsnew/2.6.rst

@@ -2412,9 +2412,13 @@ changes, or look through the Subversion logs for all the details.
   environments.  TIPC addresses are 4- or 5-tuples.
   (Contributed by Alberto Bertogli; :issue:`1646`.)
 
-  A new function, :func:`create_connection`, takes an address
-  and connects to it using an optional timeout value, returning
-  the connected socket object.
+  A new function, :func:`create_connection`, takes an address and
+  connects to it using an optional timeout value, returning the
+  connected socket object.  This function also looks up the address's
+  type and connects to it using IPv4 or IPv6 as appropriate.  Changing
+  your code to use :func:`create_connection` instead of
+  ``socket(socket.AF_INET, ...)`` may be all that's required to make
+  your code work with IPv6.
 
 * The base classes in the :mod:`SocketServer` module now support
   calling a :meth:`handle_timeout` method after a span of inactivity