From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Tue, 7 Dec 2021 11:45:49 +0000 (-0800)
Subject: [3.9] bpo-35821: Add an example to Logger.propagate documentation. (GH-29841) (GH... 
X-Git-Tag: v3.9.10~80
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e688568cdfe758a2316ecaf0c8df868d5dde0d83;p=thirdparty%2FPython%2Fcpython.git

[3.9] bpo-35821: Add an example to Logger.propagate documentation. (GH-29841) (GH-29958)
---

diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index e72a898a1136..705b31d60450 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -80,6 +80,15 @@ is the module's name in the Python package namespace.
       If this evaluates to false, logging messages are not passed to the handlers
       of ancestor loggers.
 
+      Spelling it out with an example: If the propagate attribute of the logger named
+      `A.B.C` evaluates to true, any event logged to `A.B.C` via a method call such as
+      `logging.getLogger('A.B.C').error(...)` will [subject to passing that logger's
+      level and filter settings] be passed in turn to any handlers attached to loggers
+      named `A.B`, `A` and the root logger, after first being passed to any handlers
+      attached to `A.B.C`. If any logger in the chain `A.B.C`, `A.B`, `A` has its
+      `propagate` attribute set to false, then that is the last logger whose handlers
+      are offered the event to handle, and propagation stops at that point.
+
       The constructor sets this attribute to ``True``.
 
       .. note:: If you attach a handler to a logger *and* one or more of its