mirror of
https://github.com/python/cpython
synced 2024-09-05 00:05:39 +00:00
bpo-46836: Add Doc/c-api/frame.rst (GH-32051)
Reorganize the documentation of the PyFrameObject C API.
This commit is contained in:
parent
3ac4e783e0
commit
b0f886d1bc
|
@ -111,6 +111,7 @@ Other Objects
|
|||
memoryview.rst
|
||||
weakref.rst
|
||||
capsule.rst
|
||||
frame.rst
|
||||
gen.rst
|
||||
coro.rst
|
||||
contextvars.rst
|
||||
|
|
48
Doc/c-api/frame.rst
Normal file
48
Doc/c-api/frame.rst
Normal file
|
@ -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 <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``.
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
Loading…
Reference in a new issue