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

[Vinay Sajip]

Antoine Pitrou <solipsis <at> pitrou.net> writes:

> 
> My point is that the default behaviour should be helpful.
>

I can't disagree with that. Now if only we could agree what we mean by "default"
and "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's just a tool - I completely understand that it's just an adjunct to the
interesting stuff. Doesn't bother me a bit :-)

> 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 Java thing is a red herring, I believe. It's more akin to the Unix idea of
minimum verbosity as a default. In general, you don't need to "configure a
library" except when you want specific behaviour from that library's loggers.

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

See my comments to Nick Coghlan's post about getting messages out when you can't
raise an exception. I think the case is not as common as you suggest (because in
many instances, you would raise an exception to signal an error).

I'm not opposed to changing the way things work, but I think we need more of a
consensus because some backwards incompatibility will result, albeit not likely
to affect too many users of logging.

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

You're complaining about too much documentation?! Don't measure it by weight!
Seriously, I don't see what's wrong with a library developer reading the
documentation for any module they're using, logging included. "Configuring
logging for a library" is easily visible in the sidebar on that page. So I
wouldn't agree that "it's not easily discoverable". It's not exactly buried. And
it's the library developer who has to read it, not the user of the library. The
user of the library only needs to know what logger names are used by that
library, and that too only if they want to configure those loggers.

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

But that behaviour is *not* always wanted. That's why I was asked to add
warnings integration to logging - to redirect warning messages to logging.
Things are seldom as black and white as you're making them out to be here.

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

Loggers work in a hierarchy, and the package is specifically designed so that
you can attach handlers just to the root logger, and get messages from all code
in your application + its libraries to destinations that you configure there.
This is not special case behaviour for root logger versus other loggers - it's
just that the root logger is a convenient, logical place to attach handlers.

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

Hey, that's not why I think "not too inconvenient"! It's because

(a) It's no less inconvenient than "import foo", and it's hard to argue that one
line is really inconvenient for this case - remember, for the simplest uses you
can omit the basicConfig() call, since you can use logging.info() etc.

(b) For this case, since there's no telepathy in this world, you need some way
for the programmer to communicate their intent about the logging level, or
format string, or log file that they want to use. I stand by the statement that
one line (or more precisely, one function call) is not too much to ask here, so
yes - "not too inconvenient". That's emphatically not because I'm the module's
author and "used to it".

Regards,

Vinay Sajip