[Python-checkins] bpo-28206: Document signals Handlers, Sigmasks and Signals enums (GH-28628)

[JulienPalard]

https://github.com/python/cpython/commit/9be930f9b169fb3d92693670ae069df902709b83
commit: 9be930f9b169fb3d92693670ae069df902709b83
branch: main
author: Bibo-Joshi <22366557+Bibo-Joshi at users.noreply.github.com>
committer: JulienPalard <julien at palard.fr>
date: 2021-10-04T13:09:40+02:00
summary:

bpo-28206: Document signals Handlers, Sigmasks and Signals enums (GH-28628)

Co-authored-by: desbma <desbma at users.noreply.github.com>

files:
M Doc/library/signal.rst

diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst
index 84a569d03eb29..63821866a012b 100644
--- a/Doc/library/signal.rst
+++ b/Doc/library/signal.rst
@@ -68,10 +68,34 @@ Module contents
    signal (SIG*), handler (:const:`SIG_DFL`, :const:`SIG_IGN`) and sigmask
    (:const:`SIG_BLOCK`, :const:`SIG_UNBLOCK`, :const:`SIG_SETMASK`)
    related constants listed below were turned into
-   :class:`enums <enum.IntEnum>`.
+   :class:`enums <enum.IntEnum>` (:class:`Signals`, :class:`Handlers` and :class:`Sigmasks` respectively).
    :func:`getsignal`, :func:`pthread_sigmask`, :func:`sigpending` and
    :func:`sigwait` functions return human-readable
-   :class:`enums <enum.IntEnum>`.
+   :class:`enums <enum.IntEnum>` as :class:`Signals` objects.
+
+
+The signal module defines three enums:
+
+.. class:: Signals
+
+   :class:`enum.IntEnum` collection of SIG* constants and the CTRL_* constants.
+
+   .. versionadded:: 3.5
+
+.. class:: Handlers
+
+   :class:`enum.IntEnum` collection the constants :const:`SIG_DFL` and :const:`SIG_IGN`.
+
+   .. versionadded:: 3.5
+
+.. class:: Sigmasks
+
+   :class:`enum.IntEnum` collection the constants :const:`SIG_BLOCK`, :const:`SIG_UNBLOCK` and :const:`SIG_SETMASK`.
+
+   Availability: Unix. See the man page :manpage:`sigprocmask(3)` and
+   :manpage:`pthread_sigmask(3)` for further information.
+
+   .. versionadded:: 3.5
 
 
 The variables defined in the :mod:`signal` module are:
@@ -618,8 +642,8 @@ The :mod:`signal` module defines the following functions:
 
 .. _signal-example:
 
-Example
--------
+Examples
+--------
 
 Here is a minimal example program. It uses the :func:`alarm` function to limit
 the time spent waiting to open a file; this is useful if the file is for a
@@ -631,7 +655,8 @@ be sent, and the handler raises an exception. ::
    import signal, os
 
    def handler(signum, frame):
-       print('Signal handler called with signal', signum)
+       signame = signal.Signals(signum).name
+       print(f'Signal handler called with signal {signame} ({signum})')
        raise OSError("Couldn't open device!")
 
    # Set the signal handler and a 5-second alarm