Merged revisions 77967,77969,77973,77979,77985-77986,78009,78029,78031-78033,78081,78085,78103,78105-78106,78108,78246,78703,78728,78731,78853,78855 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r77967 | vinay.sajip | 2010-02-04 12:48:53 -0600 (Thu, 04 Feb 2010) | 1 line
Logging: Implemented PEP 391.
........
r77969 | vinay.sajip | 2010-02-04 14:18:28 -0600 (Thu, 04 Feb 2010) | 1 line
Removed spurious print statement.
........
r77973 | vinay.sajip | 2010-02-04 14:23:45 -0600 (Thu, 04 Feb 2010) | 1 line
Issue #7851: logging: clarification on logging configuration files.
........
r77979 | vinay.sajip | 2010-02-04 15:40:56 -0600 (Thu, 04 Feb 2010) | 1 line
Added unit test for cfg:// resolution.
........
r77985 | vinay.sajip | 2010-02-05 08:52:05 -0600 (Fri, 05 Feb 2010) | 1 line
Issue #7857: test_logging: listener test now uses find_unused_port().
........
r77986 | vinay.sajip | 2010-02-05 09:40:20 -0600 (Fri, 05 Feb 2010) | 1 line
Issue #7857: test_logging: listener tests disabled for now.
........
r78009 | vinay.sajip | 2010-02-05 17:43:11 -0600 (Fri, 05 Feb 2010) | 1 line
test_logging: minor tweaks to timeouts, listening tests marked as skipped.
........
r78029 | vinay.sajip | 2010-02-06 14:00:43 -0600 (Sat, 06 Feb 2010) | 1 line
Issue #7857: Tentatively re-enabling one test to see effect on buildbots.
........
r78031 | vinay.sajip | 2010-02-06 14:28:36 -0600 (Sat, 06 Feb 2010) | 1 line
Issue #7857: Gave server thread more time to get ready, and re-enabled a skipped test.
........
r78032 | georg.brandl | 2010-02-06 15:54:40 -0600 (Sat, 06 Feb 2010) | 1 line
Remove unused imports from test_logging.
........
r78033 | benjamin.peterson | 2010-02-06 16:08:15 -0600 (Sat, 06 Feb 2010) | 1 line
make waiting for the server to start robust
........
r78081 | vinay.sajip | 2010-02-07 06:56:54 -0600 (Sun, 07 Feb 2010) | 1 line
Issue #7869: logging: improved format-time diagnostics and removed some 1.5.2 support code.
........
r78085 | vinay.sajip | 2010-02-07 07:06:51 -0600 (Sun, 07 Feb 2010) | 1 line
logging: Removed some more 1.5.2 support code.
........
r78103 | vinay.sajip | 2010-02-08 00:50:14 -0600 (Mon, 08 Feb 2010) | 1 line
Removed spurious print statement in test.
........
r78105 | vinay.sajip | 2010-02-08 09:32:08 -0600 (Mon, 08 Feb 2010) | 1 line
logging: skipped listening tests because they're not working reliably.
........
r78106 | vinay.sajip | 2010-02-08 10:05:50 -0600 (Mon, 08 Feb 2010) | 1 line
Issue #7857: Another attempt to keep the buildbots happy.
........
r78108 | vinay.sajip | 2010-02-08 15:18:15 -0600 (Mon, 08 Feb 2010) | 1 line
logging: gingerly re-enabling skipped tests after improving thread sync code in configurator.
........
r78246 | vinay.sajip | 2010-02-19 17:53:17 -0600 (Fri, 19 Feb 2010) | 1 line
logging: Documented warnings module integration.
........
r78703 | vinay.sajip | 2010-03-05 16:11:24 -0600 (Fri, 05 Mar 2010) | 1 line
Factored out time usage determination into a method, to facilitate alternative formatting implementations in the future.
........
r78728 | vinay.sajip | 2010-03-06 09:12:08 -0600 (Sat, 06 Mar 2010) | 1 line
Added schema version test in dictConfig.
........
r78731 | vinay.sajip | 2010-03-06 09:56:03 -0600 (Sat, 06 Mar 2010) | 1 line
Added checks for tuples in dictConfig.
........
r78853 | vinay.sajip | 2010-03-12 00:01:21 -0600 (Fri, 12 Mar 2010) | 1 line
Issue #8117: logging: Improved algorithm for computing initial rollover time.
........
r78855 | vinay.sajip | 2010-03-12 03:16:10 -0600 (Fri, 12 Mar 2010) | 1 line
Issue #8117: Updated NEWS entry and added to logging documentation.
........
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index 6e809cd..c5997ef 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -420,6 +420,13 @@
code approach, mainly separation of configuration and code and the ability of
noncoders to easily modify the logging properties.
+Note that the class names referenced in config files need to be either relative
+to the logging module, or absolute values which can be resolved using normal
+import mechanisms. Thus, you could use either `handlers.WatchedFileHandler`
+(relative to the logging module) or `mypackage.mymodule.MyHandler` (for a
+class defined in package `mypackage` and module `mymodule`, where `mypackage`
+is available on the Python import path).
+
.. _library-config:
Configuring Logging for a Library
@@ -1849,6 +1856,11 @@
The extensions are date-and-time based, using the strftime format
``%Y-%m-%d_%H-%M-%S`` or a leading portion thereof, depending on the
rollover interval.
+
+ When computing the next rollover time for the first time (when the handler
+ is created), the last modification time of an existing log file, or else
+ the current time, is used to compute when the next rotation will occur.
+
If the *utc* argument is true, times in UTC will be used; otherwise
local time is used.
@@ -2401,6 +2413,28 @@
because lock implementations in the :mod:`threading` module are not always
re-entrant, and so cannot be invoked from such signal handlers.
+
+Integration with the warnings module
+------------------------------------
+
+The :func:`captureWarnings` function can be used to integrate :mod:`logging`
+with the :mod:`warnings` module.
+
+.. function:: captureWarnings(capture)
+
+ This function is used to turn the capture of warnings by logging on and
+ off.
+
+ If `capture` is `True`, warnings issued by the :mod:`warnings` module
+ will be redirected to the logging system. Specifically, a warning will be
+ formatted using :func:`warnings.formatwarning` and the resulting string
+ logged to a logger named "py.warnings" with a severity of `WARNING`.
+
+ If `capture` is `False`, the redirection of warnings to the logging system
+ will stop, and warnings will be redirected to their original destinations
+ (i.e. those in effect before `captureWarnings(True)` was called).
+
+
Configuration
-------------