Skip to content

Commit

Permalink
[3.12] [doc] Clarify the nature of the root logger in the logging d…
Browse files Browse the repository at this point in the history
…ocumentation (GH-119440) (GH-119652)

(cherry picked from commit b407ad3)
  • Loading branch information
miss-islington committed May 28, 2024
1 parent 6ffbd93 commit 5cca041
Showing 1 changed file with 11 additions and 9 deletions.
20 changes: 11 additions & 9 deletions Doc/library/logging.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -1144,10 +1144,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
Expand Down

0 comments on commit 5cca041

Please sign in to comment.