How should logging be used in a Python package?

Question

I am currently developing a package which can be used without writing any new code and the modules can be used to develop new code (see documentation).

Many of my modules use logging in a very simple way:

import logging import sys logging.basicConfig(format='%(asctime)s %(levelname)s %(message)s',                     level=logging.DEBUG,                     stream=sys.stdout) # Code of the module follows 

I have these lines in many modules. It seems to me that I should factor it out, but I am not sure what the best / recommended / most pythonic way to do so is.

The relevant parts in the logging documentation seem to be Configuring Logging for a Library and Logging from multiple modules.

I guess I should simply move the line logging.basicConfig to the executables (bin/hwrt) and remove all other logging.basicConfig lines.

Is there any rule how packages should use logging (like PEP8 for coding style)?

If other developers use my code they might want to disable / modify the way my package does logging (so that it doesn't get mixed with their logging calls). Is there a way to help them do so?

Answer 1

Your library should not configure logging; that's an application-wide task.

Instead, just set up your logger object based on __name__, use that, and that's it. Document that you use logging, and developers using your library can use the standard logging API to configure logging.

You could add a null handler to your root logger (the logger registered for your package name) to prevent a default configuration being used if the application didn't set one:

# This goes into your library somewhere logging.getLogger('name.of.library').addHandler(logging.NullHandler()) 

and developers using your library can then disable all logging just for your library by disabling log propagation:

logging.getLogger('name.of.library').propagate = False 

All this is already documented in the logging module; you can consider it the style guide for Python logging. From the Configuring Logging for a Library section you already linked to:

Note: It is strongly advised that you do not add any handlers other than NullHandler to your library’s loggers. This is because the configuration of handlers is the prerogative of the application developer who uses your library. The application developer knows their target audience and what handlers are most appropriate for their application: if you add handlers ‘under the hood’, you might well interfere with their ability to carry out unit tests and deliver logs which suit their requirements.

logging.basicConfig() does just that; it creates handler configuration.