Abstract

This PEP defines a standard for using the logging system (PEP 282) in thestandard library.

Implementing this PEP will simplify development of daemonapplications. As a downside this PEP requires slightmodifications (however in a back-portable way) to a large numberof standard modules.

After implementing this PEP one can use following filteringscheme:

logging.getLogger('py.BaseHTTPServer').setLevel(logging.FATAL)

PEP Deferral

Further exploration of the concepts covered in this PEP has been deferredfor lack of a current champion interested in promoting the goals of thePEP and collecting and incorporating feedback, and with sufficientavailable time to do so effectively.

Rationale

There are a couple of situations when output to stdout or stderris impractical:

• Daemon applications where the framework doesn’t allow theredirection of standard output to some file, but assumes use ofsome other form of logging. Examples are syslog under *nix’esand EventLog under WinNT+.
• GUI applications which want to output every new log entry inseparate pop-up window (i.e. fading OSD).

Also sometimes applications want to filter output entries based ontheir source or severity. This requirement can’t be implementedusing 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 berewritten to use the logging system instead ofprint orsys.stdout.write.

There should be code like this included in the beginning of everymodified module:

importlogging_log=logging.getLogger('py.<module-name>')

A prefix ofpy.[2] must be used by all modules included in thestandard library distributed along with Python, and only by suchmodules (unverifiable). The use of_log is intentional as wedon’t want to auto-export it. For modules that use log only inone class a logger can be created inside the class definition asfollows:

classXXX:__log=logging.getLogger('py.<module-name>')

Then this class can create access methods to log to this privatelogger.

Soprint andsys.std{out|err}.write statements should bereplaced with_log.{debug|info}, andtraceback.print_exceptionwith_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 debugoutput or modules where debug output should be added. Forexample:

• urllib

Finally possibly some modules should be extended to provide moredebug information.

Doubtful Modules

Listed here are modules that the community will propose foraddition to the module list and modules that the community sayshould be removed from the module list.

• tabnanny (check)

Guidelines for Logging Usage

Also we can provide some recommendation to authors of librarymodules so they all follow the same format of naming loggers. Ipropose that non-standard library modules should use loggers namedafter 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 loggername “dummy.junk”.

References

Copyright

This document has been placed in the public domain.