[Python-Dev] Some changes to logging (original) (raw)

Raymond Hettinger python at rcn.com
Sun Mar 28 01:20:05 EST 2004

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

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

More information about the Python-Dev mailing list