1.. highlight:: c
2
3Frame Objects
4-------------
5
6.. c:type:: PyFrameObject
7
8   The C structure of the objects used to describe frame objects.
9
10   There are no public members in this structure.
11
12   .. versionchanged:: 3.11
13      The members of this structure were removed from the public C API.
14      Refer to the :ref:`What's New entry <pyframeobject-3.11-hiding>`
15      for details.
16
17The :c:func:`PyEval_GetFrame` and :c:func:`PyThreadState_GetFrame` functions
18can be used to get a frame object.
19
20See also :ref:`Reflection <reflection>`.
21
22.. c:var:: PyTypeObject PyFrame_Type
23
24   The type of frame objects.
25   It is the same object as :py:class:`types.FrameType` in the Python layer.
26
27   .. versionchanged:: 3.11
28
29      Previously, this type was only available after including
30      ``<frameobject.h>``.
31
32.. c:function:: int PyFrame_Check(PyObject *obj)
33
34   Return non-zero if *obj* is a frame object.
35
36   .. versionchanged:: 3.11
37
38      Previously, this function was only available after including
39      ``<frameobject.h>``.
40
41.. c:function:: PyFrameObject* PyFrame_GetBack(PyFrameObject *frame)
42
43   Get the *frame* next outer frame.
44
45   Return a :term:`strong reference`, or ``NULL`` if *frame* has no outer
46   frame.
47
48   .. versionadded:: 3.9
49
50
51.. c:function:: PyObject* PyFrame_GetBuiltins(PyFrameObject *frame)
52
53   Get the *frame*'s ``f_builtins`` attribute.
54
55   Return a :term:`strong reference`. The result cannot be ``NULL``.
56
57   .. versionadded:: 3.11
58
59
60.. c:function:: PyCodeObject* PyFrame_GetCode(PyFrameObject *frame)
61
62   Get the *frame* code.
63
64   Return a :term:`strong reference`.
65
66   The result (frame code) cannot be ``NULL``.
67
68   .. versionadded:: 3.9
69
70
71.. c:function:: PyObject* PyFrame_GetGenerator(PyFrameObject *frame)
72
73   Get the generator, coroutine, or async generator that owns this frame,
74   or ``NULL`` if this frame is not owned by a generator.
75   Does not raise an exception, even if the return value is ``NULL``.
76
77   Return a :term:`strong reference`, or ``NULL``.
78
79   .. versionadded:: 3.11
80
81
82.. c:function:: PyObject* PyFrame_GetGlobals(PyFrameObject *frame)
83
84   Get the *frame*'s ``f_globals`` attribute.
85
86   Return a :term:`strong reference`. The result cannot be ``NULL``.
87
88   .. versionadded:: 3.11
89
90
91.. c:function:: int PyFrame_GetLasti(PyFrameObject *frame)
92
93   Get the *frame*'s ``f_lasti`` attribute.
94
95   Returns -1 if ``frame.f_lasti`` is ``None``.
96
97   .. versionadded:: 3.11
98
99
100.. c:function:: PyObject* PyFrame_GetLocals(PyFrameObject *frame)
101
102   Get the *frame*'s ``f_locals`` attribute (:class:`dict`).
103
104   Return a :term:`strong reference`.
105
106   .. versionadded:: 3.11
107
108
109.. c:function:: int PyFrame_GetLineNumber(PyFrameObject *frame)
110
111   Return the line number that *frame* is currently executing.
112