Documentation of `signal.pause` is incorrect

[teythoon]

Documentation

The documentation of signal.pause just states "Wait until a signal arrives." which is incomplete to the point of being wrong: pause(2) only returns control if a signal is delivered which is not ignored by the process, see the POSIX documentation for pause.

This is easy to demonstrate. Run the following script and send SIGCHLD to it:

$ strace -e pause python3 -c 'import os; print(os.getpid()); import signal; signal.pause()'
2293354
pause()                                 = ? ERESTARTNOHAND (To be restarted if no handler)
--- SIGCHLD {si_signo=SIGCHLD, si_code=SI_USER, si_pid=2293315, si_uid=1000} ---
pause(

On the other hand, if we install a signal handler, SIGCHLD will make pause(2) return:

$ strace -e pause python3 -c 'import os; print(os.getpid()); import signal; signal.signal(signal.SIGCHLD, lambda sig, stack: None); signal.pause()'
2293525
pause()                                 = ? ERESTARTNOHAND (To be restarted if no handler)
--- SIGCHLD {si_signo=SIGCHLD, si_code=SI_USER, si_pid=2293315, si_uid=1000} ---
+++ exited with 0 +++

Linked PRs

• gh-100557: Clarify signal.pause() docs to explain it only wakes on handled signals #148723
• gh-100557: Clarify signal.pause() docs to explain it only wakes on handled signals #148760

[picnixz]

IMO it is correct. The short docstring of pause(2) is exactly "Wait for signal" which means waiting for a signal to be caught. Firing a signal does not mean it is being awaited. The doc is more precise afterwards but for the short summary, I am fine with keeping it that way.

We should only fix the docs (docstring and online) if they are incomplete/incorrect w.r.t. pause(2)