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