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.

Title: os.waitid() documentation needs TLC
Type: enhancement Stage: patch review
Components: Documentation, Library (Lib) Versions: Python 3.11, Python 3.10, Python 3.9
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, georg.brandl, iritkatriel
Priority: normal Keywords: easy, patch

Created on 2020-09-21 16:41 by georg.brandl, last changed 2022-04-11 14:59 by admin.

Pull Requests
URL Status Linked Edit
PR 22356 open georg.brandl, 2020-09-22 10:35
Messages (2)
msg377263 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2020-09-21 16:41
There are a few points where `os.waitid()` docs need improvement. Current text:

Wait for the completion of one or more child processes. idtype can be P_PID, P_PGID or P_ALL. id specifies the pid to wait on. options is constructed from the ORing of one or more of WEXITED, WSTOPPED or WCONTINUED and additionally may be ORed with WNOHANG or WNOWAIT. The return value is an object representing the data contained in the siginfo_t structure, namely: si_pid, si_uid, si_signo, si_status, si_code or None if WNOHANG is specified and there are no children in a waitable state.

Problems are:

* The given use of the *pid* argument is only for the case of `idtype=P_PID`.  For `P_ALL` it is ignored, and for `P_PGID` it specifies that the child's PGID must be *pid*.

* "One or more child processes" is misleading -- the function waits for until exactly one child process to exit (or aborts with WNOHANG).  Sure, there can be multiple candidate processes, but this should be formulated differently.

* The explanation of *options* is quite cumbersome, it seems to be copied directly from the manpage (where it is laid out much more clearly and with explanation of the different options).

Additionally the flags P_*, W* and CLD_* are just stated as-is, and need explanation in the docs. You should not need to consult the manpage to be able to use the function at all.
msg396516 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2021-06-24 23:44
See also issue38802, issue34278, issue27808.
Date User Action Args
2022-04-11 14:59:35adminsetgithub: 85991
2021-06-24 23:44:30iritkatrielsetnosy: + iritkatriel
messages: + msg396516
2021-06-24 23:43:53iritkatrielsetcomponents: + Library (Lib)
versions: + Python 3.11, - Python 3.8
2020-09-22 10:35:31georg.brandlsetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request21394
2020-09-21 16:41:50georg.brandlcreate