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

[Antoine Pitrou]

On Wed, 8 Dec 2010 01:19:45 +0000 (UTC)
Vinay Sajip <vinay_sajip at yahoo.co.uk> wrote:
> Antoine Pitrou <solipsis <at> pitrou.net> writes:
> 
> > 
> > Why wouldn't it be the default for all logging calls ? Such special
> > cases don't really make things easy to remember.
> >
> 
> One size doesn't fit all. Everything's documented reasonably well. If you use it
> often, you remember it. If you use it seldom, you might need to look things up.

My point is that the default behaviour should be helpful.

I would point out that logging is really the kind of thing people don't
want to spend time with. I know it's not very gratifying for the module
author (you!), but nobody expects (*) to have to first configure a
logging library when they want to use a third-party library. They
expect it to work *and* give useful error report by default.

(*) (not in the Python land anyway; Java might be different)

> The defaults are I believe reasonably convenient, or at least not inconvenient:
> 
> 1. If writing a library, add a NullHandler to the top-level logger of your
> library, don't add any other handlers by default (i.e. on import), document the
> names of the loggers you use. Otherwise, see the following.

First, you cannot call it a "default", since the library writer has to
make it explicit.
Second, I don't find that convenient at all. When I use a third-party
lib I want the errors to be displayed, not silenced. I'm willing to bet
that most people have the same expectation. *Especially* when
prototyping, since you're not sure you've got everything right.

So, that's two problems:
- the library author has to explicit activate what you argue is a
  "default" behaviour (otherwise the library user gets an unhelpful
  message that handlers are not configured)
- the library user still has to override that "default" since it's not
  satisfying for most uses

There's a third problem with it:
- all this is not easily discoverable. You cannot expect each user of a
  third-party lib to *also* read the logging docs in addition to the
  third-party lib docs. On my Web browser,
  http://docs.python.org/dev/library/logging.html seems to be at least
  50 pages long.

For a comparison, the warnings module logs all warnings by default on
stderr without requiring any a priori configuration. And that's what
stderr is for (reporting errors).

> 2. If writing a simple script, prototyping etc. i.e. for casual use, use
> logging.debug(), logging.info() etc. That's easy enough and convenient enough
> for casual users to remember, I hope. All WARNING, ERROR and CRITICAL events in
> your code and in that of any libraries you use will be printed to sys.stderr.

Indeed, this is convenient. And that's what I'm arguing should be the
default for *all* loggers, not just the top-level one. There's no
reason that what is convenient for the root logger isn't for other
loggers.

> 3. If slightly less than very casual use (e.g. you want to log to file, or want
> a specific message format), call basicConfig(). Just the one extra line to
> remember to do, hopefully not too inconvenient.

I know that one line sounds "not too inconvenient" since you are the
library author and you are so used to it (and certainly like using it
and spend a lot of time improving its features, which is good).
I think most people, however, have different expectations (see
beginning of this message).

> 4. For more advanced use, use programmatic configuration, fileConfig or
> dictConfig to specify a configuration. Convenience is inversely proportional to
> how involved the configuration is.

That I have already noticed :)

Regards

Antoine.