Documentation falsely leads to believe that MemoryHandler can be used to wrap SMTPHandler to send multiple messages per email

[enrico]

BPO	32935
Nosy	@iritkatriel

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2018-02-24.10:31:19.926>
labels = ['library', '3.10']
title = 'Documentation falsely leads to believe that MemoryHandler can be used to wrap SMTPHandler to send multiple messages per email'
updated_at = <Date 2021-04-14.22:02:39.145>
user = 'https://bugs.python.org/enrico'

bugs.python.org fields:

activity = <Date 2021-04-14.22:02:39.145>
actor = 'iritkatriel'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Library (Lib)']
creation = <Date 2018-02-24.10:31:19.926>
creator = 'enrico'
dependencies = []
files = []
hgrepos = []
issue_num = 32935
keywords = []
message_count = 2.0
messages = ['312710', '391103']
nosy_count = 2.0
nosy_names = ['enrico', 'iritkatriel']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue32935'
versions = ['Python 3.10']

[enrico]

In the handlers documentation, MemoryHandler directly follows SMTPHandler. SMTPHandler does not document that it is sending an email per every logging invocation, but one can sort of guess it.

Right afterwards, there is the documentation of MemoryHandler, which seems to hint that one can use it to buffer up log lines and send all of them with SMTPHandler at flush time, by using it as a target.

What really happens when trying to do that, is that at flush time an email per buffered log line is sent instead.

It would have saved me significant time and frustration if I had found in SMTPHandler a note saynig that in order to buffer up all log messages and send them as a single email, one needs to reimplement BufferingHandler and all the email composition/sending logic, and the existing handlers provide no build-in facility for doing that.

[iritkatriel]

The documentation does talk about emit() operating on single records:

https://docs.python.org/3/library/logging.handlers.html#logging.handlers.BufferingHandler.emit

How would you make this clearer?