[docs] [issue34590] "Logging HOWTO" should share an example of best practices for using logging in a library

[Nathaniel Manista]

New submission from Nathaniel Manista <nathaniel at google.com>:

https://docs.python.org/3.8/howto/logging.html#configuring-logging-for-a-library is a bit too short and doesn't answer some questions that I have as a library author about the best ways to use logging in a library.

Should I make use of a single logger object in my library, multiple loggers in a tree, or multiple unrelated loggers? Since I have just one public module, I'm tempted to say that I should just use one logger object.

Should I present as part of my public API the name of the logger object(s) used? Probably - the documentation starts with "When developing a library which uses logging, you should take care to document how the library uses logging - for example, the names of loggers used.". But should I also include the logger objects in my API? If an application wants to reach my logger, why should they use "logging.getLogger(<name that I shared with them>)" rather than "my_library.LOGGER"?

Should I use my library's fully-qualified name as the name of its logger? This seems like a great idea because it's unlikely to bring up any new conflicts. Is it a best practice? Is there any better practice?

The "Configuring Logging for a Library" text could answer these questions, and maybe it should, but... I really think a toy library example that library authors could follow would also help a great deal.

----------
assignee: docs at python
components: Documentation
messages: 324652
nosy: Nathaniel Manista, docs at python
priority: normal
severity: normal
status: open
title: "Logging HOWTO" should share an example of best practices for using logging in a library
type: enhancement
versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue34590>
_______________________________________