Documentation

The documentation for signal.strsignal(...) says Returns None if the signal is not recognized. This a misleading way to describe what actually happens.

Suggested better wording would be Throws ValueError if signalnum is invalid, and returns None if there is no canonical name for signalnum for the platform.

From reading the implementation in cpython, this is my best understanding of what happens.

If the signal number is less than 1 or greater (or equal) to signal.NSIG (ie 65) a ValueError exception is thrown. (ie signal.strsignal(65) throws a ValueError exception and does not return None). This scenario is what I found most confusing about the documentation.

If there is no suitable canonical name for the signal, then signal.strsignal(..) will return None. For example on Linux, signal 32 doesn't have a canonical name. In that case signal.strsignal(...) does return None. I am not an expert in Linux, but I did the following test, and it appears to me that signal 32 is pretty normal behaving signal, its usage is just deprecated and no longer has a standard name.

$ bash
$ echo $$  # Get pid of current shell
120846
# In another terminal
$ kill -s 65 120846  # Send signal 65 which is an invalid signal, and show that nothing happens.
-bash: kill: 65: invalid signal specification
$ kill -s 32 120846  # Send signal 32 which is a valid signal with no canonical name, and show that signal is sent
# Above shell exits with message
Unknown signal 32

It is pretty easy to verify that what I said about the cpython implementation is correct if HAVE_STRSIGNAL is true, however for HAVE_STRSIGNAL false, it depends a lot more on what strsignal() (from glibc) returns.

From looking at the implementation in glibc glibc returns a string with a name of the signal or "Unknown signal". If glibc "Unknown signal" then cpython will return None.

The one caveat is that I am not fully clear how well my analysis carries over to the Windows platform. But at least for the Linux platform, I do feel that my suggested wording Throws ValueError if signalnum is invalid, and returns None if there is no canonical name for signalnum for the platform. is a good representation of what happens.

• PR: gh-98930: improve the docstring of signal.strsignal #99290

• PR: [3.11] gh-98930: improve the docstring of signal.strsignal (GH-99290) #99449