[Python-checkins] [doc] Add a note in howto/logging.rst about "do not log to root logger in libraries" (GH-31271)
vsajip
webhook-mailer at python.org
Sat Feb 26 13:30:10 EST 2022
https://github.com/python/cpython/commit/fc44b8136ffc501264731ccc7456729b5cf4e74b
commit: fc44b8136ffc501264731ccc7456729b5cf4e74b
branch: main
author: Yuxin Wu <ppwwyyxxc at gmail.com>
committer: vsajip <vinay_sajip at yahoo.co.uk>
date: 2022-02-26T18:29:51Z
summary:
[doc] Add a note in howto/logging.rst about "do not log to root logger in libraries" (GH-31271)
files:
M Doc/howto/logging.rst
diff --git a/Doc/howto/logging.rst b/Doc/howto/logging.rst
index fcc6bec768800..4d76c27332ccd 100644
--- a/Doc/howto/logging.rst
+++ b/Doc/howto/logging.rst
@@ -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
More information about the Python-checkins
mailing list