[3.14] gh-141004: Document unstable executable kind macros from `pyframe.h` (GH-14349...

(cherry picked from commit dc62ba84ab2b83d70dee111d3feec1a6f1c3f69d)

Co-authored-by: Yashraj <yashrajpala8@gmail.com>

diff --git a/Doc/c-api/frame.rst b/Doc/c-api/frame.rst
index 4159ff6e5965fbd8d783c040f78b9e9921ac02b1..a04ef4e422949b98fb2d5ca7b679b1be818a89be 100644 (file)
--- a/Doc/c-api/frame.rst
+++ b/Doc/c-api/frame.rst
@@ -243,3 +243,62 @@ Unless using :pep:`523`, you will not need this.
    Return the currently executing line number, or -1 if there is no line number.
 
    .. versionadded:: 3.12
+
+
+.. c:var:: const PyTypeObject *PyUnstable_ExecutableKinds
+
+   An array of executable kinds (executor types) for frames, used for internal
+   debugging and tracing.
+
+   Tools like debuggers and profilers can use this to identify the type of execution
+   context associated with a frame (such as to filter out internal frames).
+   The entries are indexed by the following constants:
+
+   .. list-table::
+      :header-rows: 1
+      :widths: auto
+
+      * - Constant
+        - Description
+      * - .. c:macro:: PyUnstable_EXECUTABLE_KIND_SKIP
+        - The frame is internal (For example: inlined) and should be skipped by tools.
+      * - .. c:macro:: PyUnstable_EXECUTABLE_KIND_PY_FUNCTION
+        - The frame corresponds to a standard Python function.
+      * - .. c:macro:: PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION
+        - The frame corresponds to a function defined in native code.
+      * - .. c:macro:: PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR
+        - The frame corresponds to a method on a class instance.
+
+   However, Python's C API lacks a function to read the executable kind from
+   a frame. Instead, use this recipe:
+
+   .. code-block:: c
+
+      int
+      get_executable_kind(PyFrameObject *frame)
+      {
+         _PyInterpreterFrame *f = frame->f_frame;
+         PyObject *exec = PyStackRef_AsPyObjectBorrow(f->f_executable);
+
+         if (PyCode_Check(exec)) {
+            return PyUnstable_EXECUTABLE_KIND_PY_FUNCTION;
+         }
+         if (PyMethod_Check(exec)) {
+            return PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION;
+         }
+         if (Py_IS_TYPE(exec, &PyMethodDescr_Type)) {
+            return PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR;
+         }
+
+         return PyUnstable_EXECUTABLE_KIND_SKIP;
+      }
+
+   .. versionadded:: 3.13
+
+
+.. c:macro:: PyUnstable_EXECUTABLE_KINDS
+
+   The number of entries in :c:data:`PyUnstable_ExecutableKinds`.
+
+   .. versionadded:: 3.13
+

diff --git a/Tools/check-c-api-docs/ignored_c_api.txt b/Tools/check-c-api-docs/ignored_c_api.txt
index 6de6aaf587d4f00fd4b0ddcdb00a1b0f10bcb5a3..4801d219f29b577ee846aad25f9ae62822df5314 100644 (file)
--- a/Tools/check-c-api-docs/ignored_c_api.txt
+++ b/Tools/check-c-api-docs/ignored_c_api.txt
@@ -58,18 +58,6 @@ PyDescr_TYPE
 PyWrapperFlag_KEYWORDS
 # cpython/fileobject.h
 Py_UniversalNewlineFgets
-# cpython/ceval.h
-PyUnstable_CopyPerfMapFile
-PyUnstable_PerfTrampoline_CompileCode
-PyUnstable_PerfTrampoline_SetPersistAfterFork
-# cpython/pyerrors.h
-PyException_HEAD
-# cpython/pyframe.h
-PyUnstable_EXECUTABLE_KINDS
-PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION
-PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR
-PyUnstable_EXECUTABLE_KIND_PY_FUNCTION
-PyUnstable_EXECUTABLE_KIND_SKIP
 # cpython/pylifecycle.h
 Py_FrozenMain
 # pythonrun.h