Skip to content

Commit b407ad3

Browse files
jkunimunevsajip
andauthored
[doc] Clarify the nature of the root logger in the logging documentation (GH-119440)
Co-authored-by: Vinay Sajip <[email protected]>
1 parent 669175b commit b407ad3

File tree

1 file changed

+11
-9
lines changed

1 file changed

+11
-9
lines changed

Doc/library/logging.rst

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -109,11 +109,11 @@ The ``name`` is potentially a period-separated hierarchical value, like
109109
Loggers that are further down in the hierarchical list are children of loggers
110110
higher up in the list. For example, given a logger with a name of ``foo``,
111111
loggers with names of ``foo.bar``, ``foo.bar.baz``, and ``foo.bam`` are all
112-
descendants of ``foo``. The logger name hierarchy is analogous to the Python
113-
package hierarchy, and identical to it if you organise your loggers on a
114-
per-module basis using the recommended construction
115-
``logging.getLogger(__name__)``. That's because in a module, ``__name__``
116-
is the module's name in the Python package namespace.
112+
descendants of ``foo``. In addition, all loggers are descendants of the root
113+
logger. The logger name hierarchy is analogous to the Python package hierarchy,
114+
and identical to it if you organise your loggers on a per-module basis using
115+
the recommended construction ``logging.getLogger(__name__)``. That's because
116+
in a module, ``__name__`` is the module's name in the Python package namespace.
117117

118118

119119
.. class:: Logger
@@ -1157,10 +1157,12 @@ functions.
11571157

11581158
.. function:: getLogger(name=None)
11591159

1160-
Return a logger with the specified name or, if name is ``None``, return a
1161-
logger which is the root logger of the hierarchy. If specified, the name is
1162-
typically a dot-separated hierarchical name like *'a'*, *'a.b'* or *'a.b.c.d'*.
1163-
Choice of these names is entirely up to the developer who is using logging.
1160+
Return a logger with the specified name or, if name is ``None``, return the
1161+
root logger of the hierarchy. If specified, the name is typically a
1162+
dot-separated hierarchical name like *'a'*, *'a.b'* or *'a.b.c.d'*. Choice
1163+
of these names is entirely up to the developer who is using logging, though
1164+
it is recommended that ``__name__`` be used unless you have a specific
1165+
reason for not doing that, as mentioned in :ref:`logger`.
11641166

11651167
All calls to this function with a given name return the same logger instance.
11661168
This means that logger instances never need to be passed between different parts

0 commit comments

Comments
 (0)