https://github.com/python/cpython/commit/5cca0419cf3778a6b3a4f7f67147437ba8c84dfe
commit: 5cca0419cf3778a6b3a4f7f67147437ba8c84dfe
branch: 3.12
author: Miss Islington (bot) <[email protected]>
committer: vsajip <[email protected]>
date: 2024-05-28T15:04:19+01:00
summary:
[3.12] [doc] Clarify the nature of the root logger in the `logging`
documentation (GH-119440) (GH-119652)
(cherry picked from commit b407ad38fb93585332c370b8fa56905fb238cdfd)
files:
M Doc/library/logging.rst
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index 76ecad5c5aa3c8..c6ab3744ad5338 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -109,11 +109,11 @@ The ``name`` is potentially a period-separated
hierarchical value, like
Loggers that are further down in the hierarchical list are children of loggers
higher up in the list. For example, given a logger with a name of ``foo``,
loggers with names of ``foo.bar``, ``foo.bar.baz``, and ``foo.bam`` are all
-descendants of ``foo``. The logger name hierarchy is analogous to the Python
-package hierarchy, and identical to it if you organise your loggers on a
-per-module basis using the recommended construction
-``logging.getLogger(__name__)``. That's because in a module, ``__name__``
-is the module's name in the Python package namespace.
+descendants of ``foo``. In addition, all loggers are descendants of the root
+logger. The logger name hierarchy is analogous to the Python package hierarchy,
+and identical to it if you organise your loggers on a per-module basis using
+the recommended construction ``logging.getLogger(__name__)``. That's because
+in a module, ``__name__`` is the module's name in the Python package namespace.
.. class:: Logger
@@ -1144,10 +1144,12 @@ functions.
.. function:: getLogger(name=None)
- Return a logger with the specified name or, if name is ``None``, return a
- logger which is the root logger of the hierarchy. If specified, the name is
- typically a dot-separated hierarchical name like *'a'*, *'a.b'* or
*'a.b.c.d'*.
- Choice of these names is entirely up to the developer who is using logging.
+ Return a logger with the specified name or, if name is ``None``, return the
+ root logger of the hierarchy. If specified, the name is typically a
+ dot-separated hierarchical name like *'a'*, *'a.b'* or *'a.b.c.d'*. Choice
+ of these names is entirely up to the developer who is using logging, though
+ it is recommended that ``__name__`` be used unless you have a specific
+ reason for not doing that, as mentioned in :ref:`logger`.
All calls to this function with a given name return the same logger
instance.
This means that logger instances never need to be passed between different
parts
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: [email protected]
