[issue17987] test.support.captured_stderr, captured_stdin not documented
New submission from Fred L. Drake, Jr.: The captured_stderr and captured_stdin context managers aren't documented, and should be. ---------- assignee: docs@python components: Documentation keywords: easy messages: 189311 nosy: docs@python, fdrake priority: normal severity: normal stage: needs patch status: open title: test.support.captured_stderr, captured_stdin not documented type: enhancement versions: Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Dmi Baranov added the comment: Added a patch ---------- keywords: +patch nosy: +dmi.baranov Added file: http://bugs.python.org/file30387/issue17987.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Dmi Baranov added the comment: Sorry for noise, missed changes in Doc/library/test.rst. Updated patch added ---------- hgrepos: +192 Added file: http://bugs.python.org/file30389/issue17987_2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Serhiy Storchaka added the comment: Print to stdin? ---------- nosy: +serhiy.storchaka _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Dmi Baranov added the comment: 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' ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Serhiy Storchaka added the comment: I believe it is a mechanical mistake in test_captured_stdin(). ---------- nosy: +eli.bendersky versions: -Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Dmi Baranov added the comment: `captured_stdin` test changed, docs updated. ---------- Added file: http://bugs.python.org/file30396/issue17987_3.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Serhiy Storchaka added the comment: 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() ... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Fred L. Drake, Jr. added the comment: 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") ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Dmi Baranov added the comment: Amended, as discussed. Also changed documentation from "how to use a context managers with that" to "how it works". ---------- Added file: http://bugs.python.org/file30398/issue17987_4.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Changes by Eli Bendersky <eliben@gmail.com>: ---------- nosy: -eli.bendersky _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Fred L. Drake, Jr. added the comment: +1 for issue17987_4.patch Thanks, Dmi! ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Serhiy Storchaka added the comment:
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(). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Dmi Baranov added the comment: Thanks for review, Serhiy - updated. ---------- Added file: http://bugs.python.org/file30400/issue17987_5.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Dmi Baranov added the comment: 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 :-) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Fred L. Drake, Jr. added the comment: >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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Serhiy Storchaka added the comment: LGTM with Fred's suggestion. ---------- assignee: docs@python -> fdrake _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Dmi Baranov added the comment: Amended ---------- Added file: http://bugs.python.org/file30430/issue17987_6.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Roundup Robot added the comment: 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 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
R. David Murray added the comment: Thanks, Dmi. ---------- nosy: +r.david.murray resolution: -> fixed stage: needs patch -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Dmi Baranov added the comment: Yeah, my first patch applied :) thanks, David ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Dmi Baranov added the comment: Added a patch ---------- keywords: +patch nosy: +dmi.baranov Added file: http://bugs.python.org/file30387/issue17987.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Dmi Baranov added the comment: Sorry for noise, missed changes in Doc/library/test.rst. Updated patch added ---------- hgrepos: +192 Added file: http://bugs.python.org/file30389/issue17987_2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Serhiy Storchaka added the comment: Print to stdin? ---------- nosy: +serhiy.storchaka _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Dmi Baranov added the comment: 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' ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Serhiy Storchaka added the comment: I believe it is a mechanical mistake in test_captured_stdin(). ---------- nosy: +eli.bendersky versions: -Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Dmi Baranov added the comment: `captured_stdin` test changed, docs updated. ---------- Added file: http://bugs.python.org/file30396/issue17987_3.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Serhiy Storchaka added the comment: 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() ... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Fred L. Drake, Jr. added the comment: 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") ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Dmi Baranov added the comment: Amended, as discussed. Also changed documentation from "how to use a context managers with that" to "how it works". ---------- Added file: http://bugs.python.org/file30398/issue17987_4.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Changes by Eli Bendersky <eliben@gmail.com>: ---------- nosy: -eli.bendersky _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Fred L. Drake, Jr. added the comment: +1 for issue17987_4.patch Thanks, Dmi! ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Serhiy Storchaka added the comment:
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(). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Dmi Baranov added the comment: Thanks for review, Serhiy - updated. ---------- Added file: http://bugs.python.org/file30400/issue17987_5.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Dmi Baranov added the comment: 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 :-) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Fred L. Drake, Jr. added the comment: >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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Serhiy Storchaka added the comment: LGTM with Fred's suggestion. ---------- assignee: docs@python -> fdrake _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Dmi Baranov added the comment: Amended ---------- Added file: http://bugs.python.org/file30430/issue17987_6.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Roundup Robot added the comment: 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 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
R. David Murray added the comment: Thanks, Dmi. ---------- nosy: +r.david.murray resolution: -> fixed stage: needs patch -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
Dmi Baranov added the comment: Yeah, my first patch applied :) thanks, David ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________
participants (6)
-
Dmi Baranov -
Eli Bendersky
-
Fred L. Drake, Jr.
-
R. David Murray
-
Roundup Robot
-
Serhiy Storchaka