[Python-Dev] Using logging in the stdlib and its unit tests (original) (raw)
Glenn Linderman v+python at g.nevcal.com
Wed Dec 8 18:51:44 CET 2010
- Previous message: [Python-Dev] Using logging in the stdlib and its unit tests
- Next message: [Python-Dev] Using logging in the stdlib and its unit tests
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
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>
- Previous message: [Python-Dev] Using logging in the stdlib and its unit tests
- Next message: [Python-Dev] Using logging in the stdlib and its unit tests
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]