gh-141518: Add PyUnstable_InterpreterState_SetEvalFrameFunc()

Add PyUnstable API for PEP 523:

* PyUnstable_FrameEvalFunction type
* PyUnstable_InterpreterState_GetEvalFrameFunc()
* PyUnstable_InterpreterState_SetEvalFrameFunc()

Keep the old names as deprecated aliases to new names:

* _PyFrameEvalFunction
* _PyInterpreterState_GetEvalFrameFunc
* _PyInterpreterState_SetEvalFrameFunc

Author: vstinner

Doc/c-api/init.rst

@@ -1438,7 +1438,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
    .. versionadded:: 3.8
 
 
-.. c:type:: PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, _PyInterpreterFrame *frame, int throwflag)
+.. c:type:: PyObject* (*PyUnstable_FrameEvalFunction)(PyThreadState *tstate, _PyInterpreterFrame *frame, int throwflag)
 
    Type of a frame evaluation function.
 
@@ -1451,21 +1451,21 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
    .. versionchanged:: 3.11
       The *frame* parameter changed from ``PyFrameObject*`` to ``_PyInterpreterFrame*``.
 
-.. c:function:: _PyFrameEvalFunction _PyInterpreterState_GetEvalFrameFunc(PyInterpreterState *interp)
+.. c:function:: PyUnstable_FrameEvalFunction PyUnstable_InterpreterState_GetEvalFrameFunc(PyInterpreterState *interp)
 
    Get the frame evaluation function.
 
    See the :pep:`523` "Adding a frame evaluation API to CPython".
 
-   .. versionadded:: 3.9
+   .. versionadded:: next
 
-.. c:function:: void _PyInterpreterState_SetEvalFrameFunc(PyInterpreterState *interp, _PyFrameEvalFunction eval_frame)
+.. c:function:: void PyUnstable_InterpreterState_SetEvalFrameFunc(PyInterpreterState *interp, PyUnstable_FrameEvalFunction eval_frame)
 
    Set the frame evaluation function.
 
    See the :pep:`523` "Adding a frame evaluation API to CPython".
 
-   .. versionadded:: 3.9
+   .. versionadded:: next
 
 
 .. c:function:: PyObject* PyThreadState_GetDict()

Doc/whatsnew/3.15.rst

@@ -1087,6 +1087,16 @@ New features
 * Add :c:func:`PyTuple_FromArray` to create a :class:`tuple` from an array.
   (Contributed by Victor Stinner in :gh:`111489`.)
 
+* Add a PyUnstable API for :pep:`523`:
+
+  * :c:type:`PyUnstable_FrameEvalFunction` type
+  * :c:func:`PyUnstable_InterpreterState_GetEvalFrameFunc`
+  * :c:func:`PyUnstable_InterpreterState_SetEvalFrameFunc`
+
+  (Contributed by Victor Stinner in :gh:`141518`.)
+
+Patch by Victor Stinner.
+
 * Add :c:func:`PyUnstable_ThreadState_SetStackProtection` and
   :c:func:`PyUnstable_ThreadState_ResetStackProtection` functions to set
   the stack protection base address and stack protection size of a Python

Include/cpython/pystate.h

@@ -302,10 +302,15 @@ PyAPI_FUNC(void) PyThreadState_DeleteCurrent(void);
 
 /* Frame evaluation API */
 
-typedef PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, struct _PyInterpreterFrame *, int);
+typedef PyObject* (*PyUnstable_FrameEvalFunction)(PyThreadState *tstate, struct _PyInterpreterFrame *, int);
 
-PyAPI_FUNC(_PyFrameEvalFunction) _PyInterpreterState_GetEvalFrameFunc(
+PyAPI_FUNC(PyUnstable_FrameEvalFunction) PyUnstable_InterpreterState_GetEvalFrameFunc(
     PyInterpreterState *interp);
-PyAPI_FUNC(void) _PyInterpreterState_SetEvalFrameFunc(
+PyAPI_FUNC(void) PyUnstable_InterpreterState_SetEvalFrameFunc(
     PyInterpreterState *interp,
-    _PyFrameEvalFunction eval_frame);
+    PyUnstable_FrameEvalFunction eval_frame);
+
+// Deprecated aliases kept for backward compatibility
+#define _PyFrameEvalFunction PyUnstable_FrameEvalFunction
+#define _PyInterpreterState_GetEvalFrameFunc PyUnstable_InterpreterState_GetEvalFrameFunc
+#define _PyInterpreterState_SetEvalFrameFunc PyUnstable_InterpreterState_SetEvalFrameFunc

Include/internal/pycore_interp_structs.h

@@ -87,7 +87,7 @@ struct _ceval_runtime_state {
         struct trampoline_api_st trampoline_api;
         FILE *map_file;
         Py_ssize_t persist_after_fork;
-       _PyFrameEvalFunction prev_eval_frame;
+        PyUnstable_FrameEvalFunction prev_eval_frame;
 #else
         int _not_used;
 #endif
@@ -860,7 +860,7 @@ struct _is {
     PyObject *sysdict_copy;
     PyObject *builtins_copy;
     // Initialized to _PyEval_EvalFrameDefault().
-    _PyFrameEvalFunction eval_frame;
+    PyUnstable_FrameEvalFunction eval_frame;
 
     PyFunction_WatchCallback func_watchers[FUNC_MAX_WATCHERS];
     // One bit is set for each non-NULL entry in func_watchers

Misc/NEWS.d/next/C_API/2025-11-17-16-08-11.gh-issue-141518.Z8ig9U.rst

@@ -0,0 +1,7 @@
+Add a PyUnstable API for :pep:`523`:
+
+* :c:type:`PyUnstable_FrameEvalFunction` type
+* :c:func:`PyUnstable_InterpreterState_GetEvalFrameFunc`
+* :c:func:`PyUnstable_InterpreterState_SetEvalFrameFunc`
+
+Patch by Victor Stinner.

Modules/_testinternalcapi.c

@@ -657,7 +657,8 @@ static PyObject *
 set_eval_frame_default(PyObject *self, PyObject *Py_UNUSED(args))
 {
     module_state *state = get_module_state(self);
-    _PyInterpreterState_SetEvalFrameFunc(_PyInterpreterState_GET(), _PyEval_EvalFrameDefault);
+    PyUnstable_InterpreterState_SetEvalFrameFunc(_PyInterpreterState_GET(),
+                                                 _PyEval_EvalFrameDefault);
     Py_CLEAR(state->record_list);
     Py_RETURN_NONE;
 }
@@ -689,7 +690,8 @@ set_eval_frame_record(PyObject *self, PyObject *list)
         return NULL;
     }
     Py_XSETREF(state->record_list, Py_NewRef(list));
-    _PyInterpreterState_SetEvalFrameFunc(_PyInterpreterState_GET(), record_eval);
+    PyUnstable_InterpreterState_SetEvalFrameFunc(_PyInterpreterState_GET(),
+                                                 record_eval);
     Py_RETURN_NONE;
 }
 

Python/perf_trampoline.c

@@ -486,12 +486,12 @@ _PyPerfTrampoline_Init(int activate)
 #ifdef PY_HAVE_PERF_TRAMPOLINE
     PyThreadState *tstate = _PyThreadState_GET();
     if (!activate) {
-        _PyInterpreterState_SetEvalFrameFunc(tstate->interp, prev_eval_frame);
+        PyUnstable_InterpreterState_SetEvalFrameFunc(tstate->interp, prev_eval_frame);
         perf_status = PERF_STATUS_NO_INIT;
     }
     else if (tstate->interp->eval_frame != py_trampoline_evaluator) {
-        prev_eval_frame = _PyInterpreterState_GetEvalFrameFunc(tstate->interp);
-        _PyInterpreterState_SetEvalFrameFunc(tstate->interp, py_trampoline_evaluator);
+        prev_eval_frame = PyUnstable_InterpreterState_GetEvalFrameFunc(tstate->interp);
+        PyUnstable_InterpreterState_SetEvalFrameFunc(tstate->interp, py_trampoline_evaluator);
         extra_code_index = _PyEval_RequestCodeExtraIndex(NULL);
         if (extra_code_index == -1) {
             return -1;
@@ -517,7 +517,7 @@ _PyPerfTrampoline_Fini(void)
     }
     PyThreadState *tstate = _PyThreadState_GET();
     if (tstate->interp->eval_frame == py_trampoline_evaluator) {
-        _PyInterpreterState_SetEvalFrameFunc(tstate->interp, NULL);
+        PyUnstable_InterpreterState_SetEvalFrameFunc(tstate->interp, NULL);
     }
     if (perf_status == PERF_STATUS_OK) {
         trampoline_api.free_state(trampoline_api.state);

Python/pystate.c

@@ -2896,8 +2896,8 @@ PyGILState_Release(PyGILState_STATE oldstate)
 /* Other API */
 /*************/
 
-_PyFrameEvalFunction
-_PyInterpreterState_GetEvalFrameFunc(PyInterpreterState *interp)
+PyUnstable_FrameEvalFunction
+PyUnstable_InterpreterState_GetEvalFrameFunc(PyInterpreterState *interp)
 {
     if (interp->eval_frame == NULL) {
         return _PyEval_EvalFrameDefault;
@@ -2907,8 +2907,8 @@ _PyInterpreterState_GetEvalFrameFunc(PyInterpreterState *interp)
 
 
 void
-_PyInterpreterState_SetEvalFrameFunc(PyInterpreterState *interp,
-                                     _PyFrameEvalFunction eval_frame)
+PyUnstable_InterpreterState_SetEvalFrameFunc(PyInterpreterState *interp,
+                                             PyUnstable_FrameEvalFunction eval_frame)
 {
     if (eval_frame == _PyEval_EvalFrameDefault) {
         eval_frame = NULL;