gh-77116: Add SMTP buffering example to logging cookbook. (GH-96324)

Doc/howto/logging-cookbook.rst

@@ -2678,6 +2678,88 @@ You can of course use the conventional means of decoration::
         ...
 
 
+.. _buffered-smtp:
+
+Sending logging messages to email, with buffering
+-------------------------------------------------
+
+To illustrate how you can send log messages via email, so that a set number of
+messages are sent per email, you can subclass
+:class:`~logging.handlers.BufferingHandler`. In the following  example, which you can
+adapt to suit your specific needs, a simple test harness is provided which allows you
+to run the script with command line arguments specifying what you typically need to
+send things via SMTP. (Run the downloaded script with the ``-h`` argument to see the
+required and optional arguments.)
+
+.. code-block:: python
+
+    import logging
+    import logging.handlers
+    import smtplib
+
+    class BufferingSMTPHandler(logging.handlers.BufferingHandler):
+        def __init__(self, mailhost, port, username, password, fromaddr, toaddrs,
+                     subject, capacity):
+            logging.handlers.BufferingHandler.__init__(self, capacity)
+            self.mailhost = mailhost
+            self.mailport = port
+            self.username = username
+            self.password = password
+            self.fromaddr = fromaddr
+            if isinstance(toaddrs, str):
+                toaddrs = [toaddrs]
+            self.toaddrs = toaddrs
+            self.subject = subject
+            self.setFormatter(logging.Formatter("%(asctime)s %(levelname)-5s %(message)s"))
+
+        def flush(self):
+            if len(self.buffer) > 0:
+                try:
+                    smtp = smtplib.SMTP(self.mailhost, self.mailport)
+                    smtp.starttls()
+                    smtp.login(self.username, self.password)
+                    msg = "From: %s\r\nTo: %s\r\nSubject: %s\r\n\r\n" % (self.fromaddr, ','.join(self.toaddrs), self.subject)
+                    for record in self.buffer:
+                        s = self.format(record)
+                        msg = msg + s + "\r\n"
+                    smtp.sendmail(self.fromaddr, self.toaddrs, msg)
+                    smtp.quit()
+                except Exception:
+                    if logging.raiseExceptions:
+                        raise
+                self.buffer = []
+
+    if __name__ == '__main__':
+        import argparse
+
+        ap = argparse.ArgumentParser()
+        aa = ap.add_argument
+        aa('host', metavar='HOST', help='SMTP server')
+        aa('--port', '-p', type=int, default=587, help='SMTP port')
+        aa('user', metavar='USER', help='SMTP username')
+        aa('password', metavar='PASSWORD', help='SMTP password')
+        aa('to', metavar='TO', help='Addressee for emails')
+        aa('sender', metavar='SENDER', help='Sender email address')
+        aa('--subject', '-s',
+           default='Test Logging email from Python logging module (buffering)',
+           help='Subject of email')
+        options = ap.parse_args()
+        logger = logging.getLogger()
+        logger.setLevel(logging.DEBUG)
+        h = BufferingSMTPHandler(options.host, options.port, options.user,
+                                 options.password, options.sender,
+                                 options.to, options.subject, 10)
+        logger.addHandler(h)
+        for i in range(102):
+            logger.info("Info index = %d", i)
+        h.flush()
+        h.close()
+
+If you run this script and your SMTP server is correctly set up, you should find that
+it sends eleven emails to the addressee you specify. The first ten emails will each
+have ten log messages, and the eleventh will have two messages. That makes up 102
+messages as specified in the script.
+
 .. _utc-formatting:
 
 Formatting times using UTC (GMT) via configuration