bpo-30522: Implemented a method to allow setting a logging.StreamHander's stream. (GH-2921)

Doc/library/logging.handlers.rst

@@ -59,6 +59,18 @@ and :meth:`flush` methods).
       :meth:`close` method is inherited from :class:`~logging.Handler` and so
       does no output, so an explicit :meth:`flush` call may be needed at times.
 
+   .. method:: setStream(stream)
+
+      Sets the instance's stream to the specified value, if it is different.
+      The old stream is flushed before the new stream is set.
+
+      :param stream: The stream that the handler should use.
+
+      :return: the old stream, if the stream was changed, or *None* if it wasn't.
+
+   .. versionadded:: 3.7
+
+
 .. versionchanged:: 3.2
    The ``StreamHandler`` class now has a ``terminator`` attribute, default
    value ``'\n'``, which is used as the terminator when writing a formatted
@@ -66,6 +78,7 @@ and :meth:`flush` methods).
    set the handler instance's ``terminator`` attribute to the empty string.
    In earlier versions, the terminator was hardcoded as ``'\n'``.
 
+
 .. _file-handler:
 
 FileHandler

Lib/logging/__init__.py

@@ -997,6 +997,26 @@ class StreamHandler(Handler):
         except Exception:
             self.handleError(record)
 
+    def setStream(self, stream):
+        """
+        Sets the StreamHandler's stream to the specified value,
+        if it is different.
+
+        Returns the old stream, if the stream was changed, or None
+        if it wasn't.
+        """
+        if stream is self.stream:
+            result = None
+        else:
+            result = self.stream
+            self.acquire()
+            try:
+                self.flush()
+                self.stream = stream
+            finally:
+                self.release()
+        return result
+
     def __repr__(self):
         level = getLevelName(self.level)
         name = getattr(self.stream, 'name', '')

Lib/test/test_logging.py

@@ -698,6 +698,20 @@ class StreamHandlerTest(BaseTest):
         finally:
             logging.raiseExceptions = old_raise
 
+    def test_stream_setting(self):
+        """
+        Test setting the handler's stream
+        """
+        h = logging.StreamHandler()
+        stream = io.StringIO()
+        old = h.setStream(stream)
+        self.assertIs(old, sys.stderr)
+        actual = h.setStream(old)
+        self.assertIs(actual, stream)
+        # test that setting to existing value returns None
+        actual = h.setStream(old)
+        self.assertIsNone(actual)
+
 # -- The following section could be moved into a server_helper.py module
 # -- if it proves to be of wider utility than just test_logging
 

Misc/NEWS.d/next/Library/2017-07-30-10-07-58.bpo-30522.gAX1N-.rst

@@ -0,0 +1,2 @@
+Added a ``setStream`` method to ``logging.StreamHandler`` to allow the
+stream to be set after creation.