mirror of
https://github.com/python/cpython.git
synced 2025-10-31 10:26:02 +00:00
e870c852c0
* expand on What's New entry for PEP 667 (including porting notes) * define 'optimized scope' as a glossary term * cover comprehensions and generator expressions in locals() docs * review all mentions of "locals" in documentation (updating if needed) * review all mentions of "f_locals" in documentation (updating if needed)
175 lines
4.5 KiB
ReStructuredText
175 lines
4.5 KiB
ReStructuredText
.. highlight:: c
|
|
|
|
Frame Objects
|
|
-------------
|
|
|
|
.. c:type:: PyFrameObject
|
|
|
|
The C structure of the objects used to describe frame objects.
|
|
|
|
There are no public members in this structure.
|
|
|
|
.. versionchanged:: 3.11
|
|
The members of this structure were removed from the public C API.
|
|
Refer to the :ref:`What's New entry <pyframeobject-3.11-hiding>`
|
|
for details.
|
|
|
|
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:var:: PyTypeObject PyFrame_Type
|
|
|
|
The type of frame objects.
|
|
It is the same object as :py:class:`types.FrameType` in the Python layer.
|
|
|
|
.. versionchanged:: 3.11
|
|
|
|
Previously, this type was only available after including
|
|
``<frameobject.h>``.
|
|
|
|
.. c:function:: int PyFrame_Check(PyObject *obj)
|
|
|
|
Return non-zero if *obj* is a frame object.
|
|
|
|
.. versionchanged:: 3.11
|
|
|
|
Previously, this function was only available after including
|
|
``<frameobject.h>``.
|
|
|
|
.. 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.
|
|
|
|
.. versionadded:: 3.9
|
|
|
|
|
|
.. c:function:: PyObject* PyFrame_GetBuiltins(PyFrameObject *frame)
|
|
|
|
Get the *frame*'s :attr:`~frame.f_builtins` attribute.
|
|
|
|
Return a :term:`strong reference`. The result cannot be ``NULL``.
|
|
|
|
.. versionadded:: 3.11
|
|
|
|
|
|
.. c:function:: PyCodeObject* PyFrame_GetCode(PyFrameObject *frame)
|
|
|
|
Get the *frame* code.
|
|
|
|
Return a :term:`strong reference`.
|
|
|
|
The result (frame code) cannot be ``NULL``.
|
|
|
|
.. versionadded:: 3.9
|
|
|
|
|
|
.. c:function:: PyObject* PyFrame_GetGenerator(PyFrameObject *frame)
|
|
|
|
Get the generator, coroutine, or async generator that owns this frame,
|
|
or ``NULL`` if this frame is not owned by a generator.
|
|
Does not raise an exception, even if the return value is ``NULL``.
|
|
|
|
Return a :term:`strong reference`, or ``NULL``.
|
|
|
|
.. versionadded:: 3.11
|
|
|
|
|
|
.. c:function:: PyObject* PyFrame_GetGlobals(PyFrameObject *frame)
|
|
|
|
Get the *frame*'s :attr:`~frame.f_globals` attribute.
|
|
|
|
Return a :term:`strong reference`. The result cannot be ``NULL``.
|
|
|
|
.. versionadded:: 3.11
|
|
|
|
|
|
.. c:function:: int PyFrame_GetLasti(PyFrameObject *frame)
|
|
|
|
Get the *frame*'s :attr:`~frame.f_lasti` attribute.
|
|
|
|
Returns -1 if ``frame.f_lasti`` is ``None``.
|
|
|
|
.. versionadded:: 3.11
|
|
|
|
|
|
.. c:function:: PyObject* PyFrame_GetVar(PyFrameObject *frame, PyObject *name)
|
|
|
|
Get the variable *name* of *frame*.
|
|
|
|
* Return a :term:`strong reference` to the variable value on success.
|
|
* Raise :exc:`NameError` and return ``NULL`` if the variable does not exist.
|
|
* Raise an exception and return ``NULL`` on error.
|
|
|
|
*name* type must be a :class:`str`.
|
|
|
|
.. versionadded:: 3.12
|
|
|
|
|
|
.. c:function:: PyObject* PyFrame_GetVarString(PyFrameObject *frame, const char *name)
|
|
|
|
Similar to :c:func:`PyFrame_GetVar`, but the variable name is a C string
|
|
encoded in UTF-8.
|
|
|
|
.. versionadded:: 3.12
|
|
|
|
|
|
.. c:function:: PyObject* PyFrame_GetLocals(PyFrameObject *frame)
|
|
|
|
Get the *frame*'s :attr:`~frame.f_locals` attribute.
|
|
If the frame refers to an :term:`optimized scope`, this returns a
|
|
write-through proxy object that allows modifying the locals.
|
|
In all other cases (classes, modules, :func:`exec`, :func:`eval`) it returns
|
|
the mapping representing the frame locals directly (as described for
|
|
:func:`locals`).
|
|
|
|
Return a :term:`strong reference`.
|
|
|
|
.. versionadded:: 3.11
|
|
|
|
.. versionchanged:: 3.13
|
|
As part of :pep:`667`, return a proxy object for optimized scopes.
|
|
|
|
|
|
.. c:function:: int PyFrame_GetLineNumber(PyFrameObject *frame)
|
|
|
|
Return the line number that *frame* is currently executing.
|
|
|
|
|
|
|
|
Internal Frames
|
|
^^^^^^^^^^^^^^^
|
|
|
|
Unless using :pep:`523`, you will not need this.
|
|
|
|
.. c:struct:: _PyInterpreterFrame
|
|
|
|
The interpreter's internal frame representation.
|
|
|
|
.. versionadded:: 3.11
|
|
|
|
.. c:function:: PyObject* PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame *frame);
|
|
|
|
Return a :term:`strong reference` to the code object for the frame.
|
|
|
|
.. versionadded:: 3.12
|
|
|
|
|
|
.. c:function:: int PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame);
|
|
|
|
Return the byte offset into the last executed instruction.
|
|
|
|
.. versionadded:: 3.12
|
|
|
|
|
|
.. c:function:: int PyUnstable_InterpreterFrame_GetLine(struct _PyInterpreterFrame *frame);
|
|
|
|
Return the currently executing line number, or -1 if there is no line number.
|
|
|
|
.. versionadded:: 3.12
|
|
|
|
|