New submission from Michael Yagliyan :
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.
--
assignee: docs@python
components: Documentation
messages: 356627
nosy: bbmmy, docs@python
priority: normal
severity: normal
status: open
title: Clearer wording of os.WNOHANG documentation to avoid misinterpretation
type: enhancement
versions: Python 2.7, Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9
___
Python tracker
<https://bugs.python.org/issue38802>
___
___
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
