view tools/python/logging/logging- @ 3887:4385894c52ae

bitkeeper revision 1.1230.2.4 (421a95cepOZORm0EbZfqBeZ6PZ8MwA)

Merge freefall.cl.cam.ac.uk:/auto/groups/xeno/users/cl349/BK/xen-unstable.bk
into freefall.cl.cam.ac.uk:/auto/groups/xeno-xenod/BK/xen-unstable.bk
author iap10@freefall.cl.cam.ac.uk
date Tue Feb 22 02:15:42 2005 +0000 (2005-02-22)
parents dae98734f12e
line source
1 This module is intended to provide error logging functionality for Python
2 programs. It aims to be aligned with Python Enhancement Proposal (PEP) 282.
4 For more information on the package itself, see python_logging.html. In it,
5 there is a description of each file in the distribution.
6 You can also use pydoc to browse the interfaces.
8 Change History
9 --------------
11 Version Date Description
12 =============================================================================
13 28 Feb 2004 Traceback text is now cached.
14 Tracebacks can be propagated across sockets as text.
15 Added makeLogRecord() to allow a LogRecord to be
16 created from a dictionary.
17 Closing a handler now removes it from the internal list
18 used by shutdown().
19 Made close() call flush() for handlers where this makes
20 sense (thanks to Jim Jewett).
21 The exc_info keyword parameter can be used to pass an
22 exception tuple as well as a flag indicating that the
23 current exception should be logged.
24 A shutdown hook is registered to call shutdown() on
25 application (Python) exit (thanks to Jim Jewett).
26 Removed redundant error check in setLoggerClass().
27 Added RESET_ERROR to logging.config.
28 SocketHandler now uses an exponential backoff strategy
29 (thanks to Robert Olson).
30 Minor documentation corrections.
31 -----------------------------------------------------------------------------
32 0.4.8 22 Apr 2003 Made _listener global in stopListening().
33 Made listen() correctly pass the specified port.
34 Removed some redundant imports in __init__.py.
35 Added the record being processed as a parameter to
36 handleError (thanks to Gordon den Otter for the idea).
37 Handler.handle returns the result of applying the
38 filter to the record (thanks to Gordon den Otter for
39 the idea).
40 Added a seek(0, 2) in RotatingFileHandler before the
41 tell() call. This is because under Windows, tell()
42 returns 0 until the first actual write (thanks to
43 Gordon den Otter for the patch).
44 Altered findCaller to not use inspect (thanks to
45 Jeremy Hylton for the patch).
46 Renamed warn and WARN to warning and WARNING. This may
47 break existing code, but the standard Python module
48 will use warning/WARNING rather than warn/WARN. The
49 fatal and FATAL synonyms for critical and CRITICAL
50 have also been removed.
51 Added defaultEncoding and some support for encoding
52 Unicode messages (thanks to Stéphane Bidoul for the
53 suggestion).
54 Added process ID to the list of LogRecord attributes.
55 Modified Logger.removeHandler so that it does not
56 close the handler on removal.
57 Modified SMTPHandler to treat a single "to address"
58 correctly (thanks to Anthony Baxter).
59 Modified SMTPHandler to add a date header to the SMTP
60 message (thanks to David Driver for the suggestion).
61 Modified HTTPHandler to factor out the mapping of
62 a LogRecord to a dictionary (thanks to Franz Glasner
63 for the patch).
64 -----------------------------------------------------------------------------
65 0.4.7 15 Nov 2002 Made into a package with three modules: __init__ (the
66 core code), handlers (all handlers other than
67 FileHandler and its bases) and config (all the config
68 stuff). Before doing this:
69 Updated docstrings to include a short line, then a
70 blank line, then more descriptive text.
71 Renamed 'lvl' to 'level' in various functions.
72 Changed FileHandler to use "a" and "w" instead of "a+"
73 and "w+".
74 Moved log file rotation functionality from FileHandler
75 to a new class RotatingFileHandler.
76 Improved docstring describing rollover.
77 Updated makePickle to use 4-byte length and struct
78 module, likewise logrecv.py. Also updated on-the-fly
79 config reader to use 4-byte length/struct module.
80 Altered ConfigParser test to look at 'readline' rather
81 than 'read'.
82 Added optional "defaults" argument to fileConfig, to
83 be passed to ConfigParser.
84 Renamed ALL to NOTSET to avoid confusion.
85 Commented out getRootLogger(), as obsolete.
86 To do regression testing, run log_test.py and compare
87 the created files stdout.log and stderr.log against
88 the files stdout.exp and stderr.exp. They should match
89 except fir a couple of exception messages which give
90 absolute file paths.
91 Updated python_logging.html to remove links to
92 logging_pydoc.html, which has been removed from the
93 distribution.
94 Changed default for raiseExceptions to 1.
95 -----------------------------------------------------------------------------
96 0.4.6 08 Jul 2002 Added raiseExceptions to allow conditional propagation
97 of exceptions which occur during handling.
98 Added converter to Formatter to allow use of any
99 function to convert time from seconds to a tuple. It
100 still defaults to time.localtime but now you can also
101 use time.gmtime.
102 Added log_test22.py to test the conversion feature.
103 Changed rootlogger default level to WARN - was DEBUG.
104 Updated some docstrings.
105 Moved import of threading to where thread is imported.
106 If either is unavailable, threading support is off.
107 Updated minor defects in python_logging.html.
108 Check to see if ConfigParser has readfp method; if it
109 does and an object with a 'read' method is passed in,
110 assumes a file-like object and uses readfp to read it
111 in.
112 -----------------------------------------------------------------------------
113 0.4.5 04 Jun 2002 Fixed bug which caused problem if no args to message
114 (suggested by Hye-Shik Chang).
115 Fixed bug in _fixupParents (thanks to Nicholas Veeser)
116 and added log_test19.py as a test case for this bug.
117 Added getMessage to LogRecord (code was moved here from
118 Formatter.format)
119 Applied str() to record.msg to allow arbitrary classes
120 to determine the formatting (as msg can now be a class
121 instance).
122 Table of Contents added to python_logging.html, the
123 section on Loggers updated, and the logconf.ini file
124 section annotated.
125 Added log_test20.py which demonstrates how to use
126 class instances to provide alternatives to numeric
127 severities as mechanisms for control of logging.
128 Added log_test21.py which builds on log_test20.py to
129 show how you can use a regular expression-based Filter
130 for flexible matching similar to e.g. Protomatter
131 Syslog, where you can filter on e.g. "a.*" or "*.b" or
132 "a.*.c".
133 _levelNames changed to contain reverse mappings as well
134 as forward mappings (leveltext->level as well as level
135 -> leveltext). The reverse mappings are used by
136 fileConfig().
137 fileConfig() now more forgiving of missing options in
138 .ini file - sensible defaults now used when some
139 options are absent. Also, eval() is used less when
140 interpreting .ini file contents - int() and dict lookup
141 are used in more places.
142 -----------------------------------------------------------------------------
143 0.4.4 02 May 2002 getEffectiveLevel() returns ALL instead of None when
144 nothing found. Modified references to level=0 to
145 level=ALL in a couple of places.
146 SocketHandler now inherits from Handler (it used to
147 inherit from StreamHandler, for no good reason).
148 getLock() renamed to createLock().
149 Docstring tidy-ups, and some tidying up of
150 DatagramHandler.
151 Factored out unpickling in logrecv.py.
152 Added log_test18.py to illustrate MatchFilter, which is
153 a general matching filter.
154 Improved FileHandler.doRollover() so that the base
155 file name is always the most recent, then .1, then .2
156 etc. up to the maximum backup count. Renamed formal
157 args and attributes used in rollover.
158 Changed LogRecord attributes lvl -> levelno, level ->
159 levelname (less ambiguity)
160 Formatter.format searches for "%(asctime)" rather than
161 "(asctime)"
162 Renamed _start_time to _startTime
163 Formatter.formatTime now returns the time
164 Altered logrecv.py to support stopping servers
165 programmatically
166 Added log_test.py as overall test harness
167 basicConfig() can now be safely called more than once
168 Modified test scripts to make it easier to call them
169 from log_test.py
170 Moved SOAPHandler from core to log_test13.py. It's not
171 general enough to be in the core; most production use
172 will have differing RPC signatures.
173 -----------------------------------------------------------------------------
174 0.4.3 14 Apr 2002 Bug fix one-off error message to go to sys.stderr
175 rather than sys.stdout.
176 logrecv.py fix TCP for busy network.
177 Thread safety - added locking to Handler and for shared
178 data in module, and log_test16.py to test it.
179 Added socket listener to allow on-the-fly configuration
180 and added log_test17.py to test it.
181 -----------------------------------------------------------------------------
182 0.4.2 11 Apr 2002 Bug fix fileConfig() - setup of MemoryHandler target
183 and errors when loggers have no handlers set or
184 handlers have no formatters set
185 logconf.py - seems to hang if window closed when combo
186 dropdown is showing - added code to close popup on exit
187 Some tweaks to _srcfile computation (normpath added)
188 findCaller() optimized, now a lot faster!
189 Logger.removeHandler now closes the handler before
190 removing it
191 fileConfig() removes existing handlers before adding
192 the new set, to avoid memory leakage when repeated
193 calls are made
194 Fixed logrecv.py bug which hogged CPU time when TCP
195 connection was closed from the client
196 Added log_test14.py to demonstrate/test a DBHandler
197 which writes logging records into an RDBMS using the
198 Python Database API 2.0 (to run, you need something
199 which supports this already installed - I tested with
200 mxODBC)
201 Made getLogger name argument optional - returns root
202 logger if omitted
203 Altered Filter to take a string initializer, filtering
204 a sub-hierarchy rooted at a particular point (idea from
205 Denis S. Otkidach).
206 Added log_test15.py to test Filter initializer
207 Minor docstring changes
208 -----------------------------------------------------------------------------
209 0.4.1 03 Apr 2002 Bug fix SMTPHandler - extra \r\n needed (Oleg Orlov)
210 Added BufferingHandler, BufferingFormatter
211 Renamed getChainedPriority to getEffectiveLevel
212 Removed Logger.getRoot as it is redundant
213 Added log_test9.py to test Buffering classes and
214 to show an XMLFormatter example.
215 Added setLoggerClass.
216 Added log_test10.py to test setLoggerClass, using an
217 example Logger-derived class which outputs exception
218 info even for DEBUG level logging calls
219 Added log_test11.py to test a buffering implementation
220 of SMTPHandler
221 Changed logging call implementation to allow keyword
222 arguments (Kevin Butler and others)
223 Changed default SysLogHandler implementation.
224 Renamed "additive" to "propagate" as it better
225 describes the attribute.
226 Added HTTPHandler.
227 Modified logrecv.py to remove "both" option and to add
228 "HTTP" and "SOAP" options (SOAP option needs you to
229 have PyXML-0.6.6 and ZSI installed - for logrecv.py
230 only, and not for the core logging module itself).
231 Added log_test12.py to test HTTPHandler.
232 Added log_test13.py to test SOAPHandler.
233 Formatted to Python source guidelines (spaces, indent
234 of 4, within 80 columns).
235 More method renamings (result of feedback) - _handle()
236 renamed to emit(), _logRecord() renamed to handle().
237 Renamed FATAL to CRITICAL (David Goodger), but left
238 fatal() and FATAL in (until PEP is changed)
239 Changed configuration file format to ConfigParser
240 format.
241 Factored filter application functionality out to a new
242 Filterer class. The isLoggable() method is renamed to
243 filter() in both Filter and Filterer classes.
244 Altered SMTPHandler __init__ to accept (host, port)
245 for the mail internet address.
246 Added GUI configurator which uses Tkinter and the new
247 configuration file format. (See logconf.py and an
248 example configuration file in logconf.ini)
249 Altered log_test3.py to test with the new file format.
250 -----------------------------------------------------------------------------
251 0.4 21 Mar 2002 Incorporated comments/patches from Ollie Rutherfurd:
252 -Added level filtering for handlers.
253 -Return root logger if no name specified in getLogger.
254 Incorporated comments from Greg Ward:
255 -Added distutils setup.py script.
256 Added formatter initialization in Handler.__init__.
257 Tidied up docstrings.
258 Added removeHandler to Logger.
259 Added removeFilter to Logger and Handler.
260 logrecv.py modified to keep connection alive until
261 client closes it.
262 SocketHandler modified to not reset connection after
263 each logging event.
264 Added shutdown function which closes open sockets
267 Added log_test4.py (example of arbitrary levels)
268 Added addLevelName, changed behaviour of getLevelName
269 Fixed bugs in DatagramHandler
270 Added SMTPHandler implementation
271 Added log_test5.py to test SMTPHandler
272 Added SysLogHandler (contribution from Nicolas Untz
273 based on Sam Rushing's syslog.py)
274 Modified log_test1.py to add a SysLogHandler
275 Added rollover functionality to FileHandler
276 Added NTEventLogHandler (based on Win32 extensions)
277 Added MemoryHandler implementation
278 Added log_test7.py to test MemoryHandler
279 Added log_test8.py to test FileHandler rollover
280 Added logException method to Logger
281 Added formatException method to Formatter
282 Added log_test6.py to test NTEventHandler and
283 logException
284 Numerous internal method renamings (sorry - but better
285 to do this now, rather than when we enter beta status).
286 -----------------------------------------------------------------------------
287 0.3 14 Mar 2002 First public release, for early feedback
288 -----------------------------------------------------------------------------
289 0.2 Consolidated into single file (for internal use only)
290 -----------------------------------------------------------------------------
291 0.1 Initial implementation (for internal use only)
292 -----------------------------------------------------------------------------
294 -----------------------------------------------------------------------------
296 -----------------------------------------------------------------------------
297 Copyright 2001-2002 by Vinay Sajip. All Rights Reserved.
299 Permission to use, copy, modify, and distribute this software and its
300 documentation for any purpose and without fee is hereby granted,
301 provided that the above copyright notice appear in all copies and that
302 both that copyright notice and this permission notice appear in
303 supporting documentation, and that the name of Vinay Sajip
304 not be used in advertising or publicity pertaining to distribution
305 of the software without specific, written prior permission.