classification
Title: Clarify when logging events are propagated when propagate is true
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: chris.jerdonek, docs@python, kj, miss-islington, vinay.sajip, xtreak
Priority: normal Keywords: patch

Created on 2019-01-24 20:07 by chris.jerdonek, last changed 2021-12-07 15:48 by miss-islington. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 29841 merged vinay.sajip, 2021-11-29 13:25
PR 29957 merged miss-islington, 2021-12-07 11:15
PR 29958 merged miss-islington, 2021-12-07 11:16
PR 29963 merged kj, 2021-12-07 14:03
PR 29965 merged miss-islington, 2021-12-07 15:25
PR 29966 merged miss-islington, 2021-12-07 15:25
Messages (13)
msg334320 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2019-01-24 20:07
Currently, the logging docs are a bit ambiguous or at least not completely clear as to when events are propagated when Logger.propagate is true. The docs currently say [1]--

"If [the `propagate`] attribute evaluates to true, events logged to this logger will be passed to the handlers of higher level (ancestor) loggers, in addition to any handlers attached to this logger."

But it's not clear if "logged to this logger" means (1) a log method like info() or error() was called on the logger, or (2) the event was passed to the logger's handlers (i.e. satisfied the logger's log level threshold and any filters).

Empirically, I found that the meaning is (2).

[1]: https://docs.python.org/3/library/logging.html#logging.Logger.propagate
msg334333 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2019-01-25 00:41
Also, does "logged to this logger" include events propagated to it from a child logger? For example, if an event is logged to logger "A.B.C" and propagated to "A.B", will the propagate attribute of the latter effect whether logger "A" (or its handlers) sees it?
msg334340 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2019-01-25 05:46
I believe the information is clear from this link in the documentation:

https://docs.python.org/3/howto/logging.html#logging-flow

However, if you can suggest alternative wording which you think is clearer, I'll certainly take a look at it. Perhaps a link could be added to this section from the logging.Logger.propagate section.
msg334342 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2019-01-25 06:58
Thanks for the diagram. How about the following as a replacement?

"If this attribute is true and the event isn't rejected by the logger's level and filters, an event passed to this logger will recursively be passed to its parent logger and handled by the parent logger's handlers (after being handled by the original logger's handlers). The logger level and filters only come into play for the very first logger in this chain. For subsequent loggers, only the propagate attribute determines whether the event is passed to the parent."
msg334360 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2019-01-25 13:32
That isn't quite accurate. A logger's attached handlers will always be offered a chance to handle an event if the logger's level and filters allow. However, the event is not actually passed to ancestor loggers - it is directly offered to any handlers attached to ancestor loggers, until a logger is encountered where propagate is false - and that is the last logger whose handlers are offered the event. All handlers have their own levels and filters and may or may not process an event according to those levels and filters.
msg334362 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2019-01-25 14:15
I'm not sure which part of what I wrote you think is inaccurate. All of what you wrote matches what I was trying to convey.

For example, my saying "pass to the parent logger" corresponds to the "set current logger to parent" box in the diagram. And by "handled by the parent logger's handlers" I meant "directly offered to any handlers attached to ancestor loggers." And "only the propagate attribute determines whether the event is passed" matches your "until a logger is encountered where propagate is false."
msg334503 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2019-01-29 07:41
> I'm not sure which part of what I wrote you think is inaccurate.

It's just that language can be tricky. When you said "pass to the parent logger" this might be misconstrued as some kind of call to a method of the parent logger.

Your OP says that you think "logged to this logger" means (2), but actually it means (1). Expanding with examples:

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.
msg407914 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2021-12-07 11:15
New changeset 2bf551757e0a7e3cc6ce2ebed2178b82438ac6b5 by Vinay Sajip in branch 'main':
bpo-35821: Add an example to Logger.propagate documentation. (GH-29841)
https://github.com/python/cpython/commit/2bf551757e0a7e3cc6ce2ebed2178b82438ac6b5
msg407919 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2021-12-07 11:45
New changeset f78c229b4ec8621a9b15c6396b6c91518e8975d6 by Miss Islington (bot) in branch '3.10':
[3.10] bpo-35821: Add an example to Logger.propagate documentation. (GH-29841) (GH-29957)
https://github.com/python/cpython/commit/f78c229b4ec8621a9b15c6396b6c91518e8975d6
msg407920 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2021-12-07 11:45
New changeset e688568cdfe758a2316ecaf0c8df868d5dde0d83 by Miss Islington (bot) in branch '3.9':
[3.9] bpo-35821: Add an example to Logger.propagate documentation. (GH-29841) (GH-29958)
https://github.com/python/cpython/commit/e688568cdfe758a2316ecaf0c8df868d5dde0d83
msg407943 - (view) Author: Ken Jin (kj) * (Python committer) Date: 2021-12-07 15:25
New changeset c7e7a4b969b5728d4b4f3c59bf98e1e830d5c6d6 by Ken Jin in branch 'main':
bpo-35821: Fix restructuredtext code formatting in logging.rst (GH-29963)
https://github.com/python/cpython/commit/c7e7a4b969b5728d4b4f3c59bf98e1e830d5c6d6
msg407944 - (view) Author: miss-islington (miss-islington) Date: 2021-12-07 15:47
New changeset 14f03ce6e8a33cc8b45f11c4d428193fc7c4a145 by Miss Islington (bot) in branch '3.10':
[3.10] bpo-35821: Fix restructuredtext code formatting in logging.rst (GH-29963) (GH-29965)
https://github.com/python/cpython/commit/14f03ce6e8a33cc8b45f11c4d428193fc7c4a145
msg407945 - (view) Author: miss-islington (miss-islington) Date: 2021-12-07 15:48
New changeset db42809d299d1bc3a07b29fabe8f74fa02a7e59e by Miss Islington (bot) in branch '3.9':
bpo-35821: Fix restructuredtext code formatting in logging.rst (GH-29963)
https://github.com/python/cpython/commit/db42809d299d1bc3a07b29fabe8f74fa02a7e59e
History
Date User Action Args
2021-12-07 15:48:42miss-islingtonsetmessages: + msg407945
2021-12-07 15:47:42miss-islingtonsetmessages: + msg407944
2021-12-07 15:25:26miss-islingtonsetpull_requests: + pull_request28191
2021-12-07 15:25:22kjsetmessages: + msg407943
2021-12-07 15:25:21miss-islingtonsetpull_requests: + pull_request28190
2021-12-07 14:03:42kjsetnosy: + kj

pull_requests: + pull_request28188
2021-12-07 11:46:07vinay.sajipsetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2021-12-07 11:45:52vinay.sajipsetmessages: + msg407920
2021-12-07 11:45:22vinay.sajipsetmessages: + msg407919
2021-12-07 11:16:02miss-islingtonsetpull_requests: + pull_request28182
2021-12-07 11:15:57miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request28181
2021-12-07 11:15:53vinay.sajipsetmessages: + msg407914
2021-11-29 13:25:57vinay.sajipsetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request28070
2019-01-29 07:41:14vinay.sajipsetmessages: + msg334503
2019-01-25 14:15:35chris.jerdoneksetmessages: + msg334362
2019-01-25 13:32:40vinay.sajipsetmessages: + msg334360
2019-01-25 06:58:45chris.jerdoneksetmessages: + msg334342
2019-01-25 05:46:06vinay.sajipsetmessages: + msg334340
2019-01-25 00:42:00chris.jerdoneksetmessages: + msg334333
2019-01-25 00:27:27xtreaksetnosy: + vinay.sajip, xtreak
2019-01-24 20:07:19chris.jerdonekcreate