Skip to content

Commit 1e32705

Browse files
miss-islingtonbirkenfeld
miss-islington
and
birkenfeld
authored
bpo-41825: restructure docs for the os.wait*() family (GH-22356)
(cherry picked from commit 492dc02) Co-authored-by: Georg Brandl <georg@python.org>
1 parent fce9516 commit 1e32705

File tree

2 files changed

+145
-93
lines changed

2 files changed

+145
-93
lines changed

‎Doc/library/os.rst

+142-93
Original file line numberDiff line numberDiff line change
@@ -4376,83 +4376,50 @@ written in Python, such as a mail server's external command delivery program.
43764376
number is zero); the high bit of the low byte is set if a core file was
43774377
produced.
43784378

4379+
If there are no children that could be waited for, :exc:`ChildProcessError`
4380+
is raised.
4381+
43794382
:func:`waitstatus_to_exitcode` can be used to convert the exit status into an
43804383
exit code.
43814384

43824385
.. availability:: Unix, not Emscripten, not WASI.
43834386

43844387
.. seealso::
43854388

4386-
:func:`waitpid` can be used to wait for the completion of a specific
4387-
child process and has more options.
4389+
The other :func:`!wait*` functions documented below can be used to wait for the
4390+
completion of a specific child process and have more options.
4391+
:func:`waitpid` is the only one also available on Windows.
43884392

4389-
.. function:: waitid(idtype, id, options, /)
43904393

4391-
Wait for the completion of one or more child processes.
4392-
*idtype* can be :data:`P_PID`, :data:`P_PGID`, :data:`P_ALL`, or
4393-
:data:`P_PIDFD` on Linux.
4394-
*id* specifies the pid to wait on.
4395-
*options* is constructed from the ORing of one or more of :data:`WEXITED`,
4396-
:data:`WSTOPPED` or :data:`WCONTINUED` and additionally may be ORed with
4397-
:data:`WNOHANG` or :data:`WNOWAIT`. The return value is an object
4398-
representing the data contained in the :c:type:`siginfo_t` structure, namely:
4399-
:attr:`si_pid`, :attr:`si_uid`, :attr:`si_signo`, :attr:`si_status`,
4400-
:attr:`si_code` or ``None`` if :data:`WNOHANG` is specified and there are no
4401-
children in a waitable state.
4402-
4403-
.. availability:: Unix, not Emscripten, not WASI.
4404-
4405-
.. versionadded:: 3.3
4406-
4407-
.. data:: P_PID
4408-
P_PGID
4409-
P_ALL
4410-
4411-
These are the possible values for *idtype* in :func:`waitid`. They affect
4412-
how *id* is interpreted.
4413-
4414-
.. availability:: Unix, not Emscripten, not WASI.
4415-
4416-
.. versionadded:: 3.3
4417-
4418-
.. data:: P_PIDFD
4419-
4420-
This is a Linux-specific *idtype* that indicates that *id* is a file
4421-
descriptor that refers to a process.
4422-
4423-
.. availability:: Linux >= 5.4
4424-
4425-
.. versionadded:: 3.9
4426-
4427-
.. data:: WEXITED
4428-
WSTOPPED
4429-
WNOWAIT
4394+
.. function:: waitid(idtype, id, options, /)
44304395

4431-
Flags that can be used in *options* in :func:`waitid` that specify what
4432-
child signal to wait for.
4396+
Wait for the completion of a child process.
44334397

4434-
.. availability:: Unix, not Emscripten, not WASI.
4398+
*idtype* can be :data:`P_PID`, :data:`P_PGID`, :data:`P_ALL`, or (on Linux) :data:`P_PIDFD`.
4399+
The interpretation of *id* depends on it; see their individual descriptions.
44354400

4436-
.. versionadded:: 3.3
4401+
*options* is an OR combination of flags. At least one of :data:`WEXITED`,
4402+
:data:`WSTOPPED` or :data:`WCONTINUED` is required;
4403+
:data:`WNOHANG` and :data:`WNOWAIT` are additional optional flags.
44374404

4405+
The return value is an object representing the data contained in the
4406+
:c:type:`!siginfo_t` structure with the following attributes:
44384407

4439-
.. data:: CLD_EXITED
4440-
CLD_KILLED
4441-
CLD_DUMPED
4442-
CLD_TRAPPED
4443-
CLD_STOPPED
4444-
CLD_CONTINUED
4408+
* :attr:`!si_pid` (process ID)
4409+
* :attr:`!si_uid` (real user ID of the child)
4410+
* :attr:`!si_signo` (always :data:`~signal.SIGCHLD`)
4411+
* :attr:`!si_status` (the exit status or signal number, depending on :attr:`!si_code`)
4412+
* :attr:`!si_code` (see :data:`CLD_EXITED` for possible values)
44454413

4446-
These are the possible values for :attr:`si_code` in the result returned by
4447-
:func:`waitid`.
4414+
If :data:`WNOHANG` is specified and there are no matching children in the
4415+
requested state, ``None`` is returned.
4416+
Otherwise, if there are no matching children
4417+
that could be waited for, :exc:`ChildProcessError` is raised.
44484418

44494419
.. availability:: Unix, not Emscripten, not WASI.
44504420

44514421
.. versionadded:: 3.3
44524422

4453-
.. versionchanged:: 3.9
4454-
Added :data:`CLD_KILLED` and :data:`CLD_STOPPED` values.
4455-
44564423

44574424
.. function:: waitpid(pid, options, /)
44584425

@@ -4470,8 +4437,11 @@ written in Python, such as a mail server's external command delivery program.
44704437
``-1``, status is requested for any process in the process group ``-pid`` (the
44714438
absolute value of *pid*).
44724439

4473-
An :exc:`OSError` is raised with the value of errno when the syscall
4474-
returns -1.
4440+
*options* is an OR combination of flags. If it contains :data:`WNOHANG` and
4441+
there are no matching children in the requested state, ``(0, 0)`` is
4442+
returned. Otherwise, if there are no matching children that could be waited
4443+
for, :exc:`ChildProcessError` is raised. Other options that can be used are
4444+
:data:`WUNTRACED` and :data:`WCONTINUED`.
44754445

44764446
On Windows: Wait for completion of a process given by process handle *pid*, and
44774447
return a tuple containing *pid*, and its exit status shifted left by 8 bits
@@ -4484,7 +4454,7 @@ written in Python, such as a mail server's external command delivery program.
44844454
:func:`waitstatus_to_exitcode` can be used to convert the exit status into an
44854455
exit code.
44864456

4487-
.. availability:: Unix, not Emscripten, not WASI.
4457+
.. availability:: Unix, Windows, not Emscripten, not WASI.
44884458

44894459
.. versionchanged:: 3.5
44904460
If the system call is interrupted and the signal handler does not raise an
@@ -4497,9 +4467,9 @@ written in Python, such as a mail server's external command delivery program.
44974467
Similar to :func:`waitpid`, except no process id argument is given and a
44984468
3-element tuple containing the child's process id, exit status indication,
44994469
and resource usage information is returned. Refer to
4500-
:mod:`resource`.\ :func:`~resource.getrusage` for details on resource usage
4501-
information. The option argument is the same as that provided to
4502-
:func:`waitpid` and :func:`wait4`.
4470+
:func:`resource.getrusage` for details on resource usage information. The
4471+
*options* argument is the same as that provided to :func:`waitpid` and
4472+
:func:`wait4`.
45034473

45044474
:func:`waitstatus_to_exitcode` can be used to convert the exit status into an
45054475
exitcode.
@@ -4510,17 +4480,122 @@ written in Python, such as a mail server's external command delivery program.
45104480
.. function:: wait4(pid, options)
45114481

45124482
Similar to :func:`waitpid`, except a 3-element tuple, containing the child's
4513-
process id, exit status indication, and resource usage information is returned.
4514-
Refer to :mod:`resource`.\ :func:`~resource.getrusage` for details on
4515-
resource usage information. The arguments to :func:`wait4` are the same
4516-
as those provided to :func:`waitpid`.
4483+
process id, exit status indication, and resource usage information is
4484+
returned. Refer to :func:`resource.getrusage` for details on resource usage
4485+
information. The arguments to :func:`wait4` are the same as those provided
4486+
to :func:`waitpid`.
45174487

45184488
:func:`waitstatus_to_exitcode` can be used to convert the exit status into an
45194489
exitcode.
45204490

45214491
.. availability:: Unix, not Emscripten, not WASI.
45224492

45234493

4494+
.. data:: P_PID
4495+
P_PGID
4496+
P_ALL
4497+
P_PIDFD
4498+
4499+
These are the possible values for *idtype* in :func:`waitid`. They affect
4500+
how *id* is interpreted:
4501+
4502+
* :data:`!P_PID` - wait for the child whose PID is *id*.
4503+
* :data:`!P_PGID` - wait for any child whose progress group ID is *id*.
4504+
* :data:`!P_ALL` - wait for any child; *id* is ignored.
4505+
* :data:`!P_PIDFD` - wait for the child identified by the file descriptor
4506+
*id* (a process file descriptor created with :func:`pidfd_open`).
4507+
4508+
.. availability:: Unix, not Emscripten, not WASI.
4509+
4510+
.. note:: :data:`!P_PIDFD` is only available on Linux >= 5.4.
4511+
4512+
.. versionadded:: 3.3
4513+
.. versionadded:: 3.9
4514+
The :data:`!P_PIDFD` constant.
4515+
4516+
4517+
.. data:: WCONTINUED
4518+
4519+
This *options* flag for :func:`waitpid`, :func:`wait3`, :func:`wait4`, and
4520+
:func:`waitid` causes child processes to be reported if they have been
4521+
continued from a job control stop since they were last reported.
4522+
4523+
.. availability:: Unix, not Emscripten, not WASI.
4524+
4525+
4526+
.. data:: WEXITED
4527+
4528+
This *options* flag for :func:`waitid` causes child processes that have terminated to
4529+
be reported.
4530+
4531+
The other ``wait*`` functions always report children that have terminated,
4532+
so this option is not available for them.
4533+
4534+
.. availability:: Unix, not Emscripten, not WASI.
4535+
4536+
.. versionadded:: 3.3
4537+
4538+
4539+
.. data:: WSTOPPED
4540+
4541+
This *options* flag for :func:`waitid` causes child processes that have been stopped
4542+
by the delivery of a signal to be reported.
4543+
4544+
This option is not available for the other ``wait*`` functions.
4545+
4546+
.. availability:: Unix, not Emscripten, not WASI.
4547+
4548+
.. versionadded:: 3.3
4549+
4550+
4551+
.. data:: WUNTRACED
4552+
4553+
This *options* flag for :func:`waitpid`, :func:`wait3`, and :func:`wait4` causes
4554+
child processes to also be reported if they have been stopped but their
4555+
current state has not been reported since they were stopped.
4556+
4557+
This option is not available for :func:`waitid`.
4558+
4559+
.. availability:: Unix, not Emscripten, not WASI.
4560+
4561+
4562+
.. data:: WNOHANG
4563+
4564+
This *options* flag causes :func:`waitpid`, :func:`wait3`, :func:`wait4`, and
4565+
:func:`waitid` to return right away if no child process status is available
4566+
immediately.
4567+
4568+
.. availability:: Unix, not Emscripten, not WASI.
4569+
4570+
4571+
.. data:: WNOWAIT
4572+
4573+
This *options* flag causes :func:`waitid` to leave the child in a waitable state, so that
4574+
a later :func:`!wait*` call can be used to retrieve the child status information again.
4575+
4576+
This option is not available for the other ``wait*`` functions.
4577+
4578+
.. availability:: Unix, not Emscripten, not WASI.
4579+
4580+
4581+
.. data:: CLD_EXITED
4582+
CLD_KILLED
4583+
CLD_DUMPED
4584+
CLD_TRAPPED
4585+
CLD_STOPPED
4586+
CLD_CONTINUED
4587+
4588+
These are the possible values for :attr:`!si_code` in the result returned by
4589+
:func:`waitid`.
4590+
4591+
.. availability:: Unix, not Emscripten, not WASI.
4592+
4593+
.. versionadded:: 3.3
4594+
4595+
.. versionchanged:: 3.9
4596+
Added :data:`CLD_KILLED` and :data:`CLD_STOPPED` values.
4597+
4598+
45244599
.. function:: waitstatus_to_exitcode(status)
45254600

45264601
Convert a wait status to an exit code.
@@ -4553,32 +4628,6 @@ written in Python, such as a mail server's external command delivery program.
45534628
.. versionadded:: 3.9
45544629

45554630

4556-
.. data:: WNOHANG
4557-
4558-
The option for :func:`waitpid` to return immediately if no child process status
4559-
is available immediately. The function returns ``(0, 0)`` in this case.
4560-
4561-
.. availability:: Unix, not Emscripten, not WASI.
4562-
4563-
4564-
.. data:: WCONTINUED
4565-
4566-
This option causes child processes to be reported if they have been continued
4567-
from a job control stop since their status was last reported.
4568-
4569-
.. availability:: Unix, not Emscripten, not WASI.
4570-
4571-
Some Unix systems.
4572-
4573-
4574-
.. data:: WUNTRACED
4575-
4576-
This option causes child processes to be reported if they have been stopped but
4577-
their current state has not been reported since they were stopped.
4578-
4579-
.. availability:: Unix, not Emscripten, not WASI.
4580-
4581-
45824631
The following functions take a process status code as returned by
45834632
:func:`system`, :func:`wait`, or :func:`waitpid` as a parameter. They may be
45844633
used to determine the disposition of a process.

‎Misc/NEWS.d/next/Documentation/2020-09-22-12-32-16.bpo-41825.npcaCb.rst

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Restructured the documentation for the :func:`os.wait* <os.wait>` family of functions,
2+
and improved the docs for :func:`os.waitid` with more explanation of the
3+
possible argument constants.

0 commit comments

Comments
 (0)