From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Thu, 8 Sep 2022 07:33:16 +0000 (-0700)
Subject: [3.10] gh-88287: Add BufferingFormatter documentation. (GH-96608) (GH-96674)
X-Git-Tag: v3.10.8~142
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=6ee7a6b947c607ac79e5b66177405787dcaa8c06;p=thirdparty%2FPython%2Fcpython.git

[3.10] gh-88287: Add BufferingFormatter documentation. (GH-96608) (GH-96674)
---

diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index 824076f827af..6e83df8adb5c 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -652,6 +652,35 @@ The useful mapping keys in a :class:`LogRecord` are given in the section on
       :func:`traceback.print_stack`, but with the last newline removed) as a
       string. This default implementation just returns the input value.
 
+.. class:: BufferingFormatter(linefmt=None)
+
+   A base formatter class suitable for subclassing when you want to format a
+   number of records. You can pass a :class:`Formatter` instance which you want
+   to use to format each line (that corresponds to a single record). If not
+   specified, the default formatter (which just outputs the event message) is
+   used as the line formatter.
+
+   .. method:: formatHeader(records)
+
+      Return a header for a list of *records*. The base implementation just
+      returns the empty string. You will need to override this method if you
+      want specific behaviour, e.g. to show the count of records, a title or a
+      separator line.
+
+   .. method:: formatFooter(records)
+
+      Return a footer for a list of *records*. The base implementation just
+      returns the empty string. You will need to override this method if you
+      want specific behaviour, e.g. to show the count of records or a separator
+      line.
+
+   .. method:: format(records)
+
+      Return formatted text for a list of *records*. The base implementation
+      just returns the empty string if there are no records; otherwise, it
+      returns the concatenation of the header, each record formatted with the
+      line formatter, and the footer.
+
 .. _filter:
 
 Filter Objects