classification
Title: Clearer wording of os.WNOHANG documentation to avoid misinterpretation
Type: enhancement Stage:
Components: Documentation, Library (Lib) Versions: Python 3.9, Python 3.8, Python 3.7, Python 3.6, Python 3.5, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: bbmmy, docs@python, iritkatriel
Priority: normal Keywords:

Created on 2019-11-14 21:52 by bbmmy, last changed 2021-06-24 23:45 by iritkatriel.

Messages (3)
msg356627 - (view) Author: Michael Yagliyan (bbmmy) Date: 2019-11-14 21:52
For versions 2.7 through 3.9 of https://docs.python.org/3/library/os.html, os.WNOHANG is described as returning (0, 0) when no child process status is immediately available.

However, both os.wait3() and os.wait4() return 3-element tuples and are described as being similar to os.waitpid().  This, combined with the os.WNOHANG documentation being somewhat open to interpretation, makes it very easy to conclude (incorrectly) that wait3(WNOHANG) and wait4(WNOHANG) would return (0, 0) when no child process status is immediately available.  In fact, they would return a 3-element tuple with the first 2 elements being 0.

I suggest rephrasing the os.WNOHANG documentation to the following (or something similar):

"The option for waitpid() to return immediately if no child process status is available immediately, in which case the function returns (0, 0).  Correspondingly, wait3() and wait4() would return 3-element tuples with the first 2 elements being 0 and the last being a default-constructed resource usage information object."

Unfortunately that last part about the default-constructed resource usage information object is only true after this recent bug fix:
https://github.com/python/cpython/pull/15111/files

So I'll leave it to y'all to decide how to update the documentation since my proposed phrasing is dependent on that bug fix.
msg356628 - (view) Author: Michael Yagliyan (bbmmy) Date: 2019-11-14 22:08
If this documentation fix will not be backported (i.e. it will only apply to versions *after* the aforementioned bug fix) then a more precise way to phrase that last part would be:

"...with the first 2 elements being 0 and the last being an all-zero resource usage information object."
msg396517 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2021-06-24 23:45
see also issue41825, issue34278, issue27808.
History
Date User Action Args
2021-06-24 23:45:41iritkatrielsetnosy: + iritkatriel
messages: + msg396517
components: + Library (Lib)
2019-11-14 22:08:37bbmmysetmessages: + msg356628
2019-11-14 21:52:21bbmmycreate