classification
Title: Popen.communicate documentation does not say how to get the return code
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.10, Python 3.9, Python 3.8
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, gdr@garethrees.org, miss-islington, terry.reedy
Priority: normal Keywords: patch

Created on 2020-05-21 07:34 by gdr@garethrees.org, last changed 2020-06-24 03:43 by terry.reedy. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 20283 merged gdr@garethrees.org, 2020-05-21 07:53
PR 21105 merged miss-islington, 2020-06-24 03:12
PR 21106 merged miss-islington, 2020-06-24 03:12
Messages (10)
msg369502 - (view) Author: Gareth Rees (gdr@garethrees.org) * (Python triager) Date: 2020-05-21 07:34
When using subprocess.Popen.communicate(), it is natural to wonder how to get
the exit code of the subprocess. However, the documentation [1] says:

    Interact with process: Send data to stdin. Read data from stdout and
    stderr, until end-of-file is reached. Wait for process to terminate. The
    optional input argument should be data to be sent to the child process, or
    None, if no data should be sent to the child. If streams were opened in
    text mode, input must be a string. Otherwise, it must be bytes.

    communicate() returns a tuple (stdout_data, stderr_data). The data will be
    strings if streams were opened in text mode; otherwise, bytes.

If you can guess that communicate() might set returncode, then you can find
what you need in the documentation for that attribute [2]:

    The child return code, set by poll() and wait() (and indirectly by
    communicate()).

I suggest that the documentation for communicate() be updated to mention that
it sets the returncode attribute. This would be consistent with poll() and
wait(), which already mention this.

[1]: https://docs.python.org/3/library/subprocess.html#subprocess.Popen.communicate
[2]: https://docs.python.org/3/library/subprocess.html#subprocess.Popen.returncode
msg369697 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2020-05-23 07:30
This is not a security issue.
msg369700 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2020-05-23 07:45
Can you attach a script or post an interactive session, with both success and failure, showing that returncode is set appropriately after reading output?  Possible calls: '''python -c "print('Success')"''', "raise Exception('Failure')".  Or point to a test in test_subprocess.
msg369702 - (view) Author: Gareth Rees (gdr@garethrees.org) * (Python triager) Date: 2020-05-23 08:23
The following test cases in test_subprocess.py call the communicate() method and then immediately assert that returncode attribute has the expected value:

* test_stdout_none
* test_stderr_redirect_with_no_stdout_redirect
* test_stdout_filedes_of_stdout
* test_communicate_stdin
* test_universal_newlines_communicate_stdin
* test_universal_newlines_communicate_input_none
* test_universal_newlines_communicate_stdin_stdout_stderr
* test_nonexisting_with_pipes
* test_wait_when_sigchild_ignored
* test_startupinfo_copy
* test_close_fds_with_stdio
* test_communicate_stdin

You'll see that some of these test for success (returncode == 0) and some for failure (returncode == 1). This seems like adequate test coverage to me, but if something is missing, let me know.
msg372203 - (view) Author: Gareth Rees (gdr@garethrees.org) * (Python triager) Date: 2020-06-23 20:12
Is there anything I can do to move this forward?
msg372224 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2020-06-24 01:32
Will merge after CI passes the addition of 'the'.
msg372228 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2020-06-24 03:12
New changeset bf2e515fa43406d4bd9c4c53ecc9364034d8f9f6 by Gareth Rees in branch 'master':
bpo-40707: Document that Popen.communicate sets the returncode attribute (GH-20283)
https://github.com/python/cpython/commit/bf2e515fa43406d4bd9c4c53ecc9364034d8f9f6
msg372229 - (view) Author: miss-islington (miss-islington) Date: 2020-06-24 03:19
New changeset 02d5c74f89709672baa866fcdd04278e59328351 by Miss Islington (bot) in branch '3.9':
bpo-40707: Document that Popen.communicate sets the returncode attribute (GH-20283)
https://github.com/python/cpython/commit/02d5c74f89709672baa866fcdd04278e59328351
msg372230 - (view) Author: miss-islington (miss-islington) Date: 2020-06-24 03:19
New changeset 4f5dde463b588fc97cacb4a1905eb422b16daa37 by Miss Islington (bot) in branch '3.8':
bpo-40707: Document that Popen.communicate sets the returncode attribute (GH-20283)
https://github.com/python/cpython/commit/4f5dde463b588fc97cacb4a1905eb422b16daa37
msg372231 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2020-06-24 03:43
Thanks for the fix.
History
Date User Action Args
2020-06-24 03:43:28terry.reedysetstatus: open -> closed
resolution: fixed
messages: + msg372231

stage: patch review -> resolved
2020-06-24 03:19:43miss-islingtonsetmessages: + msg372230
2020-06-24 03:19:18miss-islingtonsetmessages: + msg372229
2020-06-24 03:12:39miss-islingtonsetpull_requests: + pull_request20273
2020-06-24 03:12:30miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request20272
2020-06-24 03:12:20terry.reedysetmessages: + msg372228
2020-06-24 01:32:05terry.reedysetmessages: + msg372224
versions: - Python 3.7
2020-06-23 20:12:44gdr@garethrees.orgsetmessages: + msg372203
2020-05-23 08:23:19gdr@garethrees.orgsetmessages: + msg369702
2020-05-23 07:45:08terry.reedysetmessages: + msg369700
2020-05-23 07:30:59terry.reedysetnosy: + terry.reedy

messages: + msg369697
versions: - Python 3.5, Python 3.6
2020-05-21 07:53:02gdr@garethrees.orgsetkeywords: + patch
stage: patch review
pull_requests: + pull_request19559
2020-05-21 07:34:10gdr@garethrees.orgcreate