[Python-Dev] Some changes to logging

[Raymond Hettinger]

[Vinay Sajip]
> I've had feedback from numerous sources that the logging package is
harder
> to configure than it needs to be, for the common use case of a simple
> script
> which needs to log to a file. I propose to change the convenience
function
> basicConfig(), which is currently the one-shot convenience function
for
> simple scripts to use. 

There is no rush to jump straight to this solution.  I recommend kicking
the idea around for a while on comp.lang.python where there have been
several discussions.  Perhaps send notes to those who've shown an
interest in the module; otherwise, they may not be looking when the
discussion starts.

Also, the logging documentation needs an example section (early in the
docs) modeled after the one for unittests which comparable because the
unittest docs are equally voluminous and option intensive, and yet they
both are actually easy to use once you see what to do.  The goal for the
unittest example page was to cover enough knowledge to handle 90% of
most peoples needs and to get them started.  A single page of examples
was all it took to flatten a vertical learning curve.

If you make an example page, posting it to a wiki or to comp.lang.python
is likely to result in feedback that will improve it more than just
directly updating CVS and waiting forever <wink> for the Py2.4 release.



> def basicConfig(**kwargs):
>     """
>     Do basic configuration for the logging system.
> 
>     This function does nothing if the root logger already has handlers
>     configured. It is a convenience method intended for use by simple
> scripts
>     to do one-shot configuration of the logging package.
> 
>     The default behaviour is to create a StreamHandler which writes to
>     sys.stderr, set a formatter using the BASIC_FORMAT format string,
and
>     add the handler to the root logger.
> 
>     A number of optional keyword arguments may be specified, which can
> alter
>     the default behaviour.
> 
>     filename  Specifies that a FileHandler be created, using the
specified
>               filename, rather than a StreamHandler.
>     filemode  Specifies the mode to open the file, if filename is
> specified
>               (if filemode is unspecified, it defaults to "a").
>     format    Use the specified format string for the handler.
>     level     Set the root logger level to the specified level.
>     stream    Use the specified stream to initialize the
StreamHandler.
> Note
>               that this argument is incompatible with 'filename' - if
both
>               are present, 'stream' is ignored.
> 
>     Note that you could specify a stream created using open(filename,
> mode)
>     rather than passing the filename and mode in. However, it should
be
>     remembered that StreamHandler does not close its stream (since it
may
> be
>     using sys.stdout or sys.stderr), whereas FileHandler closes its
stream
>     when the handler is closed.
>     """

This proposed function is much more complicated than what was requested.
While it does compress multiple lines into a single call, I think it
does not achieve simplification. 

I suggest leaving out some options and/or splitting some of those that
remain into separate functions.  Also, consider changing to name to
something active instead of configuration related.  The idea is making
something like the following possible:

>>> startfilelog(sys.stderr)
>>> log('danger will robinson; radiation levels not safe for humans')

>>> startstreamlog()
>>> log('mission accomplished; returning to base')

I can see the utility of having an optional format argument, but it
immediately raises the question of how to specify the format.  Perhaps
the docstring should say what the default is and give a couple of
alternatives:

   format defaults to:
         "%(levelname)s:%(name)s:%(message)s"
   other format options include:  
         "%(lineno)d"
         "%(asctime)s"
	   "%(thread)d"

Note, this style of docstring tells you most of what you need to know.
The previous style requires that you've read about Formatter objects,
remember all the codes, and know what the BASIC_FORMAT default is.  Of
course, all of us know this by heart, but there may be one or two users
who don't ;-)

For similar reasons, consider removing anything from the docstring that
implies a detailed understanding of the whole logging class structure
(i.e. the references to FileHandler, StreamHandler, root logger, etc).
The idea is that you shouldn't need cooking lessons before being able to
order a pizza. 



Raymond


#################################################################
#################################################################
#################################################################
#####
#####
#####
#################################################################
#################################################################
#################################################################