bpo-36842: Implement PEP 578 (GH-12613)

Adds sys.audit, sys.addaudithook, io.open_code, and associated C APIs.

1 files changed, 63 insertions, 0 deletions

diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 3b754bd..0294f74 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -19,6 +19,30 @@ always available.
    .. versionadded:: 3.2
 
 
+.. function:: addaudithook(hook)
+
+   Adds the callable *hook* to the collection of active auditing hooks for the
+   current interpreter.
+
+   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.
+
+   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.
+
+   .. 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.
+
+
 .. data:: argv
 
    The list of command line arguments passed to a Python script. ``argv[0]`` is the
@@ -37,6 +61,30 @@ always available.
       ``[os.fsencode(arg) for arg in sys.argv]``.
 
 
+.. _auditing:
+
+.. function:: audit(event, *args)
+
+   .. index:: single: auditing
+
+   Raises 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.
+
+   Hooks are added using the :func:`sys.addaudithook` or
+   :c:func:`PySys_AddAuditHook` functions.
+
+   The native equivalent of this function is :c:func:`PySys_Audit`. Using the
+   native function is preferred when possible.
+
+   .. versionadded:: 3.8
+
+
 .. data:: base_exec_prefix
 
    Set during Python startup, before ``site.py`` is run, to the same value as
@@ -114,6 +162,8 @@ always available.
 
    This function should be used for internal and specialized purposes only.
 
+   .. audit-event:: sys._current_frames
+
 
 .. function:: breakpointhook()
 
@@ -617,6 +667,8 @@ always available.
    that is deeper than the call stack, :exc:`ValueError` is raised.  The default
    for *depth* is zero, returning the frame at the top of the call stack.
 
+   .. audit-event:: sys._getframe
+
    .. impl-detail::
 
       This function should be used for internal and specialized purposes only.
@@ -1146,6 +1198,8 @@ always available.
    ``'return'``, ``'c_call'``, ``'c_return'``, or ``'c_exception'``. *arg* depends
    on the event type.
 
+   .. audit-event:: sys.setprofile
+
    The events have the following meaning:
 
    ``'call'``
@@ -1266,6 +1320,8 @@ always available.
 
    For more information on code and frame objects, refer to :ref:`types`.
 
+   .. audit-event:: sys.settrace
+
    .. impl-detail::
 
       The :func:`settrace` function is intended only for implementing debuggers,
@@ -1286,6 +1342,13 @@ always available.
    first time. The *finalizer* will be called when an asynchronous generator
    is about to be garbage collected.
 
+   .. audit-event:: sys.set_asyncgen_hooks_firstiter
+
+   .. audit-event:: sys.set_asyncgen_hooks_finalizer
+
+   Two auditing events are raised because the underlying API consists of two
+   calls, each of which must raise its own event.
+
    .. versionadded:: 3.6
       See :pep:`525` for more details, and for a reference example of a
       *finalizer* method see the implementation of