bpo-38434: Fixes some audit event documentation (GH-16932)
(cherry picked from commit 894e30ce0bcc1c509eb01c8ffa9ba6d7701aeaaf)
Co-authored-by: Steve Dower <steve.dower@python.org>
diff --git a/Doc/c-api/code.rst b/Doc/c-api/code.rst
index 3c4f669..45a6b4a 100644
--- a/Doc/c-api/code.rst
+++ b/Doc/c-api/code.rst
@@ -40,8 +40,6 @@
can bind you to a precise Python version since the definition of the bytecode
changes often.
- .. audit-event:: code.__new__ code,filename,name,argcount,posonlyargcount,kwonlyargcount,nlocals,stacksize,flags c.PyCode_New
-
.. c:function:: PyCodeObject* PyCode_NewWithPosOnlyArgs(int argcount, int posonlyargcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *lnotab)
Similar to :c:func:`PyCode_New`, but with an extra "posonlyargcount" for positonal-only arguments.
diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst
index 838a97c..87d2bd1 100644
--- a/Doc/c-api/sys.rst
+++ b/Doc/c-api/sys.rst
@@ -330,7 +330,16 @@
See :pep:`578` for a detailed description of auditing. Functions in the
runtime and standard library that raise events include the details in each
- function's documentation.
+ function's documentation and listed in the :ref:`audit events table
+ <audit-events>`.
+
+ .. audit-event:: sys.addaudithook "" c.PySys_AddAuditHook
+
+ If the interpreter is initialized, this function raises a auditing event
+ ``sys.addaudithook`` with no arguments. If any existing hooks raise an
+ exception derived from :class:`Exception`, the new hook will not be
+ added and the exception is cleared. As a result, callers cannot assume
+ that their hook has been added unless they control all existing hooks.
.. versionadded:: 3.8
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index a698ecb..34b8084 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -33,18 +33,21 @@
tuple of arguments. Native hooks added by :c:func:`PySys_AddAuditHook` are
called first, followed by hooks added in the current interpreter.
- Calling this function will trigger an event for all existing hooks, and if
- any raise an exception derived from :class:`Exception`, the add will be
- silently ignored. As a result, callers cannot assume that their hook has been
- added unless they control all existing hooks.
+ .. audit-event:: sys.addaudithook "" sys.addaudithook
+
+ Raises a auditing event ``sys.addaudithook`` with no arguments. If any
+ existing hooks raise an exception derived from :class:`Exception`, 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.
.. versionadded:: 3.8
.. impl-detail::
- When tracing is enabled, Python hooks are only traced if the callable has
- a ``__cantrace__`` member that is set to a true value. Otherwise, trace
- functions will not see the hook.
+ When tracing is enabled (see :func:`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.
.. data:: argv
@@ -87,7 +90,7 @@
native function is preferred when possible.
See the :ref:`audit events table <audit-events>` for all events raised by
- ``CPython``.
+ CPython.
.. versionadded:: 3.8
diff --git a/Doc/library/types.rst b/Doc/library/types.rst
index a21fb44..9393f9e 100644
--- a/Doc/library/types.rst
+++ b/Doc/library/types.rst
@@ -138,6 +138,10 @@
The type for code objects such as returned by :func:`compile`.
+ .. audit-event:: code.__new__ code,filename,name,argcount,posonlyargcount,kwonlyargcount,nlocals,stacksize,flags CodeType
+
+ Note that the audited arguments may not match the names or positions
+ required by the initializer.
.. data:: CellType
diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
index 0a043a9..a8ec0fb 100644
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -839,6 +839,7 @@
:func:`importlib.import_module` is provided to support applications that
determine dynamically the modules to be loaded.
+.. audit-event:: import module,filename,sys.path,sys.meta_path,sys.path_hooks import
.. _future: