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

➜

This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

This issue has been migrated to GitHub: https://github.com/python/cpython/issues/87452

classification

Title:	[doc] Clarify that Popen.returncode does not get auto-set when the process terminates
Type:		Stage:
Components:	Documentation, Library (Lib)	Versions:	Python 3.11, Python 3.10, Python 3.9

process

Status:	open	Resolution:
Dependencies:		Superseder:
Assigned To:	docs@python	Nosy List:	docs@python
Priority:	normal	Keywords:	easy

Created on 2021-02-21 15:56 by Antony.Lee, last changed 2022-04-11 14:59 by admin.

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
2022-04-11 14:59:41	admin	set	github: 87452
2021-11-27 19:08:00	Antony.Lee	set	nosy: - Antony.Lee
2021-11-27 18:44:10	iritkatriel	set	keywords: + easy title: Clarify that Popen.returncode does not get auto-set when the process terminates -> [doc] Clarify that Popen.returncode does not get auto-set when the process terminates components: + Library (Lib) versions: + Python 3.9, Python 3.11
2021-02-21 15:56:24	Antony.Lee	create