gh-93937, C API: Move PyFrame_GetBack() to Python.h (#93938)

Move the follow functions and type from frameobject.h to pyframe.h,
so the standard <Python.h> provide frame getter functions:

* PyFrame_Check()
* PyFrame_GetBack()
* PyFrame_GetBuiltins()
* PyFrame_GetGenerator()
* PyFrame_GetGlobals()
* PyFrame_GetLasti()
* PyFrame_GetLocals()
* PyFrame_Type

Remove #include "frameobject.h" from many C files. It's no longer
needed.

Author: vstinner

Doc/whatsnew/3.11.rst

@@ -1752,6 +1752,21 @@ Porting to Python 3.11
   which are not available in the limited C API.
   (Contributed by Victor Stinner in :issue:`46007`.)
 
+* The following frame functions and type are now directly available with
+  ``#include <Python.h>``, it's no longer needed to add
+  ``#include <frameobject.h>``:
+
+  * :c:func:`PyFrame_Check`
+  * :c:func:`PyFrame_GetBack`
+  * :c:func:`PyFrame_GetBuiltins`
+  * :c:func:`PyFrame_GetGenerator`
+  * :c:func:`PyFrame_GetGlobals`
+  * :c:func:`PyFrame_GetLasti`
+  * :c:func:`PyFrame_GetLocals`
+  * :c:type:`PyFrame_Type`
+
+  (Contributed by Victor Stinner in :gh:`93937`.)
+
 .. _pyframeobject-3.11-hiding:
 
 * The :c:type:`PyFrameObject` structure members have been removed from the
@@ -1888,7 +1903,6 @@ Porting to Python 3.11
   paths and then modify them, finish initialization and use :c:func:`PySys_GetObject`
   to retrieve :data:`sys.path` as a Python list object and modify it directly.
 
-
 Deprecated
 ----------
 

Include/cpython/frameobject.h

@@ -6,10 +6,6 @@
 
 /* Standard object interface */
 
-PyAPI_DATA(PyTypeObject) PyFrame_Type;
-
-#define PyFrame_Check(op) Py_IS_TYPE((op), &PyFrame_Type)
-
 PyAPI_FUNC(PyFrameObject *) PyFrame_New(PyThreadState *, PyCodeObject *,
                                         PyObject *, PyObject *);
 
@@ -31,12 +27,3 @@ PyAPI_FUNC(int) _PyFrame_IsEntryFrame(PyFrameObject *frame);
 
 PyAPI_FUNC(int) PyFrame_FastToLocalsWithError(PyFrameObject *f);
 PyAPI_FUNC(void) PyFrame_FastToLocals(PyFrameObject *);
-
-PyAPI_FUNC(PyFrameObject *) PyFrame_GetBack(PyFrameObject *frame);
-PyAPI_FUNC(PyObject *) PyFrame_GetLocals(PyFrameObject *frame);
-
-PyAPI_FUNC(PyObject *) PyFrame_GetGlobals(PyFrameObject *frame);
-PyAPI_FUNC(PyObject *) PyFrame_GetBuiltins(PyFrameObject *frame);
-
-PyAPI_FUNC(PyObject *) PyFrame_GetGenerator(PyFrameObject *frame);
-PyAPI_FUNC(int) PyFrame_GetLasti(PyFrameObject *frame);

Include/cpython/pyframe.h

@@ -0,0 +1,17 @@
+#ifndef Py_CPYTHON_PYFRAME_H
+#  error "this header file must not be included directly"
+#endif
+
+PyAPI_DATA(PyTypeObject) PyFrame_Type;
+
+#define PyFrame_Check(op) Py_IS_TYPE((op), &PyFrame_Type)
+
+PyAPI_FUNC(PyFrameObject *) PyFrame_GetBack(PyFrameObject *frame);
+PyAPI_FUNC(PyObject *) PyFrame_GetLocals(PyFrameObject *frame);
+
+PyAPI_FUNC(PyObject *) PyFrame_GetGlobals(PyFrameObject *frame);
+PyAPI_FUNC(PyObject *) PyFrame_GetBuiltins(PyFrameObject *frame);
+
+PyAPI_FUNC(PyObject *) PyFrame_GetGenerator(PyFrameObject *frame);
+PyAPI_FUNC(int) PyFrame_GetLasti(PyFrameObject *frame);
+

Include/pyframe.h

@@ -14,6 +14,12 @@ PyAPI_FUNC(int) PyFrame_GetLineNumber(PyFrameObject *);
 
 PyAPI_FUNC(PyCodeObject *) PyFrame_GetCode(PyFrameObject *frame);
 
+#ifndef Py_LIMITED_API
+#  define Py_CPYTHON_PYFRAME_H
+#  include "cpython/pyframe.h"
+#  undef Py_CPYTHON_PYFRAME_H
+#endif
+
 #ifdef __cplusplus
 }
 #endif

Makefile.pre.in

@@ -1567,6 +1567,7 @@ PYTHON_HEADERS= \
 		$(srcdir)/Include/cpython/pydebug.h \
 		$(srcdir)/Include/cpython/pyerrors.h \
 		$(srcdir)/Include/cpython/pyfpe.h \
+		$(srcdir)/Include/cpython/pyframe.h \
 		$(srcdir)/Include/cpython/pylifecycle.h \
 		$(srcdir)/Include/cpython/pymem.h \
 		$(srcdir)/Include/cpython/pystate.h \

Misc/NEWS.d/next/C API/2022-06-17-13-41-38.gh-issue-93937.uKVTEh.rst

@@ -0,0 +1,14 @@
+The following frame functions and type are now directly available with
+``#include <Python.h>``, it's no longer needed to add ``#include
+<frameobject.h>``:
+
+* :c:func:`PyFrame_Check`
+* :c:func:`PyFrame_GetBack`
+* :c:func:`PyFrame_GetBuiltins`
+* :c:func:`PyFrame_GetGenerator`
+* :c:func:`PyFrame_GetGlobals`
+* :c:func:`PyFrame_GetLasti`
+* :c:func:`PyFrame_GetLocals`
+* :c:type:`PyFrame_Type`
+
+Patch by Victor Stinner.

Modules/_ctypes/callbacks.c

@@ -10,7 +10,6 @@
 #endif
 
 #include "pycore_call.h"          // _PyObject_CallNoArgs()
-#include "frameobject.h"
 
 #include <stdbool.h>
 

Modules/_testcapimodule.c

@@ -21,7 +21,6 @@
 #define PY_SSIZE_T_CLEAN
 
 #include "Python.h"
-#include "frameobject.h"          // PyFrame_Check()
 #include "datetime.h"             // PyDateTimeAPI
 #include "marshal.h"              // PyMarshal_WriteLongToFile
 #include "structmember.h"         // PyMemberDef

Modules/_xxsubinterpretersmodule.c

@@ -6,7 +6,6 @@
 #endif
 
 #include "Python.h"
-#include "frameobject.h"
 #include "pycore_frame.h"
 #include "pycore_pystate.h"       // _PyThreadState_GET()
 #include "pycore_interpreteridobject.h"

Modules/faulthandler.c

@@ -5,8 +5,6 @@
 #include "pycore_signal.h"        // Py_NSIG
 #include "pycore_traceback.h"     // _Py_DumpTracebackThreads
 
-#include "frameobject.h"
-
 #include <object.h>
 #include <signal.h>
 #include <signal.h>