Issue 43286: Clarify that Popen.returncode does not get auto-set when the process terminates

classification

Title:	Clarify that Popen.returncode does not get auto-set when the process terminates
Type:		Stage:
Components:	Documentation	Versions:	Python 3.10

process

Status:	open	Resolution:
Dependencies:		Superseder:
Assigned To:	docs@python	Nosy List:	Antony.Lee, docs@python
Priority:	normal	Keywords:

Created on 2021-02-21 15:56 by Antony.Lee, last changed 2021-02-21 15:56 by Antony.Lee.

Messages (1)
msg387463 - (view)	Author: Antony Lee (Antony.Lee) *	Date: 2021-02-21 15:56
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.").

msg387463 - (view)

Author: Antony Lee (Antony.Lee) *

Date: 2021-02-21 15:56

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.").

History
Date	User	Action	Args
2021-02-21 15:56:24	Antony.Lee	create