Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

[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
1 changed files with 11 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
Doc/library/logging.rst
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
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