Append the callable hook to the list of active auditing hooks for the
current (sub)interpreter.
When an auditing event is raised through the sys.audit() function, each
hook will be called in the order it was added with the event name and the
tuple of arguments. Native hooks added by PySys_AddAuditHook() are
called first, followed by hooks added in the current (sub)interpreter. Hooks
can then log the event, raise an exception to abort the operation,
or terminate the process entirely.
Note that audit hooks are primarily for collecting information about internal
or otherwise unobservable actions, whether by Python or libraries written in
Python. They are not suitable for implementing a “sandbox”. In particular,
malicious code can trivially disable or bypass hooks added using this
function. At a minimum, any security-sensitive hooks must be added using the
C API PySys_AddAuditHook() before initialising the runtime, and any
modules allowing arbitrary memory modification (such as ctypes) should
be completely removed or closely monitored.
Calling sys.addaudithook() will itself raise an auditing event
named sys.addaudithook with no arguments. If any
existing hooks raise an exception derived from 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.
See the audit events table for all events raised by
CPython, and PEP 578 for the original design discussion.
New in version 3.8.
Changed in version 3.8.1: Exceptions derived from Exception but not RuntimeError
are no longer suppressed.
CPython implementation detail: When tracing is enabled (see settrace()), Python hooks are only
traced if the callable has a __cantrace__ member that is set to a
true value. Otherwise, trace functions will skip the hook.
