From c302708aaecce672bb7f0949626d7a42b1f967f5 Mon Sep 17 00:00:00 2001 From: Justin Kunimune Date: Wed, 22 May 2024 17:46:39 -0400 Subject: [PATCH 1/4] clarify details of root logger The way it's currently written, it's very confusing what the root logger's name is, because it's not explicitly stated anywhere (the how-to page says that its name "is printed as 'root'", which makes it sound like it's actually something else, but it's not it's just 'root'), and because it is stated that the logging hierarchy is based on period-separated names (this is true except for "root", and that exception isn't stated anywhere here). --- Doc/library/logging.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 564b34bcf1bb37..558833d4f2197a 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -109,7 +109,8 @@ 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 +descendants of ``foo``. In addition, all loggers are descendants of ``root``. +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__`` @@ -1157,8 +1158,8 @@ 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 + Return a logger with the specified name or, if name is ``None``, return the + root logger of the hierarchy (equivalent to passing ``name='root'``). 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. From 9b1c761e812157331afa106a86a5bd818a39690f Mon Sep 17 00:00:00 2001 From: Justin Kunimune Date: Fri, 24 May 2024 14:15:54 -0400 Subject: [PATCH 2/4] Refer to the root logger consistently in the documentation Understood about not wanting people to rely on the root logger's name being `'root'`. I rephrased it to always refer to the root logger as simply "the root logger", as is done in the rest of the document. --- Doc/library/logging.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 558833d4f2197a..2eb4d60044f9cc 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -109,7 +109,7 @@ 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``. In addition, all loggers are descendants of ``root``. +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 @@ -1159,7 +1159,7 @@ functions. .. function:: getLogger(name=None) Return a logger with the specified name or, if name is ``None``, return the - root logger of the hierarchy (equivalent to passing ``name='root'``). If specified, the name is + 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. From 323741c2abbacfa9d6c8b6443b60964744110325 Mon Sep 17 00:00:00 2001 From: Justin Kunimune Date: Sat, 25 May 2024 09:56:26 -0400 Subject: [PATCH 3/4] Update Doc/library/logging.rst Co-authored-by: Vinay Sajip --- Doc/library/logging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 2eb4d60044f9cc..d79a60ec908e8c 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -1161,7 +1161,7 @@ functions. 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. + 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-objects`. 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 From 89024a1d762536d25c842a3f80b4e26b74ae4f03 Mon Sep 17 00:00:00 2001 From: Vinay Sajip Date: Tue, 28 May 2024 11:01:37 +0100 Subject: [PATCH 4/4] Fix cross-reference and reformat paragraphs. --- Doc/library/logging.rst | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index d79a60ec908e8c..4ba520c139ebce 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -109,12 +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``. 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. +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 @@ -1159,9 +1158,11 @@ functions. .. function:: getLogger(name=None) 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-objects`. + 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