[docs] [issue17075] logging documentation for library cleanup

[Aaron Sherman]

New submission from Aaron Sherman:

This documentation states that libraries can turn off logging by adding a NullHandler:

http://docs.python.org/2/howto/logging.html#configuring-logging-for-a-library

This is not entirely true. It only holds true if the application which calls the library has not called basicConfig on the root logger. If it has, you get logs to both the root logger and the NullLogger, defeating the point of having added a NullLogger in the first place.

The correct way for a library to silence log messages is to both set a NullHandler and set propagate to false.

For an example of the behavior on the current docs, see:

  import logging
  import sys
  # Application configures its root logger
  logging.basicConfig(level=logging.DEBUG)
  
  # Library configures a NullLogger:
  logger = logging.getLogger('foo')
  logger.setLevel(logging.DEBUG)
  handler = logging.NullHandler()
  handler.setLevel(logging.DEBUG)
  logger.addHandler(handler)
  
  # Library then logs:
  logger.warning("BLAH")

This example is not terribly interesting, but the more interesting example is when the library configures a real log handler (e.g. in order to create a separate security log in an authorization module). In this case, the log messages will be sent to both the file log and the root logger by default, as long as any part of the application has configured the root logger.

IMHO, propagate should always be False for all new loggers, but at the very least the fact that it is True should be documented in the section on library logging...

----------
assignee: docs at python
components: Documentation
messages: 180919
nosy: ajs, docs at python
priority: normal
severity: normal
status: open
title: logging documentation for library cleanup
type: behavior
versions: Python 2.7

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue17075>
_______________________________________