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/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)