classification
Title: test.support.captured_output has invalid docstring example
Type: Stage: resolved
Components: Documentation Versions: Python 3.1, Python 3.2
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: ezio.melotti, georg.brandl, mnewman, python-dev
Priority: normal Keywords:

Created on 2010-02-18 21:23 by mnewman, last changed 2011-05-14 11:59 by ezio.melotti. This issue is now closed.

Messages (5)
msg99529 - (view) Author: Michael Newman (mnewman) Date: 2010-02-18 21:23
test.support.captured_output is not covered in the online documents:
http://docs.python.org/3.1/library/test.html
http://docs.python.org/dev/py3k/library/test.html

However, it does have a docstring in "C:\Python31\Lib\test\support.py" (see below). The current example for "captured_output" does not work. Looks like someone moved it from "captured_stdout" but did not fully update it. Note the old example still references "captured_stdout". 

# Here's the current code in "support.py":

@contextlib.contextmanager
def captured_output(stream_name):
    """Run the 'with' statement body using a StringIO object in place of a
    specific attribute on the sys module.
    Example use (with 'stream_name=stdout')::

       with captured_stdout() as s:
           print("hello")
       assert s.getvalue() == "hello"
    """
    import io
    orig_stdout = getattr(sys, stream_name)
    setattr(sys, stream_name, io.StringIO())
    try:
        yield getattr(sys, stream_name)
    finally:
        setattr(sys, stream_name, orig_stdout)

def captured_stdout():
    return captured_output("stdout")

# Example for captured_output should now be:

       with captured_output("stdout") as s:
           print("hello")
       assert s.getvalue() == "hello"

# It would be nice to reconcile the online doc versus the docstrings, since it confusing and makes me confused whether captured_stdout is deprecated.
msg99536 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-02-18 22:07
I don't see why the example wouldn't work anymore.  It's just in the wrong function's docs :)
msg135954 - (view) Author: Roundup Robot (python-dev) Date: 2011-05-14 05:44
New changeset 459e2c024420 by Ezio Melotti in branch '2.7':
#7960: fix docstrings for captured_output and captured_stdout.
http://hg.python.org/cpython/rev/459e2c024420

New changeset c2126d89c29b by Ezio Melotti in branch '3.1':
#7960: fix docstrings for captured_output and captured_stdout.
http://hg.python.org/cpython/rev/c2126d89c29b

New changeset 18a192ae6db9 by Ezio Melotti in branch '3.2':
#7960: merge with 3.1.
http://hg.python.org/cpython/rev/18a192ae6db9

New changeset 7517add4aec9 by Ezio Melotti in branch 'default':
#7960: merge with 3.2.
http://hg.python.org/cpython/rev/7517add4aec9
msg135955 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-05-14 05:49
I fixed the docstring, however I think captured_output should be renamed _captured_output, since it only works with sys.stdout/in/err and there are already 3 other functions (in 3.2/3.3) that use captured_output to replace the 3 std* streams.  There's no reason to document and use it elsewhere.
Georg, what do you think?
msg135969 - (view) Author: Roundup Robot (python-dev) Date: 2011-05-14 11:57
New changeset ec35f86efb0d by Ezio Melotti in branch 'default':
Merge with 3.2 and also remove captured_output from __all__ (see #7960).
http://hg.python.org/cpython/rev/ec35f86efb0d
History
Date User Action Args
2011-05-14 11:59:09ezio.melottisetstatus: open -> closed
2011-05-14 11:57:28python-devsetmessages: + msg135969
2011-05-14 05:49:29ezio.melottisetresolution: fixed
messages: + msg135955
stage: resolved
2011-05-14 05:44:24python-devsetnosy: + python-dev
messages: + msg135954
2010-02-18 22:07:29georg.brandlsetassignee: georg.brandl -> ezio.melotti

messages: + msg99536
nosy: + ezio.melotti
2010-02-18 21:23:59mnewmancreate