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

Improves the docstring on signal.strsignal to make it explain when it returns a message, None, or when it raises ValueError.

Closes GH-98930

Co-authored-by: Gregory P. Smith <greg@krypto.org>.
(cherry picked from commit 88385b856490a5ce3c99160bde6050638f81f72e)

Co-authored-by: ram vikram singh <ramvikrams243@gmail.com>

diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst
index 2269f50cbaff99114b01a832170549d7608a2041..6cca760583cc30669b0819335ecc9af31b2b3ca9 100644 (file)
--- a/Doc/library/signal.rst
+++ b/Doc/library/signal.rst
@@ -362,9 +362,9 @@ The :mod:`signal` module defines the following functions:
 
 .. function:: strsignal(signalnum)
 
-   Return the system description of the signal *signalnum*, such as
-   "Interrupt", "Segmentation fault", etc. Returns :const:`None` if the signal
-   is not recognized.
+   Returns the description of signal *signalnum*, such as "Interrupt"
+   for :const:`SIGINT`. Returns :const:`None` if *signalnum* has no
+   description. Raises :exc:`ValueError` if *signalnum* is invalid.
 
    .. versionadded:: 3.8
 

diff --git a/Modules/clinic/signalmodule.c.h b/Modules/clinic/signalmodule.c.h
index 9e4a8eb0b998a627b2b13d3d102640b98c7188d2..8b1f316d6d7276cd512a8edb7d769c9e85abe17f 100644 (file)
--- a/Modules/clinic/signalmodule.c.h
+++ b/Modules/clinic/signalmodule.c.h
@@ -205,8 +205,9 @@ PyDoc_STRVAR(signal_strsignal__doc__,
 "\n"
 "Return the system description of the given signal.\n"
 "\n"
-"The return values can be such as \"Interrupt\", \"Segmentation fault\", etc.\n"
-"Returns None if the signal is not recognized.");
+"Returns the description of signal *signalnum*, such as \"Interrupt\"\n"
+"for :const:`SIGINT`. Returns :const:`None` if *signalnum* has no\n"
+"description. Raises :exc:`ValueError` if *signalnum* is invalid.");
 
 #define SIGNAL_STRSIGNAL_METHODDEF    \
     {"strsignal", (PyCFunction)signal_strsignal, METH_O, signal_strsignal__doc__},
@@ -698,4 +699,4 @@ exit:
 #ifndef SIGNAL_PIDFD_SEND_SIGNAL_METHODDEF
     #define SIGNAL_PIDFD_SEND_SIGNAL_METHODDEF
 #endif /* !defined(SIGNAL_PIDFD_SEND_SIGNAL_METHODDEF) */
-/*[clinic end generated code: output=6ca1b70310eecdba input=a9049054013a1b77]*/
+/*[clinic end generated code: output=9b3f9f1ae2ac2b94 input=a9049054013a1b77]*/

diff --git a/Modules/signalmodule.c b/Modules/signalmodule.c
index 0f30b4da036313e01e9a8488acbdb43ee42a2714..60a8067fc8c8ae820c2dc37058ab031f0669e225 100644 (file)
--- a/Modules/signalmodule.c
+++ b/Modules/signalmodule.c
@@ -627,13 +627,14 @@ signal.strsignal
 
 Return the system description of the given signal.
 
-The return values can be such as "Interrupt", "Segmentation fault", etc.
-Returns None if the signal is not recognized.
+Returns the description of signal *signalnum*, such as "Interrupt"
+for :const:`SIGINT`. Returns :const:`None` if *signalnum* has no
+description. Raises :exc:`ValueError` if *signalnum* is invalid.
 [clinic start generated code]*/
 
 static PyObject *
 signal_strsignal_impl(PyObject *module, int signalnum)
-/*[clinic end generated code: output=44e12e1e3b666261 input=b77914b03f856c74]*/
+/*[clinic end generated code: output=44e12e1e3b666261 input=238b335847778bc0]*/
 {
     const char *res;