bpo-37390: Add audit event table to documentations (GH-14406)

Also updates some (unreleased) event names to be consistent with the others.
(cherry picked from commit 44f91c3)

Co-authored-by: Steve Dower <[email protected]>

Author: miss-islington

Doc/c-api/code.rst

@@ -45,7 +45,7 @@ bound into a function.
       The first parameter (*argcount*) now represents the total number of positional arguments,
       including positional-only.
 
-   .. audit-event:: code.__new__ "code filename name argcount posonlyargcount kwonlyargcount nlocals stacksize flags"
+   .. audit-event:: code.__new__ code,filename,name,argcount,posonlyargcount,kwonlyargcount,nlocals,stacksize,flags c.PyCode_New
 
 .. c:function:: PyCodeObject* PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)
 

Doc/c-api/sys.rst

@@ -291,8 +291,6 @@ accessible to C code.  They all work with the current interpreter thread's
 
 .. c:function:: int PySys_Audit(const char *event, const char *format, ...)
 
-   .. index:: single: audit events
-
    Raises an auditing event with any active hooks. Returns zero for success
    and non-zero with an exception set on failure.
 
@@ -311,8 +309,6 @@ accessible to C code.  They all work with the current interpreter thread's
 
 .. c:function:: int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)
 
-   .. index:: single: audit events
-
    Adds to the collection of active auditing hooks. Returns zero for success
    and non-zero on failure. If the runtime has been initialized, also sets an
    error on failure. Hooks added through this API are called for all

Doc/library/array.rst

@@ -83,7 +83,7 @@ The module defines the following type:
    to add initial items to the array.  Otherwise, the iterable initializer is
    passed to the :meth:`extend` method.
 
-   .. audit-event:: array.__new__ "typecode initializer"
+   .. audit-event:: array.__new__ typecode,initializer array.array
 
 .. data:: typecodes
 

Doc/library/audit_events.rst

@@ -0,0 +1,21 @@
+.. _audit-events:
+
+.. index:: single: audit events
+
+Audit events table
+==================
+
+This table contains all events raised by :func:`sys.audit` or
+:c:func:`PySys_Audit` calls throughout the CPython runtime and the
+standard library.
+
+See :func:`sys.addaudithook` and :c:func:`PySys_AddAuditHook` for
+information on handling these events.
+
+.. impl-detail::
+
+   This table is generated from the CPython documentation, and may not
+   represent events raised by other implementations. See your runtime
+   specific documentation for actual events raised.
+
+.. audit-event-table::

Doc/library/ctypes.rst

@@ -1509,13 +1509,13 @@ object is available:
    :c:type:`int`, which is of course not always the truth, so you have to assign
    the correct :attr:`restype` attribute to use these functions.
 
-.. audit-event:: ctypes.dlopen name
+.. audit-event:: ctypes.dlopen name ctypes.LibraryLoader
 
    Loading a library through any of these objects raises an
    :ref:`auditing event <auditing>` ``ctypes.dlopen`` with string argument
    ``name``, the name used to load the library.
 
-.. audit-event:: ctypes.dlsym "library name"
+.. audit-event:: ctypes.dlsym library,name ctypes.LibraryLoader
 
    Accessing a function on a loaded library raises an auditing event
    ``ctypes.dlsym`` with arguments ``library`` (the library object) and ``name``
@@ -2043,7 +2043,7 @@ Data types
       This method returns a ctypes type instance using the memory specified by
       *address* which must be an integer.
 
-      .. audit-event:: ctypes.cdata address
+      .. audit-event:: ctypes.cdata address ctypes._CData.from_address
 
          This method, and others that indirectly call this method, raises an
          :ref:`auditing event <auditing>` ``ctypes.cdata`` with argument

Doc/library/debug.rst

@@ -5,10 +5,13 @@ Debugging and Profiling
 These libraries help you with Python development: the debugger enables you to
 step through code, analyze stack frames and set breakpoints etc., and the
 profilers run code and give you a detailed breakdown of execution times,
-allowing you to identify bottlenecks in your programs.
+allowing you to identify bottlenecks in your programs. Auditing events
+provide visibility into runtime behaviors that would otherwise require
+intrusive debugging or patching.
 
 .. toctree::
 
+   audit_events.rst
    bdb.rst
    faulthandler.rst
    pdb.rst

Doc/library/ensurepip.rst

@@ -119,7 +119,7 @@ Module API
    *verbosity* controls the level of output to :data:`sys.stdout` from the
    bootstrapping operation.
 
-   .. audit-event:: ensurepip.bootstrap root
+   .. audit-event:: ensurepip.bootstrap root ensurepip.bootstrap
 
    .. note::
 

Doc/library/ftplib.rst

@@ -190,7 +190,7 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
    *source_address* is a 2-tuple ``(host, port)`` for the socket to bind to as
    its source address before connecting.
 
-   .. audit-event:: ftplib.FTP.connect "self host port"
+   .. audit-event:: ftplib.connect self,host,port ftplib.FTP.connect
 
    .. versionchanged:: 3.3
       *source_address* parameter was added.
@@ -225,7 +225,7 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
 
    Send a simple command string to the server and return the response string.
 
-   .. audit-event:: ftplib.FTP.sendcmd "self cmd"
+   .. audit-event:: ftplib.sendcmd self,cmd ftplib.FTP.sendcmd
 
 
 .. method:: FTP.voidcmd(cmd)
@@ -234,7 +234,7 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
    nothing if a response code corresponding to success (codes in the range
    200--299) is received.  Raise :exc:`error_reply` otherwise.
 
-   .. audit-event:: ftplib.FTP.sendcmd "self cmd"
+   .. audit-event:: ftplib.sendcmd self,cmd ftplib.FTP.voidcmd
 
 
 .. method:: FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)

Doc/library/functions.rst

@@ -128,7 +128,7 @@ are always available.  They are listed here in alphabetical order.
    :func:`breakpoint` will automatically call that, allowing you to drop into
    the debugger of choice.
 
-   .. audit-event:: builtins.breakpoint "sys.breakpointhook"
+   .. audit-event:: builtins.breakpoint breakpointhook breakpoint
 
    .. versionadded:: 3.7
 
@@ -277,7 +277,7 @@ are always available.  They are listed here in alphabetical order.
    If you want to parse Python code into its AST representation, see
    :func:`ast.parse`.
 
-   .. audit-event:: compile "source filename"
+   .. audit-event:: compile source,filename compile
 
       Raises an :ref:`auditing event <auditing>` ``compile`` with arguments
       ``source`` and ``filename``. This event may also be raised by implicit
@@ -490,7 +490,7 @@ are always available.  They are listed here in alphabetical order.
    See :func:`ast.literal_eval` for a function that can safely evaluate strings
    with expressions containing only literals.
 
-   .. audit-event:: exec code_object
+   .. audit-event:: exec code_object eval
 
       Raises an :ref:`auditing event <auditing>` ``exec`` with the code object
       as the argument. Code compilation events may also be raised.
@@ -525,7 +525,7 @@ are always available.  They are listed here in alphabetical order.
    builtins are available to the executed code by inserting your own
    ``__builtins__`` dictionary into *globals* before passing it to :func:`exec`.
 
-   .. audit-event:: exec code_object
+   .. audit-event:: exec code_object exec
 
       Raises an :ref:`auditing event <auditing>` ``exec`` with the code object
       as the argument. Code compilation events may also be raised.
@@ -779,12 +779,12 @@ are always available.  They are listed here in alphabetical order.
    If the :mod:`readline` module was loaded, then :func:`input` will use it
    to provide elaborate line editing and history features.
 
-   .. audit-event:: builtins.input prompt
+   .. audit-event:: builtins.input prompt input
 
       Raises an :ref:`auditing event <auditing>` ``builtins.input`` with
       argument ``prompt`` before reading input
 
-   .. audit-event:: builtins.input/result result
+   .. audit-event:: builtins.input/result result input
 
       Raises an auditing event ``builtins.input/result`` with the result after
       successfully reading input.
@@ -1222,7 +1222,7 @@ are always available.  They are listed here in alphabetical order.
    (where :func:`open` is declared), :mod:`os`, :mod:`os.path`, :mod:`tempfile`,
    and :mod:`shutil`.
 
-   .. audit-event:: open "file mode flags"
+   .. audit-event:: open file,mode,flags open
 
    The ``mode`` and ``flags`` arguments may have been modified or inferred from
    the original call.

Doc/library/glob.rst

@@ -52,7 +52,7 @@ For example, ``'[?]'`` matches the character ``'?'``.
    more directories and subdirectories.  If the pattern is followed by an
    ``os.sep``, only directories and subdirectories match.
 
-   .. audit-event:: glob.glob "pathname recursive"
+   .. audit-event:: glob.glob pathname,recursive glob.glob
 
    .. note::
       Using the "``**``" pattern in large directory trees may consume
@@ -67,7 +67,7 @@ For example, ``'[?]'`` matches the character ``'?'``.
    Return an :term:`iterator` which yields the same values as :func:`glob`
    without actually storing them all simultaneously.
 
-   .. audit-event:: glob.glob "pathname recursive"
+   .. audit-event:: glob.glob pathname,recursive glob.iglob
 
 
 .. function:: escape(pathname)