Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <link rel="STYLESHEET" href="lib.css" type='text/css' /> | |
5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> | |
6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> | |
7 | <link rel="first" href="lib.html" title='Python Library Reference' /> | |
8 | <link rel='contents' href='contents.html' title="Contents" /> | |
9 | <link rel='index' href='genindex.html' title='Index' /> | |
10 | <link rel='last' href='about.html' title='About this document...' /> | |
11 | <link rel='help' href='about.html' title='About this document...' /> | |
12 | <link rel="next" href="module-platform.html" /> | |
13 | <link rel="prev" href="module-gettext.html" /> | |
14 | <link rel="parent" href="allos.html" /> | |
15 | <link rel="next" href="node341.html" /> | |
16 | <meta name='aesop' content='information' /> | |
17 | <title>6.29 logging -- Logging facility for Python</title> | |
18 | </head> | |
19 | <body> | |
20 | <DIV CLASS="navigation"> | |
21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> | |
22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
23 | <tr> | |
24 | <td class='online-navigation'><a rel="prev" title="6.28.4 Acknowledgements" | |
25 | href="node339.html"><img src='../icons/previous.png' | |
26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
27 | <td class='online-navigation'><a rel="parent" title="6. Generic Operating System" | |
28 | href="allos.html"><img src='../icons/up.png' | |
29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
30 | <td class='online-navigation'><a rel="next" title="6.29.1 Logger Objects" | |
31 | href="node341.html"><img src='../icons/next.png' | |
32 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
33 | <td align="center" width="100%">Python Library Reference</td> | |
34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
35 | href="contents.html"><img src='../icons/contents.png' | |
36 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
37 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
38 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
39 | <td class='online-navigation'><a rel="index" title="Index" | |
40 | href="genindex.html"><img src='../icons/index.png' | |
41 | border='0' height='32' alt='Index' width='32' /></A></td> | |
42 | </tr></table> | |
43 | <div class='online-navigation'> | |
44 | <b class="navlabel">Previous:</b> | |
45 | <a class="sectref" rel="prev" href="node339.html">6.28.4 Acknowledgements</A> | |
46 | <b class="navlabel">Up:</b> | |
47 | <a class="sectref" rel="parent" href="allos.html">6. Generic Operating System</A> | |
48 | <b class="navlabel">Next:</b> | |
49 | <a class="sectref" rel="next" href="node341.html">6.29.1 Logger Objects</A> | |
50 | </div> | |
51 | <hr /></div> | |
52 | </DIV> | |
53 | <!--End of Navigation Panel--> | |
54 | ||
55 | <H1><A NAME="SECTION0082900000000000000000"> | |
56 | 6.29 <tt class="module">logging</tt> -- | |
57 | Logging facility for Python</A> | |
58 | </H1> | |
59 | ||
60 | <P> | |
61 | <A NAME="module-logging"></A> | |
62 | <P> | |
63 | ||
64 | <P> | |
65 | ||
66 | <P> | |
67 | <a id='l2h-2456' xml:id='l2h-2456'></a> | |
68 | <P> | |
69 | ||
70 | <span class="versionnote">New in version 2.3.</span> | |
71 | ||
72 | This module defines functions and classes which implement a flexible | |
73 | error logging system for applications. | |
74 | ||
75 | <P> | |
76 | Logging is performed by calling methods on instances of the | |
77 | <tt class="class">Logger</tt> class (hereafter called <i class="dfn">loggers</i>). Each instance has a | |
78 | name, and they are conceptually arranged in a name space hierarchy | |
79 | using dots (periods) as separators. For example, a logger named | |
80 | "scan" is the parent of loggers "scan.text", "scan.html" and "scan.pdf". | |
81 | Logger names can be anything you want, and indicate the area of an | |
82 | application in which a logged message originates. | |
83 | ||
84 | <P> | |
85 | Logged messages also have levels of importance associated with them. | |
86 | The default levels provided are <tt class="constant">DEBUG</tt>, <tt class="constant">INFO</tt>, | |
87 | <tt class="constant">WARNING</tt>, <tt class="constant">ERROR</tt> and <tt class="constant">CRITICAL</tt>. As a | |
88 | convenience, you indicate the importance of a logged message by calling | |
89 | an appropriate method of <tt class="class">Logger</tt>. The methods are | |
90 | <tt class="method">debug()</tt>, <tt class="method">info()</tt>, <tt class="method">warning()</tt>, <tt class="method">error()</tt> and | |
91 | <tt class="method">critical()</tt>, which mirror the default levels. You are not | |
92 | constrained to use these levels: you can specify your own and use a | |
93 | more general <tt class="class">Logger</tt> method, <tt class="method">log()</tt>, which takes an | |
94 | explicit level argument. | |
95 | ||
96 | <P> | |
97 | The numeric values of logging levels are given in the following table. These | |
98 | are primarily of interest if you want to define your own levels, and need | |
99 | them to have specific values relative to the predefined levels. If you | |
100 | define a level with the same numeric value, it overwrites the predefined | |
101 | value; the predefined name is lost. | |
102 | ||
103 | <P> | |
104 | <div class="center"><table class="realtable"> | |
105 | <thead> | |
106 | <tr> | |
107 | <th class="left" >Level</th> | |
108 | <th class="left" >Numeric value</th> | |
109 | </tr> | |
110 | </thead> | |
111 | <tbody> | |
112 | <tr><td class="left" valign="baseline"><code>CRITICAL</code></td> | |
113 | <td class="left" >50</td></tr> | |
114 | <tr><td class="left" valign="baseline"><code>ERROR</code></td> | |
115 | <td class="left" >40</td></tr> | |
116 | <tr><td class="left" valign="baseline"><code>WARNING</code></td> | |
117 | <td class="left" >30</td></tr> | |
118 | <tr><td class="left" valign="baseline"><code>INFO</code></td> | |
119 | <td class="left" >20</td></tr> | |
120 | <tr><td class="left" valign="baseline"><code>DEBUG</code></td> | |
121 | <td class="left" >10</td></tr> | |
122 | <tr><td class="left" valign="baseline"><code>NOTSET</code></td> | |
123 | <td class="left" >0</td></tr></tbody> | |
124 | </table></div> | |
125 | ||
126 | <P> | |
127 | Levels can also be associated with loggers, being set either by the | |
128 | developer or through loading a saved logging configuration. When a | |
129 | logging method is called on a logger, the logger compares its own | |
130 | level with the level associated with the method call. If the logger's | |
131 | level is higher than the method call's, no logging message is actually | |
132 | generated. This is the basic mechanism controlling the verbosity of | |
133 | logging output. | |
134 | ||
135 | <P> | |
136 | Logging messages are encoded as instances of the <tt class="class">LogRecord</tt> class. | |
137 | When a logger decides to actually log an event, an <tt class="class">LogRecord</tt> | |
138 | instance is created from the logging message. | |
139 | ||
140 | <P> | |
141 | Logging messages are subjected to a dispatch mechanism through the | |
142 | use of <i class="dfn">handlers</i>, which are instances of subclasses of the | |
143 | <tt class="class">Handler</tt> class. Handlers are responsible for ensuring that a logged | |
144 | message (in the form of a <tt class="class">LogRecord</tt>) ends up in a particular | |
145 | location (or set of locations) which is useful for the target audience for | |
146 | that message (such as end users, support desk staff, system administrators, | |
147 | developers). Handlers are passed <tt class="class">LogRecord</tt> instances intended for | |
148 | particular destinations. Each logger can have zero, one or more handlers | |
149 | associated with it (via the <tt class="method">addHandler()</tt> method of <tt class="class">Logger</tt>). | |
150 | In addition to any handlers directly associated with a logger, | |
151 | <em>all handlers associated with all ancestors of the logger</em> are | |
152 | called to dispatch the message. | |
153 | ||
154 | <P> | |
155 | Just as for loggers, handlers can have levels associated with them. | |
156 | A handler's level acts as a filter in the same way as a logger's level does. | |
157 | If a handler decides to actually dispatch an event, the <tt class="method">emit()</tt> method | |
158 | is used to send the message to its destination. Most user-defined subclasses | |
159 | of <tt class="class">Handler</tt> will need to override this <tt class="method">emit()</tt>. | |
160 | ||
161 | <P> | |
162 | In addition to the base <tt class="class">Handler</tt> class, many useful subclasses | |
163 | are provided: | |
164 | ||
165 | <P> | |
166 | ||
167 | <OL> | |
168 | <LI><tt class="class">StreamHandler</tt> instances send error messages to | |
169 | streams (file-like objects). | |
170 | ||
171 | <P> | |
172 | </LI> | |
173 | <LI><tt class="class">FileHandler</tt> instances send error messages to disk | |
174 | files. | |
175 | ||
176 | <P> | |
177 | </LI> | |
178 | <LI><tt class="class">BaseRotatingHandler</tt> is the base class for handlers that | |
179 | rotate log files at a certain point. It is not meant to be instantiated | |
180 | directly. Instead, use <tt class="class">RotatingFileHandler</tt> or | |
181 | <tt class="class">TimedRotatingFileHandler</tt>. | |
182 | ||
183 | <P> | |
184 | </LI> | |
185 | <LI><tt class="class">RotatingFileHandler</tt> instances send error messages to disk | |
186 | files, with support for maximum log file sizes and log file rotation. | |
187 | ||
188 | <P> | |
189 | </LI> | |
190 | <LI><tt class="class">TimedRotatingFileHandler</tt> instances send error messages to | |
191 | disk files rotating the log file at certain timed intervals. | |
192 | ||
193 | <P> | |
194 | </LI> | |
195 | <LI><tt class="class">SocketHandler</tt> instances send error messages to | |
196 | TCP/IP sockets. | |
197 | ||
198 | <P> | |
199 | </LI> | |
200 | <LI><tt class="class">DatagramHandler</tt> instances send error messages to UDP | |
201 | sockets. | |
202 | ||
203 | <P> | |
204 | </LI> | |
205 | <LI><tt class="class">SMTPHandler</tt> instances send error messages to a | |
206 | designated email address. | |
207 | ||
208 | <P> | |
209 | </LI> | |
210 | <LI><tt class="class">SysLogHandler</tt> instances send error messages to a | |
211 | <span class="Unix">Unix</span> syslog daemon, possibly on a remote machine. | |
212 | ||
213 | <P> | |
214 | </LI> | |
215 | <LI><tt class="class">NTEventLogHandler</tt> instances send error messages to a | |
216 | Windows NT/2000/XP event log. | |
217 | ||
218 | <P> | |
219 | </LI> | |
220 | <LI><tt class="class">MemoryHandler</tt> instances send error messages to a | |
221 | buffer in memory, which is flushed whenever specific criteria are | |
222 | met. | |
223 | ||
224 | <P> | |
225 | </LI> | |
226 | <LI><tt class="class">HTTPHandler</tt> instances send error messages to an | |
227 | HTTP server using either "<tt class="samp">GET</tt>" or "<tt class="samp">POST</tt>" semantics. | |
228 | ||
229 | <P> | |
230 | </LI> | |
231 | </OL> | |
232 | ||
233 | <P> | |
234 | The <tt class="class">StreamHandler</tt> and <tt class="class">FileHandler</tt> classes are defined | |
235 | in the core logging package. The other handlers are defined in a sub- | |
236 | module, <tt class="module">logging.handlers</tt>. (There is also another sub-module, | |
237 | <tt class="module">logging.config</tt>, for configuration functionality.) | |
238 | ||
239 | <P> | |
240 | Logged messages are formatted for presentation through instances of the | |
241 | <tt class="class">Formatter</tt> class. They are initialized with a format string | |
242 | suitable for use with the % operator and a dictionary. | |
243 | ||
244 | <P> | |
245 | For formatting multiple messages in a batch, instances of | |
246 | <tt class="class">BufferingFormatter</tt> can be used. In addition to the format string | |
247 | (which is applied to each message in the batch), there is provision for | |
248 | header and trailer format strings. | |
249 | ||
250 | <P> | |
251 | When filtering based on logger level and/or handler level is not enough, | |
252 | instances of <tt class="class">Filter</tt> can be added to both <tt class="class">Logger</tt> and | |
253 | <tt class="class">Handler</tt> instances (through their <tt class="method">addFilter()</tt> method). | |
254 | Before deciding to process a message further, both loggers and handlers | |
255 | consult all their filters for permission. If any filter returns a false | |
256 | value, the message is not processed further. | |
257 | ||
258 | <P> | |
259 | The basic <tt class="class">Filter</tt> functionality allows filtering by specific logger | |
260 | name. If this feature is used, messages sent to the named logger and its | |
261 | children are allowed through the filter, and all others dropped. | |
262 | ||
263 | <P> | |
264 | In addition to the classes described above, there are a number of module- | |
265 | level functions. | |
266 | ||
267 | <P> | |
268 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
269 | <td><nobr><b><tt id='l2h-2457' xml:id='l2h-2457' class="function">getLogger</tt></b>(</nobr></td> | |
270 | <td><var></var><big>[</big><var>name</var><big>]</big><var></var>)</td></tr></table></dt> | |
271 | <dd> | |
272 | Return a logger with the specified name or, if no name is specified, return | |
273 | a logger which is the root logger of the hierarchy. If specified, the name | |
274 | is typically a dot-separated hierarchical name like <var>"a"</var>, <var>"a.b"</var> | |
275 | or <var>"a.b.c.d"</var>. Choice of these names is entirely up to the developer | |
276 | who is using logging. | |
277 | ||
278 | <P> | |
279 | All calls to this function with a given name return the same logger instance. | |
280 | This means that logger instances never need to be passed between different | |
281 | parts of an application. | |
282 | </dl> | |
283 | ||
284 | <P> | |
285 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
286 | <td><nobr><b><tt id='l2h-2458' xml:id='l2h-2458' class="function">getLoggerClass</tt></b>(</nobr></td> | |
287 | <td><var></var>)</td></tr></table></dt> | |
288 | <dd> | |
289 | Return either the standard <tt class="class">Logger</tt> class, or the last class passed to | |
290 | <tt class="function">setLoggerClass()</tt>. This function may be called from within a new | |
291 | class definition, to ensure that installing a customised <tt class="class">Logger</tt> class | |
292 | will not undo customisations already applied by other code. For example: | |
293 | ||
294 | <P> | |
295 | <div class="verbatim"><pre> | |
296 | class MyLogger(logging.getLoggerClass()): | |
297 | # ... override behaviour here | |
298 | </pre></div> | |
299 | ||
300 | <P> | |
301 | </dl> | |
302 | ||
303 | <P> | |
304 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
305 | <td><nobr><b><tt id='l2h-2459' xml:id='l2h-2459' class="function">debug</tt></b>(</nobr></td> | |
306 | <td><var>msg</var><big>[</big><var>, *args</var><big>[</big><var>, **kwargs</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
307 | <dd> | |
308 | Logs a message with level <tt class="constant">DEBUG</tt> on the root logger. | |
309 | The <var>msg</var> is the message format string, and the <var>args</var> are the | |
310 | arguments which are merged into <var>msg</var>. The only keyword argument in | |
311 | <var>kwargs</var> which is inspected is <var>exc_info</var> which, if it does not | |
312 | evaluate as false, causes exception information to be added to the logging | |
313 | message. If an exception tuple (in the format returned by | |
314 | <tt class="function">sys.exc_info()</tt>) is provided, it is used; otherwise, | |
315 | <tt class="function">sys.exc_info()</tt> is called to get the exception information. | |
316 | </dl> | |
317 | ||
318 | <P> | |
319 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
320 | <td><nobr><b><tt id='l2h-2460' xml:id='l2h-2460' class="function">info</tt></b>(</nobr></td> | |
321 | <td><var>msg</var><big>[</big><var>, *args</var><big>[</big><var>, **kwargs</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
322 | <dd> | |
323 | Logs a message with level <tt class="constant">INFO</tt> on the root logger. | |
324 | The arguments are interpreted as for <tt class="function">debug()</tt>. | |
325 | </dl> | |
326 | ||
327 | <P> | |
328 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
329 | <td><nobr><b><tt id='l2h-2461' xml:id='l2h-2461' class="function">warning</tt></b>(</nobr></td> | |
330 | <td><var>msg</var><big>[</big><var>, *args</var><big>[</big><var>, **kwargs</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
331 | <dd> | |
332 | Logs a message with level <tt class="constant">WARNING</tt> on the root logger. | |
333 | The arguments are interpreted as for <tt class="function">debug()</tt>. | |
334 | </dl> | |
335 | ||
336 | <P> | |
337 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
338 | <td><nobr><b><tt id='l2h-2462' xml:id='l2h-2462' class="function">error</tt></b>(</nobr></td> | |
339 | <td><var>msg</var><big>[</big><var>, *args</var><big>[</big><var>, **kwargs</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
340 | <dd> | |
341 | Logs a message with level <tt class="constant">ERROR</tt> on the root logger. | |
342 | The arguments are interpreted as for <tt class="function">debug()</tt>. | |
343 | </dl> | |
344 | ||
345 | <P> | |
346 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
347 | <td><nobr><b><tt id='l2h-2463' xml:id='l2h-2463' class="function">critical</tt></b>(</nobr></td> | |
348 | <td><var>msg</var><big>[</big><var>, *args</var><big>[</big><var>, **kwargs</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
349 | <dd> | |
350 | Logs a message with level <tt class="constant">CRITICAL</tt> on the root logger. | |
351 | The arguments are interpreted as for <tt class="function">debug()</tt>. | |
352 | </dl> | |
353 | ||
354 | <P> | |
355 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
356 | <td><nobr><b><tt id='l2h-2464' xml:id='l2h-2464' class="function">exception</tt></b>(</nobr></td> | |
357 | <td><var>msg</var><big>[</big><var>, *args</var><big>]</big><var></var>)</td></tr></table></dt> | |
358 | <dd> | |
359 | Logs a message with level <tt class="constant">ERROR</tt> on the root logger. | |
360 | The arguments are interpreted as for <tt class="function">debug()</tt>. Exception info | |
361 | is added to the logging message. This function should only be called | |
362 | from an exception handler. | |
363 | </dl> | |
364 | ||
365 | <P> | |
366 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
367 | <td><nobr><b><tt id='l2h-2465' xml:id='l2h-2465' class="function">log</tt></b>(</nobr></td> | |
368 | <td><var>level, msg</var><big>[</big><var>, *args</var><big>[</big><var>, **kwargs</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
369 | <dd> | |
370 | Logs a message with level <var>level</var> on the root logger. | |
371 | The other arguments are interpreted as for <tt class="function">debug()</tt>. | |
372 | </dl> | |
373 | ||
374 | <P> | |
375 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
376 | <td><nobr><b><tt id='l2h-2466' xml:id='l2h-2466' class="function">disable</tt></b>(</nobr></td> | |
377 | <td><var>lvl</var>)</td></tr></table></dt> | |
378 | <dd> | |
379 | Provides an overriding level <var>lvl</var> for all loggers which takes | |
380 | precedence over the logger's own level. When the need arises to | |
381 | temporarily throttle logging output down across the whole application, | |
382 | this function can be useful. | |
383 | </dl> | |
384 | ||
385 | <P> | |
386 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
387 | <td><nobr><b><tt id='l2h-2467' xml:id='l2h-2467' class="function">addLevelName</tt></b>(</nobr></td> | |
388 | <td><var>lvl, levelName</var>)</td></tr></table></dt> | |
389 | <dd> | |
390 | Associates level <var>lvl</var> with text <var>levelName</var> in an internal | |
391 | dictionary, which is used to map numeric levels to a textual | |
392 | representation, for example when a <tt class="class">Formatter</tt> formats a message. | |
393 | This function can also be used to define your own levels. The only | |
394 | constraints are that all levels used must be registered using this | |
395 | function, levels should be positive integers and they should increase | |
396 | in increasing order of severity. | |
397 | </dl> | |
398 | ||
399 | <P> | |
400 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
401 | <td><nobr><b><tt id='l2h-2468' xml:id='l2h-2468' class="function">getLevelName</tt></b>(</nobr></td> | |
402 | <td><var>lvl</var>)</td></tr></table></dt> | |
403 | <dd> | |
404 | Returns the textual representation of logging level <var>lvl</var>. If the | |
405 | level is one of the predefined levels <tt class="constant">CRITICAL</tt>, | |
406 | <tt class="constant">ERROR</tt>, <tt class="constant">WARNING</tt>, <tt class="constant">INFO</tt> or <tt class="constant">DEBUG</tt> | |
407 | then you get the corresponding string. If you have associated levels | |
408 | with names using <tt class="function">addLevelName()</tt> then the name you have associated | |
409 | with <var>lvl</var> is returned. If a numeric value corresponding to one of the | |
410 | defined levels is passed in, the corresponding string representation is | |
411 | returned. Otherwise, the string "Level %s" % lvl is returned. | |
412 | </dl> | |
413 | ||
414 | <P> | |
415 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
416 | <td><nobr><b><tt id='l2h-2469' xml:id='l2h-2469' class="function">makeLogRecord</tt></b>(</nobr></td> | |
417 | <td><var>attrdict</var>)</td></tr></table></dt> | |
418 | <dd> | |
419 | Creates and returns a new <tt class="class">LogRecord</tt> instance whose attributes are | |
420 | defined by <var>attrdict</var>. This function is useful for taking a pickled | |
421 | <tt class="class">LogRecord</tt> attribute dictionary, sent over a socket, and reconstituting | |
422 | it as a <tt class="class">LogRecord</tt> instance at the receiving end. | |
423 | </dl> | |
424 | ||
425 | <P> | |
426 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
427 | <td><nobr><b><tt id='l2h-2470' xml:id='l2h-2470' class="function">basicConfig</tt></b>(</nobr></td> | |
428 | <td><var></var><big>[</big><var>**kwargs</var><big>]</big><var></var>)</td></tr></table></dt> | |
429 | <dd> | |
430 | Does basic configuration for the logging system by creating a | |
431 | <tt class="class">StreamHandler</tt> with a default <tt class="class">Formatter</tt> and adding it to | |
432 | the root logger. The functions <tt class="function">debug()</tt>, <tt class="function">info()</tt>, | |
433 | <tt class="function">warning()</tt>, <tt class="function">error()</tt> and <tt class="function">critical()</tt> will call | |
434 | <tt class="function">basicConfig()</tt> automatically if no handlers are defined for the | |
435 | root logger. | |
436 | ||
437 | <P> | |
438 | ||
439 | <span class="versionnote">Changed in version 2.4: | |
440 | Formerly, <tt class="function">basicConfig</tt> did not take any keyword | |
441 | arguments.</span> | |
442 | ||
443 | <P> | |
444 | The following keyword arguments are supported. | |
445 | ||
446 | <P> | |
447 | <div class="center"><table class="realtable"> | |
448 | <thead> | |
449 | <tr> | |
450 | <th class="left" >Format</th> | |
451 | <th class="left" >Description</th> | |
452 | </tr> | |
453 | </thead> | |
454 | <tbody> | |
455 | <tr><td class="left" valign="baseline"><code>filename</code></td> | |
456 | <td class="left" >Specifies that a FileHandler be created, using the | |
457 | specified filename, rather than a StreamHandler.</td></tr> | |
458 | <tr><td class="left" valign="baseline"><code>filemode</code></td> | |
459 | <td class="left" >Specifies the mode to open the file, if filename is | |
460 | specified (if filemode is unspecified, it defaults to 'a').</td></tr> | |
461 | <tr><td class="left" valign="baseline"><code>format</code></td> | |
462 | <td class="left" >Use the specified format string for the handler.</td></tr> | |
463 | <tr><td class="left" valign="baseline"><code>datefmt</code></td> | |
464 | <td class="left" >Use the specified date/time format.</td></tr> | |
465 | <tr><td class="left" valign="baseline"><code>level</code></td> | |
466 | <td class="left" >Set the root logger level to the specified level.</td></tr> | |
467 | <tr><td class="left" valign="baseline"><code>stream</code></td> | |
468 | <td class="left" >Use the specified stream to initialize the StreamHandler. | |
469 | Note that this argument is incompatible with 'filename' - if both | |
470 | are present, 'stream' is ignored.</td></tr></tbody> | |
471 | </table></div> | |
472 | ||
473 | <P> | |
474 | </dl> | |
475 | ||
476 | <P> | |
477 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
478 | <td><nobr><b><tt id='l2h-2471' xml:id='l2h-2471' class="function">shutdown</tt></b>(</nobr></td> | |
479 | <td><var></var>)</td></tr></table></dt> | |
480 | <dd> | |
481 | Informs the logging system to perform an orderly shutdown by flushing and | |
482 | closing all handlers. | |
483 | </dl> | |
484 | ||
485 | <P> | |
486 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
487 | <td><nobr><b><tt id='l2h-2472' xml:id='l2h-2472' class="function">setLoggerClass</tt></b>(</nobr></td> | |
488 | <td><var>klass</var>)</td></tr></table></dt> | |
489 | <dd> | |
490 | Tells the logging system to use the class <var>klass</var> when instantiating a | |
491 | logger. The class should define <tt class="method">__init__()</tt> such that only a name | |
492 | argument is required, and the <tt class="method">__init__()</tt> should call | |
493 | <tt class="method">Logger.__init__()</tt>. This function is typically called before any | |
494 | loggers are instantiated by applications which need to use custom logger | |
495 | behavior. | |
496 | </dl> | |
497 | ||
498 | <P> | |
499 | <div class="seealso"> | |
500 | <p class="heading">See Also:</p> | |
501 | ||
502 | <dl compact="compact" class="seerfc"> | |
503 | <dt><a href="http://www.python.org/peps/pep-0282.html" | |
504 | title="A Logging System" | |
505 | >PEP 282, <em>A Logging System</em></a> | |
506 | <dd>The proposal which described this feature for inclusion in | |
507 | the Python standard library. | |
508 | </dl> | |
509 | <dl compact="compact" class="seeurl"> | |
510 | <dt><a href='http://www.red-dove.com/python_logging.html' | |
511 | >Original Python <tt class="module">logging</tt> package</a></dt> | |
512 | <dd>This is the original source for the <tt class="module">logging</tt> | |
513 | package. The version of the package available from this | |
514 | site is suitable for use with Python 1.5.2, 2.1.x and 2.2.x, | |
515 | which do not include the <tt class="module">logging</tt> package in the standard | |
516 | library.</dd> | |
517 | </dl> | |
518 | </div> | |
519 | ||
520 | <P> | |
521 | ||
522 | <p><br /></p><hr class='online-navigation' /> | |
523 | <div class='online-navigation'> | |
524 | <!--Table of Child-Links--> | |
525 | <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a> | |
526 | ||
527 | <UL CLASS="ChildLinks"> | |
528 | <LI><A href="node341.html">6.29.1 Logger Objects</a> | |
529 | <LI><A href="minimal-example.html">6.29.2 Basic example</a> | |
530 | <LI><A href="multiple-destinations.html">6.29.3 Logging to multiple destinations</a> | |
531 | <LI><A href="network-logging.html">6.29.4 Sending and receiving logging events across a network</a> | |
532 | <LI><A href="node345.html">6.29.5 Handler Objects</a> | |
533 | <UL> | |
534 | <LI><A href="node346.html">6.29.5.1 StreamHandler</a> | |
535 | <LI><A href="node347.html">6.29.5.2 FileHandler</a> | |
536 | <LI><A href="node348.html">6.29.5.3 RotatingFileHandler</a> | |
537 | <LI><A href="node349.html">6.29.5.4 TimedRotatingFileHandler</a> | |
538 | <LI><A href="node350.html">6.29.5.5 SocketHandler</a> | |
539 | <LI><A href="node351.html">6.29.5.6 DatagramHandler</a> | |
540 | <LI><A href="node352.html">6.29.5.7 SysLogHandler</a> | |
541 | <LI><A href="node353.html">6.29.5.8 NTEventLogHandler</a> | |
542 | <LI><A href="node354.html">6.29.5.9 SMTPHandler</a> | |
543 | <LI><A href="node355.html">6.29.5.10 MemoryHandler</a> | |
544 | <LI><A href="node356.html">6.29.5.11 HTTPHandler</a> | |
545 | </ul> | |
546 | <LI><A href="node357.html">6.29.6 Formatter Objects</a> | |
547 | <LI><A href="node358.html">6.29.7 Filter Objects</a> | |
548 | <LI><A href="node359.html">6.29.8 LogRecord Objects</a> | |
549 | <LI><A href="node360.html">6.29.9 Thread Safety</a> | |
550 | <LI><A href="node361.html">6.29.10 Configuration</a> | |
551 | <UL> | |
552 | <LI><A href="logging-config-api.html">6.29.10.1 Configuration functions</a> | |
553 | <LI><A href="logging-config-fileformat.html">6.29.10.2 Configuration file format</a> | |
554 | </ul></ul> | |
555 | <!--End of Table of Child-Links--> | |
556 | </div> | |
557 | ||
558 | <DIV CLASS="navigation"> | |
559 | <div class='online-navigation'> | |
560 | <p></p><hr /> | |
561 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
562 | <tr> | |
563 | <td class='online-navigation'><a rel="prev" title="6.28.4 Acknowledgements" | |
564 | href="node339.html"><img src='../icons/previous.png' | |
565 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
566 | <td class='online-navigation'><a rel="parent" title="6. Generic Operating System" | |
567 | href="allos.html"><img src='../icons/up.png' | |
568 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
569 | <td class='online-navigation'><a rel="next" title="6.29.1 Logger Objects" | |
570 | href="node341.html"><img src='../icons/next.png' | |
571 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
572 | <td align="center" width="100%">Python Library Reference</td> | |
573 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
574 | href="contents.html"><img src='../icons/contents.png' | |
575 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
576 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
577 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
578 | <td class='online-navigation'><a rel="index" title="Index" | |
579 | href="genindex.html"><img src='../icons/index.png' | |
580 | border='0' height='32' alt='Index' width='32' /></A></td> | |
581 | </tr></table> | |
582 | <div class='online-navigation'> | |
583 | <b class="navlabel">Previous:</b> | |
584 | <a class="sectref" rel="prev" href="node339.html">6.28.4 Acknowledgements</A> | |
585 | <b class="navlabel">Up:</b> | |
586 | <a class="sectref" rel="parent" href="allos.html">6. Generic Operating System</A> | |
587 | <b class="navlabel">Next:</b> | |
588 | <a class="sectref" rel="next" href="node341.html">6.29.1 Logger Objects</A> | |
589 | </div> | |
590 | </div> | |
591 | <hr /> | |
592 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
593 | </DIV> | |
594 | <!--End of Navigation Panel--> | |
595 | <ADDRESS> | |
596 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
597 | </ADDRESS> | |
598 | </BODY> | |
599 | </HTML> |