Skip to content

Commit 5cca041

Browse files
[3.12] [doc] Clarify the nature of the root logger in the logging documentation (GH-119440) (GH-119652)
(cherry picked from commit b407ad3)
1 parent 6ffbd93 commit 5cca041

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
@@ -1144,10 +1144,12 @@ functions.
11441144

11451145
.. function:: getLogger(name=None)
11461146

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

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

0 commit comments

Comments
 (0)