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

[Vinay Sajip]

https://github.com/python/cpython/commit/2543f50033208c1a8df04999082b11aa09e82a04
commit: 2543f50033208c1a8df04999082b11aa09e82a04
branch: master
author: Vinay Sajip <vinay_sajip at yahoo.co.uk>
committer: GitHub <noreply at github.com>
date: 2017-07-30T10:41:45+01:00
summary:

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

files:
A Misc/NEWS.d/next/Library/2017-07-30-10-07-58.bpo-30522.gAX1N-.rst
M Doc/library/logging.handlers.rst
M Lib/logging/__init__.py
M Lib/test/test_logging.py

diff --git a/Doc/library/logging.handlers.rst b/Doc/library/logging.handlers.rst
index f13f765c019..0974286e55d 100644
--- a/Doc/library/logging.handlers.rst
+++ b/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
diff --git a/Lib/logging/__init__.py b/Lib/logging/__init__.py
index f9bfb79ae66..54d4e883d97 100644
--- a/Lib/logging/__init__.py
+++ b/Lib/logging/__init__.py
@@ -997,6 +997,26 @@ def emit(self, record):
         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', '')
diff --git a/Lib/test/test_logging.py b/Lib/test/test_logging.py
index 88845629614..6d0b23441ba 100644
--- a/Lib/test/test_logging.py
+++ b/Lib/test/test_logging.py
@@ -698,6 +698,20 @@ def test_error_handling(self):
         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
 
diff --git a/Misc/NEWS.d/next/Library/2017-07-30-10-07-58.bpo-30522.gAX1N-.rst b/Misc/NEWS.d/next/Library/2017-07-30-10-07-58.bpo-30522.gAX1N-.rst
new file mode 100644
index 00000000000..214f98e101c
--- /dev/null
+++ b/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.