191 lines
4.9 KiB
Plaintext
191 lines
4.9 KiB
Plaintext
PEP: 337
|
||
Title: Logging Usage in the Standard Library
|
||
Version: $Revision$
|
||
Last-Modified: $Date$
|
||
Author: Michael P. Dubner <dubnerm@mindless.com>
|
||
Status: Draft
|
||
Type: Standards Track
|
||
Content-Type: text/plain
|
||
Created: 02-Oct-2004
|
||
Python-Version: 2.5
|
||
Post-History: 10-Nov-2004
|
||
|
||
|
||
Abstract
|
||
|
||
This PEP defines a standard for using the logging system (PEP 282
|
||
[1]) in the standard library.
|
||
|
||
Implementing this PEP will simplify development of daemon
|
||
applications. As a downside this PEP requires slight
|
||
modifications (however in a back-portable way) to a large number
|
||
of standard modules.
|
||
|
||
After implementing this PEP one can use following filtering
|
||
scheme:
|
||
|
||
logging.getLogger('py.BaseHTTPServer').setLevel(logging.FATAL)
|
||
|
||
|
||
Rationale
|
||
|
||
There are a couple of situations when output to stdout or stderr
|
||
is impractical:
|
||
|
||
- Daemon applications where the framework doesn't allow the
|
||
redirection of standard output to some file, but assumes use of
|
||
some other form of logging. Examples are syslog under *nix'es
|
||
and EventLog under WinNT+.
|
||
|
||
- GUI applications which want to output every new log entry in
|
||
separate pop-up window (i.e. fading OSD).
|
||
|
||
Also sometimes applications want to filter output entries based on
|
||
their source or severity. This requirement can't be implemented
|
||
using simple redirection.
|
||
|
||
Finally sometimes output needs to be marked with event timestamps,
|
||
which can be accomplished with ease using the logging system.
|
||
|
||
|
||
Proposal
|
||
|
||
Every module usable for daemon and GUI applications should be
|
||
rewritten to use the logging system instead of 'print' or
|
||
'sys.stdout.write'.
|
||
|
||
There should be code like this included in the beginning of every
|
||
modified module:
|
||
|
||
import logging
|
||
|
||
_log = logging.getLogger('py.<module-name>')
|
||
|
||
A prefix of 'py.' [2] must be used by all modules included in the
|
||
standard library distributed along with Python, and only by such
|
||
modules (unverifiable). The use of "_log" is intentional as we
|
||
don't want to auto-export it. For modules that use log only in
|
||
one class a logger can be created inside the class definition as
|
||
follows:
|
||
|
||
class XXX:
|
||
|
||
__log = logging.getLogger('py.<module-name>')
|
||
|
||
Then this class can create access methods to log to this private
|
||
logger.
|
||
|
||
So "print" and "sys.std{out|err}.write" statements should be
|
||
replaced with "_log.{debug|info}", and "traceback.print_exception"
|
||
with "_log.exception" or sometimes "_log.debug('...', exc_info=1)".
|
||
|
||
|
||
Module List
|
||
|
||
Here is a (possibly incomplete) list of modules to be reworked:
|
||
|
||
- asyncore (dispatcher.log, dispatcher.log_info)
|
||
|
||
- BaseHTTPServer (BaseHTTPRequestHandler.log_request,
|
||
BaseHTTPRequestHandler.log_error,
|
||
BaseHTTPRequestHandler.log_message)
|
||
|
||
- cgi (possibly - is cgi.log used by somebody?)
|
||
|
||
- ftplib (if FTP.debugging)
|
||
|
||
- gopherlib (get_directory)
|
||
|
||
- httplib (HTTPResponse, HTTPConnection)
|
||
|
||
- ihooks (_Verbose)
|
||
|
||
- imaplib (IMAP4._mesg)
|
||
|
||
- mhlib (MH.error)
|
||
|
||
- nntplib (NNTP)
|
||
|
||
- pipes (Template.makepipeline)
|
||
|
||
- pkgutil (extend_path)
|
||
|
||
- platform (_syscmd_ver)
|
||
|
||
- poplib (if POP3._debugging)
|
||
|
||
- profile (if Profile.verbose)
|
||
|
||
- robotparser (_debug)
|
||
|
||
- smtplib (if SGMLParser.verbose)
|
||
|
||
- shlex (if shlex.debug)
|
||
|
||
- smtpd (SMTPChannel/PureProxy where print >> DEBUGSTREAM)
|
||
|
||
- smtplib (if SMTP.debuglevel)
|
||
|
||
- SocketServer (BaseServer.handle_error)
|
||
|
||
- telnetlib (if Telnet.debuglevel)
|
||
|
||
- threading? (_Verbose._note, Thread.__bootstrap)
|
||
|
||
- timeit (Timer.print_exc)
|
||
|
||
- trace
|
||
|
||
- uu (decode)
|
||
|
||
Additionally there are a couple of modules with commented debug
|
||
output or modules where debug output should be added. For
|
||
example:
|
||
|
||
- urllib
|
||
|
||
Finally possibly some modules should be extended to provide more
|
||
debug information.
|
||
|
||
|
||
Doubtful Modules
|
||
|
||
Listed here are modules that the community will propose for
|
||
addition to the module list and modules that the community say
|
||
should be removed from the module list.
|
||
|
||
- tabnanny (check)
|
||
|
||
|
||
Guidelines for Logging Usage
|
||
|
||
Also we can provide some recommendation to authors of library
|
||
modules so they all follow the same format of naming loggers. I
|
||
propose that non-standard library modules should use loggers named
|
||
after their full names, so a module "spam" in sub-package "junk"
|
||
of package "dummy" will be named "dummy.junk.spam" and, of course,
|
||
the "__init__" module of the same sub-package will have the logger
|
||
name "dummy.junk".
|
||
|
||
|
||
References
|
||
|
||
[1] PEP 282, A Logging System, Vinay Sajip, Trent Mick
|
||
http://www.python.org/dev/peps/pep-0282/
|
||
|
||
[2] http://mail.python.org/pipermail/python-dev/2004-October/049282.html
|
||
|
||
|
||
Copyright
|
||
|
||
This document has been placed in the public domain.
|
||
|
||
|
||
|
||
Local Variables:
|
||
mode: indented-text
|
||
indent-tabs-mode: nil
|
||
sentence-end-double-space: t
|
||
fill-column: 70
|
||
End:
|