Hello, I beg your pardon in advance for my English, which isn't my native language. I'm posting PEProposal for discussion. Last part is reasoning for posting it in this hot time. I'm ready to implement it all by myself... :-) -- Best regards, Michael Dubner (dubnerm@mindless.com) Brainbench MVP/HTML+JavaScript (http://www.brainbench.com) PS: Sorry for my English PEP: XXX Title: Guidelines for Logging Usage 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: Abstract This PEP defines guidelines for using logging system (PEP 282 [1]) in standard library. Implementing this PEP will simplify development of daemon applications. As a downside this PEP requires to slightly modify (however in backportable way) large number of standard modules. After implementing this PEP one can use following filtering scheme:: logging.getLogger('stdlib.BaseHTTPServer').setLevel(logging.FATAL) Rationale There are couple of situations when output to stdout or stderr is very incomfortable. - Daemon application where framework doesn't allows to redirect standard output to some file, but assumes use of some other way of logging. Examples are syslog under *nix'es and EventLog under WinNT+. - GUI application which want to output every new log entry in separate popup window (i.e. fading OSD). Also sometimes application want to filter output enties based on it's source or severity. This requirement can't be implemented using simple redirection. At last sometimes output need to be marked with time of event, which can be acqured with logging system with ease. Proposal Every module usable for daemon and GUI applications should be rewritten to use 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('stdlib.<module-name>') Prefix of 'stdlib.' must be used by all modules included in standard library distributed along with Python, and only by such modules (unverifiable). Using of "_log" is intentional as we don't want to auto-export it. For modules that using log only in one class logger can be created inside class definition as following:: class XXX: __log = logging.getLogger('stdlib.<module-name>') Then this class can create access methods to log to this private logger. So print's and "sys.std{out|err}.write" 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 (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) Additionaly there are couple of modules with commented debug output or modules where debug output should be added. For example: - urllib At last possibly some modules should be extended to provide more debug information. Doubtful Modules Here should be placed modules that community will propose for addition to module list and modules that community say should be removed from module list. - tabnanny (check) Guidelines for Logging Usage Also we can provide some recommendation to authors of library modules so they all follow same format of naming loggers. I propose that non-standard library modules should use logger named after their full names, so module "spam" in sub-package "junk" of package "dummy" will be named "dummy.junk.spam" and, of cause, "__init__" module of same package will have logger "dummy.junk". Implementation Schedule Proposal As one can see whole bunch of changes required to fullfil this proposal is rather large. I propose to delay these changes until after 2.4 release, and change only modules critical for server applications: - BaseHTTPServer - ftplib - httplib - poplib - smtpd - smtplib - SocketServer This can be done rather fast and reliable. References [1] PEP 282, A Logging System, Vinay Sajip, Trent Mick http://www.python.org/peps/pep-0282.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:
On Tue, Oct 05, 2004 at 01:44:58AM +0400, Michael P. Dubner wrote:
I'm posting PEProposal for discussion. Last part is reasoning for posting it in this hot time.
I like this proposal; it begins to impose some degree of sanity on the standard library. (If you want editing help with the grammar and text of the PEP, let me know; I'll happily polish the wording.)
logging.getLogger('stdlib.BaseHTTPServer').setLevel(logging.FATAL)
There's been discussion in the past of having a name for the Python standard library, so that 'from <name> import httplib' would always get the standard httplib module. This name should match whatever's using in the logging, so the logging should use a name everyone is happy with using in import statements. Whether that's stdlib or std or __std__ or Lib isn't important, as long as the logging matches. PEP 8 should also gain some text encouraging the use of the logging module in code and describing the dummy.junk convention. --amk
On Wed, 2004-10-06 at 15:57, A.M. Kuchling wrote:
There's been discussion in the past of having a name for the Python standard library, so that 'from <name> import httplib' would always get the standard httplib module. This name should match whatever's using in the logging, so the logging should use a name everyone is happy with using in import statements. Whether that's stdlib or std or __std__ or Lib isn't important, as long as the logging matches.
+1 -Barry
PEP 8 should also gain some text encouraging the use of the logging module in code and describing the dummy.junk convention.
Index: pep-0008.txt =================================================================== RCS file: /cvsroot/python/python/nondist/peps/pep-0008.txt,v retrieving revision 1.25 diff -c -r1.25 pep-0008.txt *** pep-0008.txt 6 Aug 2004 18:47:26 -0000 1.25 --- pep-0008.txt 7 Oct 2004 02:07:02 -0000 *************** *** 600,605 **** --- 600,608 ---- No: if greeting == True: Yes: if greeting: + - Use the print statement only where the user's objective is + to print. Use the logging method to deliver status information + to users on the fly. For more information, see PEP xxxx [6]. References *************** *** 614,619 **** --- 617,624 ---- [5] Barry's GNU Mailman style guide http://barry.warsaw.us/software/STYLEGUIDE.txt + [6] PEP xxxx, Guidelines for Logging Usage + Copyright
A.M. Kuchling wrote:
I like this proposal; it begins to impose some degree of sanity on the standard library.
I was the reason behind this PEP. :-)
(If you want editing help with the grammar and text of the PEP, let me know; I'll happily polish the wording.)
I will be happy to get such help. I haven't grammar checker handy, so as I recall I've only checked spelling once (and possibly not last edition). Sorry to native English speakers.
logging.getLogger('stdlib.BaseHTTPServer').setLevel(logging.FATAL)
There's been discussion in the past of having a name for the Python standard library, so that 'from <name> import httplib' would always get the standard httplib module. This name should match whatever's using in the logging, so the logging should use a name everyone is happy with using in import statements. Whether that's stdlib or std or __std__ or Lib isn't important, as long as the logging matches.
I'm not really sure that these names MUST be equal. Name to use for import statement can be __stdlib__ or ever __python_library__ to ensure uniqueness and specific name MUST draw attention to this place. But for logger name this prefix should be as short as possible because it's to be displayed, and sometime logger plus time, level and message text must fit 80 character line... -- Best regards, Michael Dubner (dubnerm.at.mindless.com) Brainbench MVP/HTML+JavaScript (http://www.brainbench.com) PS: Sorry for my English
Quoting "Michael P. Dubner" <dubnerm-news@mail.ru>:
There's been discussion in the past of having a name for the Python standard library, so that 'from <name> import httplib' would always get the standard httplib module. This name should match whatever's using in the logging, so the logging should use a name everyone is happy with using in import statements. Whether that's stdlib or std or __std__ or Lib isn't important, as long as the logging matches.
I'm not really sure that these names MUST be equal. Name to use for import statement can be __stdlib__ or ever __python_library__ to ensure uniqueness and specific name MUST draw attention to this place. But for logger name this prefix should be as short as possible because it's to be displayed, and sometime logger plus time, level and message text must fit 80 character line...
I agree with Andrew that the names should be equal - consistency is good, and brevity is a benefit for 'from x import' as well. I'd propose taking a tip from Java and using "py." as the prefix for the stdlib. Short, to the point, and I'd be surprised if anyone was using a bare "py" as a package or module name. Cheers, Nick. -- Nick Coghlan Brisbane, Australia
Nick Coghlan wrote:
I agree with Andrew that the names should be equal - consistency is good, and brevity is a benefit for 'from x import' as well.
I'd propose taking a tip from Java and using "py." as the prefix for the stdlib. Short, to the point, and I'd be surprised if anyone was using a bare "py" as a package or module name.
+1 -- Best regards, Michael Dubner (dubnerm.at.mindless.com) Brainbench MVP/HTML+JavaScript (http://www.brainbench.com) PS: Sorry for my English
On Friday 08 October 2004 08:04 pm, Nick Coghlan wrote:
I agree with Andrew that the names should be equal - consistency is good, and brevity is a benefit for 'from x import' as well.
Yes, and yes.
I'd propose taking a tip from Java and using "py." as the prefix for the stdlib. Short, to the point, and I'd be surprised if anyone was using a bare "py" as a package or module name.
Works for me! +1. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org>
Nick Coghlan wrote:
I'd propose taking a tip from Java and using "py." as the prefix for the stdlib. Short, to the point, and I'd be surprised if anyone was using a bare "py" as a package or module name.
Well, there's Py, née PyCrust, but it's now buried under the main wxPython package.
from wx import py
http://www.wxpython.org/py.php -- Robert Kern rkern@ucsd.edu "In the fields of hell where the grass grows high Are the graves of dreams allowed to die." -- Richard Harter
participants (7)
-
A.M. Kuchling -
Barry Warsaw -
Fred L. Drake, Jr. -
Garth T Kidd -
Michael P. Dubner -
Nick Coghlan -
Robert Kern