Debian Codegraph @

Doc/c-api/reflection.rst

raw
1 .. highlight:: c
2
3 .. _reflection:
4
5 Reflection
6 ==========
7
8 .. c:function:: PyObject* PyEval_GetBuiltins(void)
9
10 .. deprecated:: 3.13
11
12 Use :c:func:`PyEval_GetFrameBuiltins` instead.
13
14 Return a dictionary of the builtins in the current execution frame,
15 or the interpreter of the thread state if no frame is currently executing.
16
17
18 .. c:function:: PyObject* PyEval_GetLocals(void)
19
20 .. deprecated:: 3.13
21
22 Use either :c:func:`PyEval_GetFrameLocals` to obtain the same behaviour as calling
23 :func:`locals` in Python code, or else call :c:func:`PyFrame_GetLocals` on the result
24 of :c:func:`PyEval_GetFrame` to access the :attr:`~frame.f_locals` attribute of the
25 currently executing frame.
26
27 Return a mapping providing access to the local variables in the current execution frame,
28 or ``NULL`` if no frame is currently executing.
29
30 Refer to :func:`locals` for details of the mapping returned at different scopes.
31
32 As this function returns a :term:`borrowed reference`, the dictionary returned for
33 :term:`optimized scopes <optimized scope>` is cached on the frame object and will remain
34 alive as long as the frame object does. Unlike :c:func:`PyEval_GetFrameLocals` and
35 :func:`locals`, subsequent calls to this function in the same frame will update the
36 contents of the cached dictionary to reflect changes in the state of the local variables
37 rather than returning a new snapshot.
38
39 .. versionchanged:: 3.13
40 As part of :pep:`667`, :c:func:`PyFrame_GetLocals`, :func:`locals`, and
41 :attr:`FrameType.f_locals <frame.f_locals>` no longer make use of the shared cache
42 dictionary. Refer to the :ref:`What's New entry <whatsnew313-locals-semantics>` for
43 additional details.
44
45
46 .. c:function:: PyObject* PyEval_GetGlobals(void)
47
48 .. deprecated:: 3.13
49
50 Use :c:func:`PyEval_GetFrameGlobals` instead.
51
52 Return a dictionary of the global variables in the current execution frame,
53 or ``NULL`` if no frame is currently executing.
54
55
56 .. c:function:: PyFrameObject* PyEval_GetFrame(void)
57
58 Return the :term:`attached thread state`'s frame, which is ``NULL`` if no frame is
59 currently executing.
60
61 See also :c:func:`PyThreadState_GetFrame`.
62
63
64 .. c:function:: PyObject* PyEval_GetFrameBuiltins(void)
65
66 Return a dictionary of the builtins in the current execution frame,
67 or the interpreter of the thread state if no frame is currently executing.
68
69 .. versionadded:: 3.13
70
71
72 .. c:function:: PyObject* PyEval_GetFrameLocals(void)
73
74 Return a dictionary of the local variables in the current execution frame,
75 or ``NULL`` if no frame is currently executing. Equivalent to calling
76 :func:`locals` in Python code.
77
78 To access :attr:`~frame.f_locals` on the current frame without making an independent
79 snapshot in :term:`optimized scopes <optimized scope>`, call :c:func:`PyFrame_GetLocals`
80 on the result of :c:func:`PyEval_GetFrame`.
81
82 .. versionadded:: 3.13
83
84
85 .. c:function:: PyObject* PyEval_GetFrameGlobals(void)
86
87 Return a dictionary of the global variables in the current execution frame,
88 or ``NULL`` if no frame is currently executing. Equivalent to calling
89 :func:`globals` in Python code.
90
91 .. versionadded:: 3.13
92
93
94 .. c:function:: const char* PyEval_GetFuncName(PyObject *func)
95
96 Return the name of *func* if it is a function, class or instance object, else the
97 name of *func*\s type.
98
99
100 .. c:function:: const char* PyEval_GetFuncDesc(PyObject *func)
101
102 Return a description string, depending on the type of *func*.
103 Return values include "()" for functions and methods, " constructor",
104 " instance", and " object". Concatenated with the result of
105 :c:func:`PyEval_GetFuncName`, the result will be a description of
106 *func*.