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@python
components: Documentation
keywords: easy
messages: 180344
nosy: chris.jerdonek, docs@python, vinay.sajip
priority: normal
severity: normal
status: open
title: logging documentation clarifications
type: enhancement
_______________________________________
Python tracker <rep...@bugs.python.org>
<http://bugs.python.org/issue17007>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
