[doc] Add a note in howto/logging.rst about "do not log to root logger in libraries" (GH-31271)

This commit is contained in:
Yuxin Wu 2022-02-26 10:29:51 -08:00 committed by GitHub
parent 0d9b565e62
commit fc44b8136f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 7 additions and 0 deletions

View File

@ -831,6 +831,13 @@ should have the desired effect. If an organisation produces a number of
libraries, then the logger name specified can be 'orgname.foo' rather than
just 'foo'.
.. note:: It is strongly advised that you *do not log to the root logger*
in your library. Instead, use a logger with a unique and easily
identifiable name, such as the ``__name__`` for your library's top-level package
or module. Logging to the root logger will make it difficult or impossible for
the application developer to configure the logging verbosity or handlers of
your library as they wish.
.. note:: It is strongly advised that you *do not add any handlers other
than* :class:`~logging.NullHandler` *to your library's loggers*. This is
because the configuration of handlers is the prerogative of the application