mirrors/cpython
0
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2024-11-23 09:54:58 +08:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
Co-authored-by: Éric Araujo <merwok@netwok.org>
This commit is contained in:
Andrew Kuchling 2020-10-20 10:41:02 -04:00 committed by GitHub
parent ec42789e6e
commit 0c37269be7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 24 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
Doc/library/sys.rst
View File

@ -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.
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.