[doc] Clarify that Popen.returncode does not get auto-set when the process terminates

[anntzer]

BPO	43286

^{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 = None
created_at = <Date 2021-02-21.15:56:24.983>
labels = ['easy', '3.9', '3.10', '3.11', 'library', 'docs']
title = '[doc] Clarify that Popen.returncode does not get auto-set when the process terminates'
updated_at = <Date 2021-11-27.19:08:00.355>
user = 'https://github.com/anntzer'

bugs.python.org fields:

activity = <Date 2021-11-27.19:08:00.355>
actor = 'Antony.Lee'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'Library (Lib)']
creation = <Date 2021-02-21.15:56:24.983>
creator = 'Antony.Lee'
dependencies = []
files = []
hgrepos = []
issue_num = 43286
keywords = ['easy']
message_count = 1.0
messages = ['387463']
nosy_count = 1.0
nosy_names = ['docs@python']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue43286'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

Linked PRs

• gh-87452 Making returncode unreliability explicit #92181
• [3.11] gh-87452: Improve the Popen.returncode docs #103771

[anntzer]

Currently, the documentation for Popen.returncode states

The child return code, set by poll() and wait() (and indirectly by communicate()). A None value indicates that the process hasn’t terminated yet.

A negative value -N indicates that the child was terminated by signal N (POSIX only).

As far back as https://bugs.python.org/issue1727024 it had been suggested that this fails to emphasize an important piece of information, namely that this attribute can be outdated (it is *only* set if poll() or wait() are called; this is not obvious, e.g. returncode could have beeen implemented as a property that auto-calls poll()). I do realize that a strict reading of the docs does suggest the actual behavior, but a bit of explicitness won't hurt...

The wording suggested in https://bugs.python.org/issue1727024 seems clearer to me ("Note: The value stored in returncode may be out-of-date. Use poll() to reliably find the current return code.").

[gpshead]

thanks, good clarification. merged.