bpo-36842: Implement PEP 578 (GH-12613)
Adds sys.audit, sys.addaudithook, io.open_code, and associated C APIs.
diff --git a/Doc/c-api/code.rst b/Doc/c-api/code.rst
index 27d3f76..fd3f691 100644
--- a/Doc/c-api/code.rst
+++ b/Doc/c-api/code.rst
@@ -40,6 +40,7 @@
:c:func:`PyCode_New` directly can bind you to a precise Python
version since the definition of the bytecode changes often.
+ .. audit-event:: code.__new__ "code filename name argcount kwonlyargcount nlocals stacksize flags"
.. c:function:: PyCodeObject* PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)
diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst
index defc859..543dc60 100644
--- a/Doc/c-api/file.rst
+++ b/Doc/c-api/file.rst
@@ -60,6 +60,32 @@
raised if the end of the file is reached immediately.
+.. c:function:: int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)
+
+ Overrides the normal behavior of :func:`io.open_code` to pass its parameter
+ through the provided handler.
+
+ The handler is a function of type :c:type:`PyObject *(\*)(PyObject *path,
+ void *userData)`, where *path* is guaranteed to be :c:type:`PyUnicodeObject`.
+
+ The *userData* pointer is passed into the hook function. Since hook
+ functions may be called from different runtimes, this pointer should not
+ refer directly to Python state.
+
+ As this hook is intentionally used during import, avoid importing new modules
+ during its execution unless they are known to be frozen or available in
+ ``sys.modules``.
+
+ Once a hook has been set, it cannot be removed or replaced, and later calls to
+ :c:func:`PyFile_SetOpenCodeHook` will fail. On failure, the function returns
+ -1 and sets an exception if the interpreter has been initialized.
+
+ This function is safe to call before :c:func:`Py_Initialize`.
+
+ .. versionadded:: 3.8
+
+
+
.. c:function:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
.. index:: single: Py_PRINT_RAW
diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst
index 04e169a..2091da6 100644
--- a/Doc/c-api/sys.rst
+++ b/Doc/c-api/sys.rst
@@ -289,6 +289,56 @@
.. versionadded:: 3.2
+.. 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.
+
+ If any hooks have been added, *format* and other arguments will be used
+ to construct a tuple to pass. Apart from ``N``, the same format characters
+ as used in :c:func:`Py_BuildValue` are available. If the built value is not
+ a tuple, it will be added into a single-element tuple. (The ``N`` format
+ option consumes a reference, but since there is no way to know whether
+ arguments to this function will be consumed, using it may cause reference
+ leaks.)
+
+ :func:`sys.audit` performs the same function from Python code.
+
+ .. versionadded:: 3.8
+
+
+.. 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
+ interpreters created by the runtime.
+
+ This function is safe to call before :c:func:`Py_Initialize`. When called
+ after runtime initialization, existing audit hooks are notified and may
+ silently abort the operation by raising an error subclassed from
+ :class:`Exception` (other errors will not be silenced).
+
+ The hook function is of type :c:type:`int (*)(const char *event, PyObject
+ *args, void *userData)`, where *args* is guaranteed to be a
+ :c:type:`PyTupleObject`. The hook function is always called with the GIL
+ held by the Python interpreter that raised the event.
+
+ The *userData* pointer is passed into the hook function. Since hook
+ functions may be called from different runtimes, this pointer should not
+ refer directly to Python state.
+
+ See :pep:`578` for a detailed decription of auditing. Functions in the
+ runtime and standard library that raise events include the details in each
+ function's documentation.
+
+ .. versionadded:: 3.8
+
+
.. _processcontrol:
Process Control