From 0c37269be7065b9b15b7b3a4406084f9535a793a Mon Sep 17 00:00:00 2001 From: Andrew Kuchling Date: Tue, 20 Oct 2020 10:41:02 -0400 Subject: [PATCH] bpo-41192: Clarify the sys module's description of the auditing feature (GH-22768) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Éric Araujo --- Doc/library/sys.rst | 33 ++++++++++++++++++++++++--------- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index d201d7061f9..468a30d3268 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -31,16 +31,22 @@ always available. When an auditing event is raised through the :func:`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 :c:func:`PySys_AddAuditHook` are - called first, followed by hooks added in the current interpreter. + called first, followed by hooks added in the current interpreter. Hooks + can then log the event, raise an exception to abort the operation, + or terminate the process entirely. .. audit-event:: sys.addaudithook "" sys.addaudithook - Raise an auditing event ``sys.addaudithook`` with no arguments. If any + Calling :func:`sys.addaudithook` will itself raise an auditing event + named ``sys.addaudithook`` with no arguments. If any 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. + See the :ref:`audit events table ` for all events raised by + CPython, and :pep:`578` for the original design discussion. + .. versionadded:: 3.8 .. versionchanged:: 3.8.1 @@ -81,14 +87,23 @@ always available. .. index:: single: auditing - Raise an auditing event with any active hooks. The event name is a string - identifying the event and its associated schema, which is the number and - types of arguments. The schema for a given event is considered public and - stable API and should not be modified between releases. + Raise an auditing event and trigger any active auditing hooks. + *event* is a string identifying the event, and *args* may contain + optional arguments with more information about the event. The + number and types of arguments for a given event are considered a + public and stable API and should not be modified between releases. - This function will raise the first exception raised by any hook. In general, - these errors should not be handled and should terminate the process as - quickly as possible. + For example, one auditing event is named ``os.chdir``. This event has + one argument called *path* that will contain the requested new + working directory. + + :func:`sys.audit` will call the existing auditing hooks, passing + the event name and arguments, and will re-raise the first exception + from any hook. In general, if an exception is raised, it should not + be handled and the process should be terminated as quickly as + possible. This allows hook implementations to decide how to respond + to particular events: they can merely log the event or abort the + operation by raising an exception. Hooks are added using the :func:`sys.addaudithook` or :c:func:`PySys_AddAuditHook` functions.