[Python-Dev] Using logging in the stdlib and its unit tests
Glenn Linderman
v+python at g.nevcal.com
Wed Dec 8 18:51:44 CET 2010
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>
More information about the Python-Dev
mailing list