Popen.communicate documentation does not say how to get the return code

[gareth-rees]

BPO	40707
Nosy	@terryjreedy, @gareth-rees, @miss-islington
PRs	bpo-40707: Document that Popen.communicate sets the returncode attribute #20283 [3.9] bpo-40707: Document that Popen.communicate sets the returncode attribute (GH-20283) #21105 [3.8] bpo-40707: Document that Popen.communicate sets the returncode attribute (GH-20283) #21106

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2020-06-24.03:43:28.607>
created_at = <Date 2020-05-21.07:34:10.236>
labels = ['type-feature', '3.8', '3.9', '3.10', 'docs']
title = 'Popen.communicate documentation does not say how to get the return code'
updated_at = <Date 2020-06-24.03:43:28.606>
user = 'https://github.com/gareth-rees'

bugs.python.org fields:

activity = <Date 2020-06-24.03:43:28.606>
actor = 'terry.reedy'
assignee = 'docs@python'
closed = True
closed_date = <Date 2020-06-24.03:43:28.607>
closer = 'terry.reedy'
components = ['Documentation']
creation = <Date 2020-05-21.07:34:10.236>
creator = 'gdr@garethrees.org'
dependencies = []
files = []
hgrepos = []
issue_num = 40707
keywords = ['patch']
message_count = 10.0
messages = ['369502', '369697', '369700', '369702', '372203', '372224', '372228', '372229', '372230', '372231']
nosy_count = 4.0
nosy_names = ['terry.reedy', 'docs@python', 'gdr@garethrees.org', 'miss-islington']
pr_nums = ['20283', '21105', '21106']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue40707'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

[gareth-rees]

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.

[terryjreedy]

This is not a security issue.

[terryjreedy]

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.

[gareth-rees]

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.

[gareth-rees]

Is there anything I can do to move this forward?

[terryjreedy]

Will merge after CI passes the addition of 'the'.

[terryjreedy]

New changeset bf2e515 by Gareth Rees in branch 'master':
bpo-40707: Document that Popen.communicate sets the returncode attribute (GH-20283)
bf2e515

[miss-islington]

New changeset 02d5c74 by Miss Islington (bot) in branch '3.9':
bpo-40707: Document that Popen.communicate sets the returncode attribute (GH-20283)
02d5c74

[miss-islington]

New changeset 4f5dde4 by Miss Islington (bot) in branch '3.8':
bpo-40707: Document that Popen.communicate sets the returncode attribute (GH-20283)
4f5dde4

[terryjreedy]

Thanks for the fix.