python-peps/peps/pep-0337.rst

206 lines
4.9 KiB
ReStructuredText
Raw Normal View History

PEP: 337
Title: Logging Usage in the Standard Library
Version: $Revision$
Last-Modified: $Date$
Author: Michael P. Dubner <dubnerm@mindless.com>
Status: Deferred
Type: Standards Track
2017-01-24 15:47:22 -05:00
Content-Type: text/x-rst
Created: 02-Oct-2004
Python-Version: 2.5
Post-History: 10-Nov-2004
Abstract
2017-01-24 15:47:22 -05:00
========
This PEP defines a standard for using the logging system (:pep:`282`) in the
2017-01-24 15:47:22 -05:00
standard library.
2017-01-24 15:47:22 -05:00
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.
2017-01-24 15:47:22 -05:00
After implementing this PEP one can use following filtering
scheme::
logging.getLogger('py.BaseHTTPServer').setLevel(logging.FATAL)
PEP Deferral
2017-01-24 15:47:22 -05:00
============
2017-01-24 15:47:22 -05:00
Further exploration of the concepts covered in this PEP has been deferred
for lack of a current champion interested in promoting the goals of the
PEP and collecting and incorporating feedback, and with sufficient
available time to do so effectively.
Rationale
2017-01-24 15:47:22 -05:00
=========
2017-01-24 15:47:22 -05:00
There are a couple of situations when output to stdout or stderr
is impractical:
2017-01-24 15:47:22 -05:00
- 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+.
2017-01-24 15:47:22 -05:00
- GUI applications which want to output every new log entry in
separate pop-up window (i.e. fading OSD).
2017-01-24 15:47:22 -05:00
Also sometimes applications want to filter output entries based on
their source or severity. This requirement can't be implemented
using simple redirection.
2017-01-24 15:47:22 -05:00
Finally sometimes output needs to be marked with event timestamps,
which can be accomplished with ease using the logging system.
Proposal
2017-01-24 15:47:22 -05:00
========
Every module usable for daemon and GUI applications should be
rewritten to use the logging system instead of ``print`` or
``sys.stdout.write``.
2017-01-24 15:47:22 -05:00
There should be code like this included in the beginning of every
modified module::
2017-01-24 15:47:22 -05:00
import logging
2017-01-24 15:47:22 -05:00
_log = logging.getLogger('py.<module-name>')
2017-01-24 15:47:22 -05:00
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::
2017-01-24 15:47:22 -05:00
class XXX:
2017-01-24 15:47:22 -05:00
__log = logging.getLogger('py.<module-name>')
2017-01-24 15:47:22 -05:00
Then this class can create access methods to log to this private
logger.
2017-01-24 15:47:22 -05:00
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
2017-01-24 15:47:22 -05:00
===========
2017-01-24 15:47:22 -05:00
Here is a (possibly incomplete) list of modules to be reworked:
2017-01-24 15:47:22 -05:00
- asyncore (dispatcher.log, dispatcher.log_info)
2017-01-24 15:47:22 -05:00
- BaseHTTPServer (BaseHTTPRequestHandler.log_request,
BaseHTTPRequestHandler.log_error,
BaseHTTPRequestHandler.log_message)
2017-01-24 15:47:22 -05:00
- cgi (possibly - is cgi.log used by somebody?)
2017-01-24 15:47:22 -05:00
- ftplib (if FTP.debugging)
2017-01-24 15:47:22 -05:00
- gopherlib (get_directory)
2017-01-24 15:47:22 -05:00
- httplib (HTTPResponse, HTTPConnection)
2017-01-24 15:47:22 -05:00
- ihooks (_Verbose)
2017-01-24 15:47:22 -05:00
- imaplib (IMAP4._mesg)
2017-01-24 15:47:22 -05:00
- mhlib (MH.error)
2017-01-24 15:47:22 -05:00
- nntplib (NNTP)
2017-01-24 15:47:22 -05:00
- pipes (Template.makepipeline)
2017-01-24 15:47:22 -05:00
- pkgutil (extend_path)
2017-01-24 15:47:22 -05:00
- platform (_syscmd_ver)
2017-01-24 15:47:22 -05:00
- poplib (if POP3._debugging)
2017-01-24 15:47:22 -05:00
- profile (if Profile.verbose)
2017-01-24 15:47:22 -05:00
- robotparser (_debug)
2017-01-24 15:47:22 -05:00
- smtplib (if SGMLParser.verbose)
2017-01-24 15:47:22 -05:00
- shlex (if shlex.debug)
2017-01-24 15:47:22 -05:00
- smtpd (SMTPChannel/PureProxy where print >> DEBUGSTREAM)
2017-01-24 15:47:22 -05:00
- smtplib (if SMTP.debuglevel)
2017-01-24 15:47:22 -05:00
- SocketServer (BaseServer.handle_error)
2017-01-24 15:47:22 -05:00
- telnetlib (if Telnet.debuglevel)
2017-01-24 15:47:22 -05:00
- threading? (_Verbose._note, Thread.__bootstrap)
2017-01-24 15:47:22 -05:00
- timeit (Timer.print_exc)
2017-01-24 15:47:22 -05:00
- trace
2017-01-24 15:47:22 -05:00
- uu (decode)
2017-01-24 15:47:22 -05:00
Additionally there are a couple of modules with commented debug
output or modules where debug output should be added. For
example:
2017-01-24 15:47:22 -05:00
- urllib
2017-01-24 15:47:22 -05:00
Finally possibly some modules should be extended to provide more
debug information.
Doubtful Modules
2017-01-24 15:47:22 -05:00
================
2017-01-24 15:47:22 -05:00
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.
2017-01-24 15:47:22 -05:00
- tabnanny (check)
Guidelines for Logging Usage
2017-01-24 15:47:22 -05:00
============================
2017-01-24 15:47:22 -05:00
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
2017-01-24 15:47:22 -05:00
==========
2017-06-11 15:02:39 -04:00
.. [2] https://mail.python.org/pipermail/python-dev/2004-October/049282.html
Copyright
2017-01-24 15:47:22 -05:00
=========
This document has been placed in the public domain.
2017-01-24 15:47:22 -05:00
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End: