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.
........
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 @@
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 @@
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 @@
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 @@
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 @@
>>> 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 @@
... p = p.next[0]
...
foo bar foo bar foo bar foo bar
- >>>
+ >>>
.. _ctypes-callback-functions:
@@ -2018,7 +2018,7 @@
.. 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 @@
.. 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 @@
>>> 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 @@
.. 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 @@
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 @@
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 @@
.. 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 @@
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 @@
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 @@
: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*.