#17987: properly document support.captured_xxx.

Patch by Dmi Baranov.

diff --git a/Doc/library/test.rst b/Doc/library/test.rst
index 702ef8ac428974da7f5914329cb16b06c6ef756c..bf78b4d763526613e441c771c9328031758a5c01 100644 (file)
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@@ -362,17 +362,29 @@ The :mod:`test.support` module defines the following functions:
       New optional arguments *filters* and *quiet*.
 
 
-.. function:: captured_stdout()
+.. function:: captured_stdin()
+              captured_stdout()
+              captured_stderr()
 
-   A context manager that runs the :keyword:`with` statement body using a
-   :class:`io.StringIO` object as sys.stdout.  That object can be retrieved
-   using the ``as`` clause of the :keyword:`with` statement.
+   A context managers that temporarily replaces the named stream with
+   :class:`io.StringIO` object.
 
-   Example use::
+   Example use with output streams::
 
-      with captured_stdout() as s:
+      with captured_stdout() as stdout, captured_stderr() as stderr:
           print("hello")
-      assert s.getvalue() == "hello\n"
+          print("error", file=sys.stderr)
+      assert stdout.getvalue() == "hello\n"
+      assert stderr.getvalue() == "error\n"
+
+   Example use with input stream::
+
+      with captured_stdin() as stdin:
+          stdin.write('hello\n')
+          stdin.seek(0)
+          # call test code that consumes from sys.stdin
+          captured = input()
+      self.assertEqual(captured, "hello")
 
 
 .. function:: temp_cwd(name='tempcwd', quiet=False, path=None)

diff --git a/Lib/test/support.py b/Lib/test/support.py
index 8db90a2a8cd7b943b3c2575f8881c46ac2e38f99..7ab5ff7d3168913868309b3a55037cbf57fe3019 100644 (file)
--- a/Lib/test/support.py
+++ b/Lib/test/support.py
@@ -1184,16 +1184,31 @@ def captured_output(stream_name):
 def captured_stdout():
     """Capture the output of sys.stdout:
 
-       with captured_stdout() as s:
+       with captured_stdout() as stdout:
            print("hello")
-       self.assertEqual(s.getvalue(), "hello")
+       self.assertEqual(stdout.getvalue(), "hello\n")
     """
     return captured_output("stdout")
 
 def captured_stderr():
+    """Capture the output of sys.stderr:
+
+       with captured_stderr() as stderr:
+           print("hello", file=sys.stderr)
+       self.assertEqual(stderr.getvalue(), "hello\n")
+    """
     return captured_output("stderr")
 
 def captured_stdin():
+    """Capture the input to sys.stdin:
+
+       with captured_stdin() as stdin:
+           stdin.write('hello\n')
+           stdin.seek(0)
+           # call test code that consumes from sys.stdin
+           captured = input()
+       self.assertEqual(captured, "hello")
+    """
     return captured_output("stdin")
 
 

diff --git a/Lib/test/test_support.py b/Lib/test/test_support.py
index f6ef5f614713e83b13a4b384f29f0054749b8b0b..340b8daa4e5a0b5d96fd841f160c3ea0163a6f1f 100644 (file)
--- a/Lib/test/test_support.py
+++ b/Lib/test/test_support.py
@@ -130,19 +130,22 @@ class TestSupport(unittest.TestCase):
         self.assertNotIn("bar", sys.path)
 
     def test_captured_stdout(self):
-        with support.captured_stdout() as s:
+        with support.captured_stdout() as stdout:
             print("hello")
-        self.assertEqual(s.getvalue(), "hello\n")
+        self.assertEqual(stdout.getvalue(), "hello\n")
 
     def test_captured_stderr(self):
-        with support.captured_stderr() as s:
+        with support.captured_stderr() as stderr:
             print("hello", file=sys.stderr)
-        self.assertEqual(s.getvalue(), "hello\n")
+        self.assertEqual(stderr.getvalue(), "hello\n")
 
     def test_captured_stdin(self):
-        with support.captured_stdin() as s:
-            print("hello", file=sys.stdin)
-        self.assertEqual(s.getvalue(), "hello\n")
+        with support.captured_stdin() as stdin:
+            stdin.write('hello\n')
+            stdin.seek(0)
+            # call test code that consumes from sys.stdin
+            captured = input()
+        self.assertEqual(captured, "hello")
 
     def test_gc_collect(self):
         support.gc_collect()

diff --git a/Misc/ACKS b/Misc/ACKS
index 13929770e7a702b1f500dc0cbbc0b34257f05ef7..087db243ce73d1dab32639c6c71b6b77cd6be67c 100644 (file)
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -65,6 +65,7 @@ Luigi Ballabio
 Jeff Balogh
 Manuel Balsera
 Matt Bandy
+Dmi Baranov
 Michael J. Barber
 Daniel Barclay
 Nicolas Bareil