Merged revisions 66045,66048-66049,66053,66060,66062-66063,66065,66067,66071-66074,66080,66082-66083,66090-66093,66097-66099,66103,66105,66110,66118 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r66045 | andrew.kuchling | 2008-08-26 19:27:18 -0500 (Tue, 26 Aug 2008) | 1 line

  Trim whitespace; add a few updates
........
  r66048 | andrew.kuchling | 2008-08-26 19:45:02 -0500 (Tue, 26 Aug 2008) | 1 line

  Add an item and a note
........
  r66049 | andrew.kuchling | 2008-08-26 21:12:18 -0500 (Tue, 26 Aug 2008) | 1 line

  Add various items
........
  r66053 | georg.brandl | 2008-08-28 04:40:18 -0500 (Thu, 28 Aug 2008) | 2 lines

  #3711: .dll isn't a valid Python extension anymore.
........
  r66060 | armin.rigo | 2008-08-29 16:21:52 -0500 (Fri, 29 Aug 2008) | 3 lines

  A collection of crashers, all variants of the idea
  of issue #3720.
........
  r66062 | georg.brandl | 2008-08-30 04:49:36 -0500 (Sat, 30 Aug 2008) | 2 lines

  #3730: mention "server" attribute explicitly.
........
  r66063 | georg.brandl | 2008-08-30 04:52:44 -0500 (Sat, 30 Aug 2008) | 2 lines

  #3716: fix typo.
........
  r66065 | georg.brandl | 2008-08-30 05:03:09 -0500 (Sat, 30 Aug 2008) | 2 lines

  #3569: eval() also accepts "exec"able code objects.
........
  r66067 | georg.brandl | 2008-08-30 08:17:39 -0500 (Sat, 30 Aug 2008) | 2 lines

  super() actually returns a super object.
........
  r66071 | andrew.kuchling | 2008-08-30 10:19:57 -0500 (Sat, 30 Aug 2008) | 1 line

  Partial edits from revision and tidying pass
........
  r66072 | andrew.kuchling | 2008-08-30 10:21:23 -0500 (Sat, 30 Aug 2008) | 1 line

  Tidy up some sentences
........
  r66073 | andrew.kuchling | 2008-08-30 10:25:47 -0500 (Sat, 30 Aug 2008) | 1 line

  Correction from Antoine Pitrou: BufferedWriter and Reader support seek()
........
  r66074 | andrew.kuchling | 2008-08-30 11:44:54 -0500 (Sat, 30 Aug 2008) | 1 line

  Edit four more sections
........
  r66080 | georg.brandl | 2008-08-30 17:00:28 -0500 (Sat, 30 Aug 2008) | 2 lines

  Fix markup.
........
  r66082 | andrew.kuchling | 2008-08-30 17:56:54 -0500 (Sat, 30 Aug 2008) | 1 line

  More edits; markup fixes
........
  r66083 | andrew.kuchling | 2008-08-30 21:24:08 -0500 (Sat, 30 Aug 2008) | 1 line

  More edits
........
  r66090 | andrew.kuchling | 2008-08-31 09:29:31 -0500 (Sun, 31 Aug 2008) | 1 line

  Edit the library section, rearranging items to flow better and making lots of edits
........
  r66091 | andrew.kuchling | 2008-08-31 10:41:48 -0500 (Sun, 31 Aug 2008) | 1 line

  Last batch of edits; remove the 'other changes' section
........
  r66092 | andrew.kuchling | 2008-08-31 10:48:44 -0500 (Sun, 31 Aug 2008) | 1 line

  Update patch/bug count
........
  r66093 | gregory.p.smith | 2008-08-31 11:34:18 -0500 (Sun, 31 Aug 2008) | 3 lines

  issue3715: docstring representation of hex escaped string needs to be double
  escaped.
........
  r66097 | benjamin.peterson | 2008-09-01 09:13:43 -0500 (Mon, 01 Sep 2008) | 4 lines

  #3703 unhelpful _fileio.FileIO error message when trying to open a directory

  Reviewer: Gregory P. Smith
........
  r66098 | georg.brandl | 2008-09-01 09:15:55 -0500 (Mon, 01 Sep 2008) | 2 lines

  #3749: fix c'n'p errors.
........
  r66099 | benjamin.peterson | 2008-09-01 09:18:30 -0500 (Mon, 01 Sep 2008) | 4 lines

  Fix compilation when --without-threads is given #3683

  Reviewer: Georg Brandl, Benjamin Peterson
........
  r66103 | vinay.sajip | 2008-09-01 09:30:10 -0500 (Mon, 01 Sep 2008) | 1 line

  logging: fixed lack of use of encoding attribute specified on a stream.
........
  r66105 | vinay.sajip | 2008-09-01 09:33:59 -0500 (Mon, 01 Sep 2008) | 1 line

  logging: fixed lack of use of encoding attribute specified on a stream.
........
  r66110 | vinay.sajip | 2008-09-01 10:08:07 -0500 (Mon, 01 Sep 2008) | 1 line

  Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
........
  r66118 | vinay.sajip | 2008-09-01 12:44:14 -0500 (Mon, 01 Sep 2008) | 1 line

  Bug #3738: Documentation is now more accurate in describing handler close methods.
........

6 files changed, 80 insertions, 34 deletions

diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index 29f0350..9fff0a2 100644
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -51,13 +51,13 @@ It defines the following functions:
    Codec Interface). The functions/methods are expected to work in a stateless
    mode.
 
-   *incrementalencoder* and *incrementalencoder*: These have to be factory
+   *incrementalencoder* and *incrementaldecoder*: These have to be factory
    functions providing the following interface:
 
    ``factory(errors='strict')``
 
    The factory functions must return objects providing the interfaces defined by
-   the base classes :class:`IncrementalEncoder` and :class:`IncrementalEncoder`,
+   the base classes :class:`IncrementalEncoder` and :class:`IncrementalDecoder`,
    respectively. Incremental codecs can maintain state.
 
    *streamreader* and *streamwriter*: These have to be factory functions providing
@@ -478,7 +478,7 @@ define in order to be compatible with the Python codec registry.
 
    The *errors* argument will be assigned to an attribute of the same name.
    Assigning to this attribute makes it possible to switch between different error
-   handling strategies during the lifetime of the :class:`IncrementalEncoder`
+   handling strategies during the lifetime of the :class:`IncrementalDecoder`
    object.
 
    The set of allowed values for the *errors* argument can be extended with
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index a5e16df..9156bd2 100644
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -8,7 +8,7 @@
 
 
 ``ctypes`` is a foreign function library for Python.  It provides C compatible
-data types, and allows calling functions in dlls/shared libraries.  It can be
+data types, and allows calling functions in DLLs or shared libraries.  It can be
 used to wrap these libraries in pure Python.
 
 
@@ -21,8 +21,8 @@ Note: The code samples in this tutorial use ``doctest`` to make sure that they
 actually work.  Since some code samples behave differently under Linux, Windows,
 or Mac OS X, they contain doctest directives in comments.
 
-Note: Some code sample references the ctypes :class:`c_int` type. This type is
-an alias to the :class:`c_long` type on 32-bit systems.  So, you should not be
+Note: Some code samples reference the ctypes :class:`c_int` type. This type is
+an alias for the :class:`c_long` type on 32-bit systems.  So, you should not be
 confused if :class:`c_long` is printed if you would expect :class:`c_int` ---
 they are actually the same type.
 
@@ -32,8 +32,8 @@ they are actually the same type.
 Loading dynamic link libraries
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-``ctypes`` exports the *cdll*, and on Windows also *windll* and *oledll* objects
-to load dynamic link libraries.
+``ctypes`` exports the *cdll*, and on Windows *windll* and *oledll*
+objects, for loading dynamic link libraries.
 
 You load libraries by accessing them as attributes of these objects. *cdll*
 loads libraries which export functions using the standard ``cdecl`` calling
@@ -315,7 +315,7 @@ property::
    >>> p = create_string_buffer("Hello", 10)  # create a 10 byte buffer
    >>> print(sizeof(p), repr(p.raw))
    10 'Hello\x00\x00\x00\x00\x00'
-   >>> p.value = "Hi"      
+   >>> p.value = "Hi"
    >>> print(sizeof(p), repr(p.raw))
    10 'Hi\x00lo\x00\x00\x00\x00\x00'
    >>>
@@ -906,7 +906,7 @@ other, and finally follow the pointer chain a few times::
    ...     p = p.next[0]
    ...
    foo bar foo bar foo bar foo bar
-   >>>    
+   >>>
 
 
 .. _ctypes-callback-functions:
@@ -2018,7 +2018,7 @@ Data types
 
    .. method:: _CData.from_buffer_copy(source[, offset])
 
-      This method creates a ctypes instance, the buffer is copied from
+      This method creates a ctypes instance, copying the buffer from
       the source object buffer which must be readable.  The optional
       ``offset`` parameter specifies an offset into the source buffer
       in bytes; the default is zero.  If the source buffer is not
@@ -2033,13 +2033,13 @@ Data types
 
    .. method:: from_param(obj)
 
-      This method adapts obj to a ctypes type.  It is called with the actual
-      object used in a foreign function call, when the type is present in the
-      foreign functions :attr:`argtypes` tuple; it must return an object that
-      can be used as function call parameter.
+      This method adapts *obj* to a ctypes type.  It is called with the actual
+      object used in a foreign function call when the type is present in the
+      foreign function's :attr:`argtypes` tuple; it must return an object that
+      can be used as a function call parameter.
 
-      All ctypes data types have a default implementation of this classmethod,
-      normally it returns ``obj`` if that is an instance of the type.  Some
+      All ctypes data types have a default implementation of this classmethod
+      that normally returns ``obj`` if that is an instance of the type.  Some
       types accept other objects as well.
 
 
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index ac40ce7..aa60be9 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -372,10 +372,10 @@ are always available.  They are listed here in alphabetical order.
       >>> eval('x+1')
       2
 
-   This function can also be used to execute arbitrary code objects (such as those
-   created by :func:`compile`).  In this case pass a code object instead of a
-   string.  The code object must have been compiled passing ``'eval'`` as the
-   *kind* argument.
+   This function can also be used to execute arbitrary code objects (such as
+   those created by :func:`compile`).  In this case pass a code object instead
+   of a string.  If the code object has been compiled with ``'exec'`` as the
+   *kind* argument, :func:`eval`\'s return value will be ``None``.
 
    Hints: dynamic execution of statements is supported by the :func:`exec`
    function.  The :func:`globals` and :func:`locals` functions
@@ -1086,14 +1086,14 @@ are always available.  They are listed here in alphabetical order.
 
    .. XXX updated as per http://www.artima.com/weblogs/viewpost.jsp?thread=208549 but needs checking
 
-   Return the superclass of *type*.
-   
-   Calling :func:`super()` without arguments is equivalent to
-   ``super(this_class, first_arg)``. If called with one
-   argument the super object returned is unbound.  If called with two
-   arguments and the second argument is an object, ``isinstance(obj,
-   type)`` must be true.  If the second argument is a type,
-   ``issubclass(type2, type)`` must be true.
+
+   Return a "super" object that acts like the superclass of *type*.  If the
+   second argument is omitted the super object returned is unbound.  If the
+   second argument is an object, ``isinstance(obj, type)`` must be true.  If the
+   second argument is a type, ``issubclass(type2, type)`` must be
+   true. :func:`super` only works for :term:`new-style class`\es.  Calling
+   :func:`super()` without arguments is equivalent to ``super(this_class,
+   first_arg)``.
 
    A typical use for calling a cooperative superclass method is::
 
diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst
index f025b25..cad28dd 100644
--- a/Doc/library/http.server.rst
+++ b/Doc/library/http.server.rst
@@ -56,6 +56,11 @@ of which this module provides three different variants:
       Contains a tuple of the form ``(host, port)`` referring to the client's
       address.
 
+   .. attribute:: server
+
+      Contains the server instance.
+
+
    .. attribute:: command
 
       Contains the command (request type). For example, ``'GET'``.
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index 43e738e..e19f189 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -420,6 +420,45 @@ You can see that the config file approach has a few advantages over the Python
 code approach, mainly separation of configuration and code and the ability of
 noncoders to easily modify the logging properties.
 
+Configuring Logging for a Library
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When developing a library which uses logging, some consideration needs to be
+given to its configuration. If the using application does not use logging, and
+library code makes logging calls, then a one-off message "No handlers could be
+found for logger X.Y.Z" is printed to the console. This message is intended
+to catch mistakes in logging configuration, but will confuse an application
+developer who is not aware of logging by the library.
+
+In addition to documenting how a library uses logging, a good way to configure
+library logging so that it does not cause a spurious message is to add a
+handler which does nothing. This avoids the message being printed, since a
+handler will be found: it just doesn't produce any output. If the library user
+configures logging for application use, presumably that configuration will add
+some handlers, and if levels are suitably configured then logging calls made
+in library code will send output to those handlers, as normal.
+
+A do-nothing handler can be simply defined as follows::
+
+    import logging
+
+    class NullHandler(logging.Handler):
+        def emit(self, record):
+            pass
+
+An instance of this handler should be added to the top-level logger of the
+logging namespace used by the library. If all logging by a library *foo* is
+done using loggers with names matching "foo.x.y", then the code::
+
+    import logging
+
+    h = NullHandler()
+    logging.getLogger("foo").addHandler(h)
+
+should have the desired effect. If an organisation produces a number of
+libraries, then the logger name specified can be "orgname.foo" rather than
+just "foo".
+
 
 Logging Levels
 --------------
@@ -1440,8 +1479,10 @@ subclasses. However, the :meth:`__init__` method in subclasses needs to call
 
 .. method:: Handler.close()
 
-   Tidy up any resources used by the handler. This version does nothing and is
-   intended to be implemented by subclasses.
+   Tidy up any resources used by the handler. This version does no output but
+   removes the handler from an internal list of handlers which is closed when
+   :func:`shutdown` is called. Subclasses should ensure that this gets called
+   from overridden :meth:`close` methods.
 
 
 .. method:: Handler.handle(record)
@@ -1503,7 +1544,7 @@ and :meth:`flush` methods).
 
       Flushes the stream by calling its :meth:`flush` method. Note that the
       :meth:`close` method is inherited from :class:`Handler` and so does
-      nothing, so an explicit :meth:`flush` call may be needed at times.
+      no output, so an explicit :meth:`flush` call may be needed at times.
 
 
 FileHandler
@@ -1821,7 +1862,7 @@ extensions for Python installed.
       source of event log entries. However, if you do this, you will not be able
       to see the events as you intended in the Event Log Viewer - it needs to be
       able to access the registry to get the .dll name. The current version does
-      not do this (in fact it doesn't do anything).
+      not do this.
 
 
    .. method:: emit(record)
diff --git a/Doc/library/math.rst b/Doc/library/math.rst
index a7dd4dd..588aef3 100644
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -290,7 +290,7 @@ The module also defines two mathematical constants:
    :exc:`OverflowError`, ``math.log(0L)`` may raise :exc:`ValueError` instead.
 
    All functions return a quiet *NaN* if at least one of the args is *NaN*.
-   Signaling *NaN*s raise an exception. The exception type still depends on the
+   Signaling *NaN*\s raise an exception. The exception type still depends on the
    platform and libm implementation. It's usually :exc:`ValueError` for *EDOM*
    and :exc:`OverflowError` for errno *ERANGE*.