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

[Gregory P. Smith]

On Wed, Dec 8, 2010 at 9:51 AM, Glenn Linderman
<v+python at g.nevcal.com<v%2Bpython at g.nevcal.com>
> wrote:

>  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).
>

Exactly.  All I ever recommend people do is:

import logging
...
    logging.warn('doing something a bit odd.')
...
    for x in thing:
        logging.debug('working on %r', x)
...


And be done with it.  If they are controlling their __main__ they'll
probably want to call a common function to setup the log message formatting
and where it gets written to from there.  Otherwise ignore that and leave
that up to the person using your library (directly, indirectly or otherwise)
to do that in their __main__ code.

For logging to be useful it needs to be dirt simple.  The above is.

-gps
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20101209/06191ded/attachment.html>