diff --git a/Doc/c-api/concrete.rst b/Doc/c-api/concrete.rst index 84224dcca52..8d3124a12fa 100644 --- a/Doc/c-api/concrete.rst +++ b/Doc/c-api/concrete.rst @@ -111,6 +111,7 @@ Other Objects memoryview.rst weakref.rst capsule.rst + frame.rst gen.rst coro.rst contextvars.rst diff --git a/Doc/c-api/frame.rst b/Doc/c-api/frame.rst new file mode 100644 index 00000000000..0e36e6e1fd7 --- /dev/null +++ b/Doc/c-api/frame.rst @@ -0,0 +1,48 @@ +.. highlight:: c + +Frame Objects +------------- + +.. c:type:: PyFrameObject + + The C structure of the objects used to describe frame objects. + + The structure is not part of the C API. + + .. versionchanged:: 3.11 + The structure moved to the internal C API headers. + +The :c:func:`PyEval_GetFrame` and :c:func:`PyThreadState_GetFrame` functions +can be used to get a frame object. + +See also :ref:`Reflection `. + + +.. c:function:: PyFrameObject* PyFrame_GetBack(PyFrameObject *frame) + + Get the *frame* next outer frame. + + Return a :term:`strong reference`, or ``NULL`` if *frame* has no outer + frame. + + *frame* must not be ``NULL``. + + .. versionadded:: 3.9 + + +.. c:function:: PyCodeObject* PyFrame_GetCode(PyFrameObject *frame) + + Get the *frame* code. + + Return a :term:`strong reference`. + + *frame* must not be ``NULL``. The result (frame code) cannot be ``NULL``. + + .. versionadded:: 3.9 + + +.. c:function:: int PyFrame_GetLineNumber(PyFrameObject *frame) + + Return the line number that *frame* is currently executing. + + *frame* must not be ``NULL``. diff --git a/Doc/c-api/reflection.rst b/Doc/c-api/reflection.rst index fe7741a2d7a..4b1c4770848 100644 --- a/Doc/c-api/reflection.rst +++ b/Doc/c-api/reflection.rst @@ -31,35 +31,6 @@ Reflection See also :c:func:`PyThreadState_GetFrame`. -.. c:function:: PyFrameObject* PyFrame_GetBack(PyFrameObject *frame) - - Get the *frame* next outer frame. - - Return a :term:`strong reference`, or ``NULL`` if *frame* has no outer frame. - - *frame* must not be ``NULL``. - - .. versionadded:: 3.9 - - -.. c:function:: PyCodeObject* PyFrame_GetCode(PyFrameObject *frame) - - Get the *frame* code. - - Return a :term:`strong reference`. - - *frame* must not be ``NULL``. The result (frame code) cannot be ``NULL``. - - .. versionadded:: 3.9 - - -.. c:function:: int PyFrame_GetLineNumber(PyFrameObject *frame) - - Return the line number that *frame* is currently executing. - - *frame* must not be ``NULL``. - - .. c:function:: const char* PyEval_GetFuncName(PyObject *func) Return the name of *func* if it is a function, class or instance object, else the diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst index 2f5720d493d..7bd47bb9c66 100644 --- a/Doc/c-api/veryhigh.rst +++ b/Doc/c-api/veryhigh.rst @@ -286,20 +286,6 @@ the same library that the Python runtime is using. ` arguments and a closure tuple of cells. -.. c:type:: PyFrameObject - - The C structure of the objects used to describe frame objects. - - The structure is only part of the internal C API: fields should not be - access directly. Use getter functions like :c:func:`PyFrame_GetCode` and - :c:func:`PyFrame_GetBack`. - - Debuggers and profilers can use the limited C API to access this structure. - - .. versionchanged:: 3.11 - The structure moved to the internal C API headers. - - .. c:function:: PyObject* PyEval_EvalFrame(PyFrameObject *f) Evaluate an execution frame. This is a simplified interface to diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 938a573d595..fe6c2e24c3d 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -968,10 +968,8 @@ Porting to Python 3.11 * ``f_stackdepth``: removed. * ``f_state``: no public API (renamed to ``f_frame.f_state``). * ``f_trace``: no public API. - * ``f_trace_lines``: use ``PyObject_GetAttrString((PyObject*)frame, "f_trace_lines")`` - (it also be modified). - * ``f_trace_opcodes``: use ``PyObject_GetAttrString((PyObject*)frame, "f_trace_opcodes")`` - (it also be modified). + * ``f_trace_lines``: use ``PyObject_GetAttrString((PyObject*)frame, "f_trace_lines")``. + * ``f_trace_opcodes``: use ``PyObject_GetAttrString((PyObject*)frame, "f_trace_opcodes")``. * ``f_localsplus``: no public API (renamed to ``f_frame.localsplus``). * ``f_valuestack``: removed.