bpo-41192: Add documentation of undocumented audit events (GH-21308)
diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst
index ea027ee..ed3735a 100644
--- a/Doc/c-api/file.rst
+++ b/Doc/c-api/file.rst
@@ -82,6 +82,8 @@
This function is safe to call before :c:func:`Py_Initialize`.
+ .. audit-event:: setopencodehook "" c.PyFile_SetOpenCodeHook
+
.. versionadded:: 3.8
diff --git a/Doc/library/audit_events.rst b/Doc/library/audit_events.rst
index 3c68a15..367d56e 100644
--- a/Doc/library/audit_events.rst
+++ b/Doc/library/audit_events.rst
@@ -19,3 +19,29 @@
specific documentation for actual events raised.
.. audit-event-table::
+
+The following events are raised internally and do not correspond to any
+public API of CPython:
+
++--------------------------+-------------------------------------------+
+| Audit event | Arguments |
++==========================+===========================================+
+| _winapi.CreateFile | ``file_name``, ``desired_access``, |
+| | ``share_mode``, ``creation_disposition``, |
+| | ``flags_and_attributes`` |
++--------------------------+-------------------------------------------+
+| _winapi.CreateJunction | ``src_path``, ``dst_path`` |
++--------------------------+-------------------------------------------+
+| _winapi.CreateNamedPipe | ``name``, ``open_mode``, ``pipe_mode`` |
++--------------------------+-------------------------------------------+
+| _winapi.CreatePipe | |
++--------------------------+-------------------------------------------+
+| _winapi.CreateProcess | ``application_name``, ``command_line``, |
+| | ``current_directory`` |
++--------------------------+-------------------------------------------+
+| _winapi.OpenProcess | ``process_id``, ``desired_access`` |
++--------------------------+-------------------------------------------+
+| _winapi.TerminateProcess | ``handle``, ``exit_code`` |
++--------------------------+-------------------------------------------+
+| ctypes.PyObj_FromPtr | ``obj`` |
++--------------------------+-------------------------------------------+
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index a052e72..b33aa81 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -783,6 +783,8 @@
.. impl-detail:: This is the address of the object in memory.
+ .. audit-event:: builtins.id id id
+
.. function:: input([prompt])
diff --git a/Doc/library/types.rst b/Doc/library/types.rst
index e4a8dec..a5cf9ab 100644
--- a/Doc/library/types.rst
+++ b/Doc/library/types.rst
@@ -116,6 +116,11 @@
The type of user-defined functions and functions created by
:keyword:`lambda` expressions.
+ .. audit-event:: function.__new__ code types.FunctionType
+
+ The audit event only occurs for direct instantiation of function objects,
+ and is not raised for normal compilation.
+
.. data:: GeneratorType
@@ -145,10 +150,11 @@
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
+ .. audit-event:: code.__new__ code,filename,name,argcount,posonlyargcount,kwonlyargcount,nlocals,stacksize,flags types.CodeType
Note that the audited arguments may not match the names or positions
- required by the initializer.
+ required by the initializer. The audit event only occurs for direct
+ instantiation of code objects, and is not raised for normal compilation.
.. method:: CodeType.replace(**kwargs)
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 4396f1b..29e64cb 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1540,6 +1540,12 @@
result of implicit invocation via language syntax or built-in functions.
See :ref:`special-lookup`.
+ .. audit-event:: object.__getattr__ obj,name object.__getattribute__
+
+ For certain sensitive attribute accesses, raises an
+ :ref:`auditing event <auditing>` ``object.__getattr__`` with arguments
+ ``obj`` and ``name``.
+
.. method:: object.__setattr__(self, name, value)
@@ -1551,12 +1557,24 @@
call the base class method with the same name, for example,
``object.__setattr__(self, name, value)``.
+ .. audit-event:: object.__setattr__ obj,name,value object.__setattr__
+
+ For certain sensitive attribute assignments, raises an
+ :ref:`auditing event <auditing>` ``object.__setattr__`` with arguments
+ ``obj``, ``name``, ``value``.
+
.. method:: object.__delattr__(self, name)
Like :meth:`__setattr__` but for attribute deletion instead of assignment. This
should only be implemented if ``del obj.name`` is meaningful for the object.
+ .. audit-event:: object.__delattr__ obj,name object.__delattr__
+
+ For certain sensitive attribute deletions, raises an
+ :ref:`auditing event <auditing>` ``object.__delattr__`` with arguments
+ ``obj`` and ``name``.
+
.. method:: object.__dir__(self)