bpo-41192: Clarify the sys module's description of the auditing feature (GH-22768)
Co-authored-by: Éric Araujo <merwok@netwok.org>
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index d201d70..468a30d 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -31,16 +31,22 @@
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 <audit-events>` 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 @@
.. 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.