Mailing List Archive

bpo-41192: Clarify the sys module's description of the auditing feature (GH-22768)
https://github.com/python/cpython/commit/0c37269be7065b9b15b7b3a4406084f9535a793a
commit: 0c37269be7065b9b15b7b3a4406084f9535a793a
branch: master
author: Andrew Kuchling <amk@amk.ca>
committer: akuchling <amk@amk.ca>
date: 2020-10-20T10:41:02-04:00
summary:

bpo-41192: Clarify the sys module's description of the auditing feature (GH-22768)


Co-authored-by: Éric Araujo <merwok@netwok.org>

files:
M Doc/library/sys.rst

diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index d201d7061f980..468a30d326891 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 <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 @@ 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.
-
- 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.
+ 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.
+
+ 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.

_______________________________________________
Python-checkins mailing list
Python-checkins@python.org
https://mail.python.org/mailman/listinfo/python-checkins