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

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?

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.

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."

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.

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."

> 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.

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

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

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

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

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

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