classification
Title: test.support.captured_stderr, captured_stdin not documented
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: fdrake Nosy List: dmi.baranov, docs@python, fdrake, python-dev, r.david.murray, serhiy.storchaka
Priority: normal Keywords: easy, patch

Created on 2013-05-15 21:30 by fdrake, last changed 2013-07-11 20:48 by dmi.baranov. This issue is now closed.

Files
File name Uploaded Description Edit
issue17987.patch dmi.baranov, 2013-05-27 17:47 added docstrings, fix in captured_stdout docstring review
issue17987_2.patch dmi.baranov, 2013-05-27 18:09 review
issue17987_3.patch dmi.baranov, 2013-05-28 11:44 review
issue17987_4.patch dmi.baranov, 2013-05-28 13:04 review
issue17987_5.patch dmi.baranov, 2013-05-28 14:41 review
issue17987_6.patch dmi.baranov, 2013-05-30 16:31 review
Repositories containing patches
added description and samples to Doc/library/test.rst
Messages (20)
msg189311 - (view) Author: Fred Drake (fdrake) (Python committer) Date: 2013-05-15 21:30
The captured_stderr and captured_stdin context managers aren't documented, and should be.
msg190147 - (view) Author: Dmi Baranov (dmi.baranov) * Date: 2013-05-27 17:47
Added a patch
msg190150 - (view) Author: Dmi Baranov (dmi.baranov) * Date: 2013-05-27 18:09
Sorry for noise, missed changes in Doc/library/test.rst. Updated patch added
msg190151 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-05-27 18:30
Print to stdin?
msg190152 - (view) Author: Dmi Baranov (dmi.baranov) * Date: 2013-05-27 18:51
Yes, I agree that this is not an obvious sample, but:

$ ./python -m test.test_support | grep test_captured_stdin
test_captured_stdin (__main__.TestSupport) ... ok

What's about that?

with captured_stdin() as s:
    s.write('hello\n')
    s.seek(0)
    captured = input()

assert captured == 'hello'
msg190191 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-05-28 10:22
I believe it is a mechanical mistake in test_captured_stdin().
msg190196 - (view) Author: Dmi Baranov (dmi.baranov) * Date: 2013-05-28 11:44
`captured_stdin` test changed, docs updated.
msg190198 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-05-28 12:12
I think it will be better to describe all three functions together (as sys.stdin/stdout/stderr).

.. function:: captured_stdin()
              captured_stdout()
              captured_stderr()

... description ...

   Example use::

      ... example for captured_stdin() ...

      ... example for captured_stdout() ...
msg190199 - (view) Author: Fred Drake (fdrake) (Python committer) Date: 2013-05-28 12:25
Joining the documentation for captured_stderr and captured_stdout makes
sense, as they can really use a single example, and the usage is
completely parallel.

I'd rather see captured_stdin handled separately, perhaps with some
additional comments in the example, to emphasize the intended usage
pattern:

     with support.captured_stdin() as s:
         # Prepare simulated input:
         s.write('hello\n')
         s.seek(0)
         # Call test code that consumes from stdin:
         captured = input()
     self.assertEqual(captured, "hello")
msg190204 - (view) Author: Dmi Baranov (dmi.baranov) * Date: 2013-05-28 13:04
Amended, as discussed. Also changed documentation from "how to use a context managers with that" to "how it works".
msg190207 - (view) Author: Fred Drake (fdrake) (Python committer) Date: 2013-05-28 13:27
+1 for issue17987_4.patch

Thanks, Dmi!
msg190209 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-05-28 13:42
> I'd rather see captured_stdin handled separately, perhaps with some
> additional comments in the example, to emphasize the intended usage
> pattern:

However all three functions share a description.

sys.stdin also has totally different usage pattern than sys.stdout/stderr, but it's documentation joined with documentation of all sys.std* streams.

I think functions should be mentioned in order of it's fd numbers (0 - stdin, 1
- stdout, 2 - stderr). And example for capture_stdout() looks more appropriate then for capture_stderr().
msg190215 - (view) Author: Dmi Baranov (dmi.baranov) * Date: 2013-05-28 14:41
Thanks for review, Serhiy - updated.
msg190286 - (view) Author: Dmi Baranov (dmi.baranov) * Date: 2013-05-29 10:52
Fred or Serhiy - any news here? I'm signed Contributor Agreement few days ago, just waiting a change in my profile here, please don't worry about copyright :-)
msg190298 - (view) Author: Fred Drake (fdrake) (Python committer) Date: 2013-05-29 12:32
From v5 of the patch:
+   A context managers that temporarily replaces the :data:`sys.stdin` /
+   :data:`sys.stdout` / :data:`sys.stderr` stream with :class:`io.StringIO`
+   object.

I'd go with singular nouns instead of trying to map across them with plurals:

  Context manager that temporarily replaces the named stream with an
  :class:`io.StringIO` object.
msg190302 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-05-29 12:48
LGTM with Fred's suggestion.
msg190370 - (view) Author: Dmi Baranov (dmi.baranov) * Date: 2013-05-30 16:31
Amended
msg192879 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-07-11 16:30
New changeset af2416c2e27c by R David Murray in branch '3.3':
#17987: properly document support.captured_xxx.
http://hg.python.org/cpython/rev/af2416c2e27c

New changeset d0f7f1996001 by R David Murray in branch 'default':
Merge #17987: properly document support.captured_xxx.
http://hg.python.org/cpython/rev/d0f7f1996001
msg192880 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-07-11 16:30
Thanks, Dmi.
msg192903 - (view) Author: Dmi Baranov (dmi.baranov) * Date: 2013-07-11 20:48
Yeah, my first patch applied :) thanks, David
History
Date User Action Args
2013-07-11 20:48:41dmi.baranovsetmessages: + msg192903
2013-07-11 16:30:52r.david.murraysetstatus: open -> closed

nosy: + r.david.murray
messages: + msg192880

resolution: fixed
stage: needs patch -> resolved
2013-07-11 16:30:09python-devsetnosy: + python-dev
messages: + msg192879
2013-05-30 16:31:09dmi.baranovsetfiles: + issue17987_6.patch

messages: + msg190370
2013-05-29 12:48:46serhiy.storchakasetassignee: docs@python -> fdrake
messages: + msg190302
2013-05-29 12:32:00fdrakesetmessages: + msg190298
2013-05-29 10:52:23dmi.baranovsetmessages: + msg190286
2013-05-28 14:41:39dmi.baranovsetfiles: + issue17987_5.patch

messages: + msg190215
2013-05-28 13:42:33serhiy.storchakasetmessages: + msg190209
2013-05-28 13:27:56fdrakesetmessages: + msg190207
2013-05-28 13:18:35eli.benderskysetnosy: - eli.bendersky
2013-05-28 13:04:48dmi.baranovsetfiles: + issue17987_4.patch

messages: + msg190204
2013-05-28 12:25:35fdrakesetmessages: + msg190199
2013-05-28 12:12:32serhiy.storchakasetmessages: + msg190198
2013-05-28 11:44:49dmi.baranovsetfiles: + issue17987_3.patch

messages: + msg190196
2013-05-28 10:22:05serhiy.storchakasetnosy: + eli.bendersky

messages: + msg190191
versions: - Python 3.5
2013-05-27 18:51:11dmi.baranovsetmessages: + msg190152
2013-05-27 18:30:20serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg190151
2013-05-27 18:09:39dmi.baranovsetfiles: + issue17987_2.patch
hgrepos: + hgrepo192
messages: + msg190150
2013-05-27 17:47:42dmi.baranovsetfiles: + issue17987.patch

nosy: + dmi.baranov
messages: + msg190147

keywords: + patch
2013-05-15 21:30:23fdrakecreate