edit docs

python · vsajip · Jun 7, 2022 · May 10, 2022 · May 10, 2022 · May 10, 2022
commit f1ea183f6f98871687084440ede535a628681be8
@@ -713,6 +713,41 @@ which, when run, produces something like:
     2010-09-06 22:38:15,301 d.e.f DEBUG    IP: 123.231.231.123 User: fred     A message at DEBUG level with 2 parameters
     2010-09-06 22:38:15,301 d.e.f INFO     IP: 123.231.231.123 User: fred     A message at INFO level with 2 parameters
 
+Imparting contextual information for specific Handlers
+------------------------------------------------------
+
+Each :class:`~Handler` has it's own chain of Filters.
+If you want to add contextual information to a :class:`LogRecord` without leaking
+this contextual information to other handlers, you can use a filter that returns
+a new :class:`~LogRecord` instead of modifying it in-place:
+
+script::
+
+    import logging
+
+    def filter(record: logging.LogRecord):
+        record = logging.LogRecord(
+            name=record.name,
+            level=record.levelno,
+            pathname=record.pathname,
+            lineno=record.lineno,
+            msg=record.msg,
+            exc_info=record.exc_info,
+            args=(),
+        )
+        record.user = 'jim'
+        return record
+
+    if __name__ == '__main__':
+        logger = logging.getLogger()
+        logger.setLevel(logging.INFO)
+        handler = logging.StreamHandler()
+        formatter = logging.Formatter('%(message)s from %(user)-8s')
+        handler.setFormatter(formatter)
+        handler.addFilter(filter)
+        logger.addHandler(handler)
+
+        logger.info('A log message')
 
 .. _multiple-processes:
 

@@ -663,8 +663,9 @@ empty string, all events are passed.
    .. method:: filter(record)
 
       Is the specified record to be logged? Returns zero for no, nonzero for
-      yes. If deemed appropriate, the record may be modified in-place by this
-      method.
+      yes. Filters can also modify log records in-place or return a completely
+      different log-record which will replace the original log record without
+      modifying it.
 
 Note that filters attached to handlers are consulted before an event is
 emitted by the handler, whereas filters attached to loggers are consulted
@@ -686,6 +687,12 @@ which has a ``filter`` method with the same semantics.
    parameter. The returned value should conform to that returned by
    :meth:`~Filter.filter`.
 
+.. versionchanged:: 3.12
+   You can now return a :class:`LogRecord` instance from filters to replace
+   the log record without modifying it in place. This allows filters installed
+   on a :class:`Handler` to modify the log record before it is emitted without
+   having side effects on other handlers.
+
 Although filters are used primarily to filter records based on more
 sophisticated criteria than levels, they get to see every record which is
 processed by the handler or logger they're attached to: this can be useful if