improvements for the logging package

[Trent Mick]

[skip at pobox.com wrote]
> Perhaps so, but the logging module seems like such an unpythonic beast to
> me.  How about cleaning it up (*) before we add more to it?

Yes. I was also trying to encourage Rotem to get involved in other parts
of the logging module/package later on in my email. :)

> Stuff like colorizing seems like it belongs in its own module
> (presuming a reasonably general markup scheme can be agreed upon) so
> it can be used outside the logging package.

Yah, you are probably right. Most additions to the logging system could
easily live as their own separate pieces.

> (*) Stuff that seems very odd to me:
> 
>     - It's a package, but contrary to any other package I've ever seen, most
>       of its functionality is implemented in __init__.py.  __init__.py is
>       roughly four times larger than the next largest (bsddb, which is a
>       beast because BerkDB has gotten so big over the years and the
>       module/package has strived to remain backwards-compatible).

I'm not defending the implementation, but does this cause any particular
problems?


>       The obvious 'hello world' example
> 
>         import logging
>         logging.info('hello world')
> 
>       ought to just work (implicitly add a stream handler connected to
>       stderr to the root logger).

Maybe. Unless that causes troubles for real use. Having lazy
configuration like this means that it can be a subtle thing for
top-level application code to setup the proper logging configuration.

I cringe a little bit when I see this presented as the "hello world"
example. My basic hello world tends to be:

    import logging
    log = logging.getLogger("name-of-my-module-or-script")

    # use log.{debug|info|warn|error}() in module/script...
    #...

    if __name__ == "__main__":
        logging.basicConfig()
        #...
        
and then I wish again that the default output were a bit nicer for my
most common usage -- which is logging to the command line in scripts --
rather than looking more like to web server error/access logs.

I think the usability of the logging module could be much improved with
a nicer introduction to it (i.e. docs). It's not really a "hello world"
type of tool. Its usefulness only really shows in larger use cases.


>     - Its functionality is partitioned in sometimes odd ways.  For example,
>       it has a handlers module, but what I presume would be the most
>       commonly used handler (StreamHandler) is not defined there.  It's in
>       (you have three guesses and the first two don't count) __init__.py
>       instead of in logging.handlers.  Consequently, browsing in the obvious
>       way fails to find the StreamHandler class.
>
>     - It doesn't use PEP 8 style as far as naming is concerned, instead
>       doing some sort of Java or C++ or Perl camelCase thing.  Eschewing PEP
>       8 is fine for other stuff, but code in the Python core (especially new
>       code like the logging module) should strive to adhere to PEP 8, since
>       many people will use the core code as a pattern for their own code.

Perhaps Vijay (who did all the implementation) can comment on these.
Unfortunately backwards-compat might restrict some cleanups to the
package, but perhaps not too much. I did a poor job of keeping up with
the package after I laid out an initial design, er copied an initial
design from Java's log4j package (and I'm not even a Java guy). :(

Trent

-- 
Trent Mick
TrentM at ActiveState.com