bpo-38920: Add audit hooks for when sys.excepthook and sys.unraisable hooks are invoked (GH-17392)

Also fixes some potential segfaults in unraisable hook handling.

1 files changed, 22 insertions, 1 deletions

diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 2f33445..a824fb9 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -36,13 +36,18 @@ always available.
    .. audit-event:: sys.addaudithook "" sys.addaudithook
 
       Raise an auditing event ``sys.addaudithook`` with no arguments. If any
-      existing hooks raise an exception derived from :class:`Exception`, the
+      existing hooks raise an exception derived from :class:`RuntimeError`, the
       new hook will not be added and the exception suppressed. As a result,
       callers cannot assume that their hook has been added unless they control
       all existing hooks.
 
    .. versionadded:: 3.8
 
+   .. versionchanged:: 3.8.1
+
+      Exceptions derived from :class:`Exception` but not :class:`RuntimeError`
+      are no longer suppressed.
+
    .. impl-detail::
 
       When tracing is enabled (see :func:`settrace`), Python hooks are only
@@ -308,6 +313,15 @@ always available.
    before the program exits.  The handling of such top-level exceptions can be
    customized by assigning another three-argument function to ``sys.excepthook``.
 
+   .. audit-event:: sys.excepthook hook,type,value,traceback sys.excepthook
+
+      Raise an auditing event ``sys.excepthook`` with arguments ``hook``,
+      ``type``, ``value``, ``traceback`` when an uncaught exception occurs.
+      If no hook has been set, ``hook`` may be ``None``. If any hook raises
+      an exception derived from :class:`RuntimeError` the call to the hook will
+      be suppressed. Otherwise, the audit hook exception will be reported as
+      unraisable and ``sys.excepthook`` will be called.
+
    .. seealso::
 
       The :func:`sys.unraisablehook` function handles unraisable exceptions
@@ -1540,6 +1554,13 @@ always available.
 
    See also :func:`excepthook` which handles uncaught exceptions.
 
+   .. audit-event:: sys.unraisablehook hook,unraisable sys.unraisablehook
+
+      Raise an auditing event ``sys.unraisablehook`` with arguments
+      ``hook``, ``unraisable`` when an exception that cannot be handled occurs.
+      The ``unraisable`` object is the same as what will be passed to the hook.
+      If no hook has been set, ``hook`` may be ``None``.
+
    .. versionadded:: 3.8
 
 .. data:: version