[New-bugs-announce] [issue17007] logging documentation clarifications

[Chris Jerdonek]

New submission from Chris Jerdonek:

Here are some suggestions of things to clarify in the logging documentation after consulting it as an end-user:

1. Clarify in Logger.filter(), Handler.filter(), and probably also in the Filter section that the case of more than filter behaves as follows: filters are applied until a filter says the record should not be processed.  In particular, a record gets processed only if all filters say it should be processed rather than at least one.

This is especially worth clarifying because with the above behavior combined with the Filter class's default behavior, it never makes sense to add more than one filter (because you can replace a group of filters with their lowest common ancestor).  It's only needed with custom filters.

2. Clarify that a handler can log the same record multiple times if it is attached to an ancestor logger.  This clarification perhaps best goes in the Logger.propagate section.  Currently, it's not clear whether loggers/handlers are "smart" in the sense that they keep track of whether a given message has already been passed to a given handler (independent of what loggers it is attached to): "Logger.propagate: If this evaluates to true, logging messages are passed by this logger and by its child loggers to the handlers of higher level (ancestor) loggers."

Incidentally, is there any case where you would want the same handler to process the same record more than once?

3. Clarify in the LogRecord section that the "name" attribute refers to the name of the logger used in the end-user's code rather than the name of the logger handling the message.  In particular, a record logged by a logger and an ancestor logger will have the same "name" field for both.

4. Clarify the last part of this sentence: "Note that filters attached to handlers are consulted whenever an event is emitted by the handler, whereas filters attached to loggers are consulted whenever an event is logged to the handler (using debug(), info(), etc.)"

It should say something like, "whereas filters attached to loggers are consulted prior to sending an event to its handlers."  In particular, there can be more than one handler, and it happens before rather than after being logged to the handlers ("whenever" is somewhat ambiguous).

----------
assignee: docs at python
components: Documentation
keywords: easy
messages: 180344
nosy: chris.jerdonek, docs at python, vinay.sajip
priority: normal
severity: normal
status: open
title: logging documentation clarifications
type: enhancement

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue17007>
_______________________________________