https://github.com/python/cpython/commit/47fb0f82cdd949b863e6e8dda13e38c62d6509cb
commit: 47fb0f82cdd949b863e6e8dda13e38c62d6509cb
branch: 3.13
author: Miss Islington (bot) <[email protected]>
committer: vsajip <[email protected]>
date: 2024-05-28T15:04:46+01:00
summary:
[3.13] [doc] Clarify the nature of the root logger in the `logging`
documentation (GH-119440) (GH-119651)
(cherry picked from commit b407ad38fb93585332c370b8fa56905fb238cdfd)
files:
M Doc/library/logging.rst
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index fb6ca38ba72aba..0624423c950797 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
@@ -1157,10 +1157,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]
