| 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*. |