[Python-Dev] Using logging in the stdlib and its unit tests

[Glenn Linderman]

On 12/8/2010 4:15 AM, Vinay Sajip wrote:
> You're complaining about too much documentation?! Don't measure it by weight!
On 12/8/2010 5:57 AM, Vinay Sajip wrote:
> Of course I understand I could be wrong
> about this, but I don't recall when a stdlib maintainer has said to me, "I want
> to start using logging in stdlib module XXX, but can't justify it because ..."

So I'm a fairly new Python user, but 30 years programming experience.

When I first looked at the Python logging facility (and again today, 
when I looked again), I found a simple example of debugging logging.  
Then a bunch of stuff about how to configure rotating logs.  Then 
something about logging levels. And then a dissertation on the theory of 
loggers "The logging library takes a modular approach and offers the 
several categories of components: loggers, handlers, filters, and 
formatters."  And I hadn't gotten through 10% of the documentation yet, 
per the scrollbar.

My reaction the first time was "Sounds sophisticated and complex.  I 
think I'll do something simpler for now, and maybe someday, when I have 
a spare week, I'll read the documentation and see if the benefits are 
worth the effort."

OK, so now you've discovered that too much documentation can be a turn 
off... at least, if it is presented from the top to describe the 
sophistication of the facility, rather than how easy it is to use (if it 
is, I still haven't gotten to 10%, and I still don't know that).

 From this thread, it sounds like it might be that logging could be easy 
to use.  Although part of my turn off from too much documentation and 
sophistication is a concern about the overhead of reading in and 
compiling a module that is that sophisticated for simple programs.

Now if I was convinced that

(1) it always gets read in anyway as part of Python startup (8% of the 
documentation didn't say that), so that no matter how simple my 
alternate facility, I pay the cost of loading the logger anyway, and

(2) that it would take less than a week to comprehend the basics of what 
I need to learn to use it, (in other words, if the 8% of the 
documentation I've read, actually gave sufficient simple examples to use 
applications and libraries, and left the sohistication and complexity 
and theory to later sections)

then I might have used the logger, instead of writing, in my personal 
library of "useful functions":

_logfh = sys.stderr
def log( text=None, textpre=None, filename=None, mode=None
          ):  # version 2010/11/11
     global _logfh
     if filename is not None:
         if mode is None:
             mode = "a"
         _logfh = open( filename, mode, **_wenc )
     if text is not None:
         if textpre is None:
             _logfh.write( str( text ) + "\n")
         else:
             _logfh.write( str( textpre ) + ": " + str( text ) + "\n")
     _logfh.flush()
     return _logfh


You see, I can create that faster than I read 8% of the documentation 
for logger, which didn't convince me that using the logger was better 
than the above, and it has been working fine... and I can tweak it when 
and if I need more sophistication.  I'm well aware that my function 
provides much less than what logger provides.  But in the first 8% of 
the documentation, I hadn't learned how to be able to use logging from a 
multiple module program in an easy and consistent manner...

The example shows a 4 line cost... it is not clear from the first 8% of 
the documentation if it requires 4 lines in every module; it is not 
clear if I can or should or if by default, the file I configure for one 
module is available to other modules, such that only two lines are 
necessary in those modules (import, logging.debug (or other levels of 
message)), etc.  And I'd have to read more than 8% of the documentation 
to find that out.

Now I'm not saying that I only read 8% of the documentation for modules 
that I want to use, in general, before I give up in disgust.  But I 
start reading, and estimate the cost of learning vs the cost of 
rewriting as I go.  logger documentation is large, so reading it all 
before starting to use it is unlikely; since the first part didn't get 
me started soon enough, I "put it on a shelf", where it still is.

If the first part had shown an example of how to use logger, in simple 
mode, in a trivial but multi-module application (because most trivial 
application do involve multiple modules, even if only one is 
user-written), then as I went along, I'd have likely learned more about 
the features as needed.  There are lots of interesting sounding features 
in the Table of Contents.  "Someday" I might decide to spend the week to 
read about them.

Hope this perspective helps, somehow.

Glenn

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20101208/ac576592/attachment.html>