python · vstinner · Mar 23, 2022 · Mar 22, 2022 · Mar 22, 2022 · Mar 22, 2022
diff --git 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
@@ -0,0 +1,75 @@
+.. highlight:: c
+
+Frame Objects
+-------------
+
+.. 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 internal C API to access this structure
+   without calling functions, but the internal C API doesn't provide any
+   backward compatibility warranty.
+
+   .. versionchanged:: 3.11
+      The structure moved to the internal C API headers.
+
 Public members:
+
+* ``f_back`` (read only): Next outer frame object (this frame's caller).
+  See also: :c:func:`PyFrame_GetBack`.
+* ``f_builtins`` (read only): Builtins namespace seen by this frame.
+* ``f_code`` (read only): Code object being executed in this frame.
+  See also :c:func:`PyFrame_GetCode`.
+* ``f_globals`` (read only): Global namespace seen by this frame.
+* ``f_lasti`` (read only): Index of last attempted instruction in bytecode.
+* ``f_lineno``: Current line number in Python source code.
+  See also :c:func:`PyFrame_GetLineNumber`.
+* ``f_locals`` (read only): Local namespace seen by this frame.
+* ``f_trace_lines``: Emit ``PyTrace_LINE`` trace events?
+* ``f_trace_opcodes``: Emit ``PyTrace_OPCODE`` trace events?
+* ``f_trace``: Tracing function for this frame, or ``None``
+
+The :c:func:`PyObject_GetAttrString` and :c:func:`PyObject_SetAttrString`
+functions can be used to get and set these members. For example,
+``PyObject_GetAttrString((PyObject*)frame, "f_builtins")`` gets the frame
+builtins namespace.
+
+The :c:func:`PyEval_GetFrame` and :c:func:`PyThreadState_GetFrame` functions
+can be used to get a frame object.
+
+See also :ref:`Reflection <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
@@ -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
@@ -286,20 +286,6 @@ the same library that the Python runtime is using.
    <keyword-only_parameter>` 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
@@ -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.