[3.13] [doc] Clarify the nature of the root logger in the logging documentation (GH-119440) (GH-119651)

(cherry picked from commit b407ad38fb)
This commit is contained in:
Miss Islington (bot) 2024-05-28 16:04:46 +02:00 committed by GitHub
parent dcf585d0c1
commit 47fb0f82cd
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -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 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``, 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 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 descendants of ``foo``. In addition, all loggers are descendants of the root
package hierarchy, and identical to it if you organise your loggers on a logger. The logger name hierarchy is analogous to the Python package hierarchy,
per-module basis using the recommended construction and identical to it if you organise your loggers on a per-module basis using
``logging.getLogger(__name__)``. That's because in a module, ``__name__`` the recommended construction ``logging.getLogger(__name__)``. That's because
is the module's name in the Python package namespace. in a module, ``__name__`` is the module's name in the Python package namespace.
.. class:: Logger .. class:: Logger
@ -1157,10 +1157,12 @@ functions.
.. function:: getLogger(name=None) .. function:: getLogger(name=None)
Return a logger with the specified name or, if name is ``None``, return a Return a logger with the specified name or, if name is ``None``, return the
logger which is the root logger of the hierarchy. If specified, the name is root logger of the hierarchy. If specified, the name is typically a
typically a dot-separated hierarchical name like *'a'*, *'a.b'* or *'a.b.c.d'*. dot-separated hierarchical name like *'a'*, *'a.b'* or *'a.b.c.d'*. Choice
Choice of these names is entirely up to the developer who is using logging. 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. 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 This means that logger instances never need to be passed between different parts