Frame objects#

type PyFrameObject * Part of the Limited API (as an opaque struct).*

La estructura C de los objetos utilizados para describir los objetos del frame.

No hay miembros públicos en esta estructura.

Distinto en la versión 3.11: Los miembros de esta estructura se han eliminado de la API pública de C. Consulte la entrada Novedades para más detalles.

Las funciones "PyEval_GetFrame()" y "PyThreadState_GetFrame()" pueden utilizarse para obtener un objeto frame.

Véase también Reflexión.

PyTypeObject PyFrame_Type

The type of frame objects. It is the same object as "types.FrameType" in the Python layer.

Distinto en la versión 3.11: Previously, this type was only available after including "".

PyFrameObject PyFrame_New(PyThreadState tstate, PyCodeObject code, PyObject globals, PyObject *locals)

Create a new frame object. This function returns a strong reference to the new frame object on success, and returns "NULL" with an exception set on failure.

int PyFrame_Check(PyObject *obj)

Return non-zero if obj is a frame object.

Distinto en la versión 3.11: Previously, this function was only available after including "".

PyFrameObject PyFrame_GetBack(PyFrameObject frame) Return value: New reference.

Obtiene el frame exterior siguiente.

Return a strong reference, or "NULL" if frame has no outer frame. This raises no exceptions.

Added in version 3.9.

PyObject PyFrame_GetBuiltins(PyFrameObject frame) Return value: New reference.

Get the frame's "f_builtins" attribute.

Retorna una strong reference, o "NULL" si frame no tiene frame exterior.

Added in version 3.11.

PyCodeObject PyFrame_GetCode(PyFrameObject frame) Return value: New reference. Part of the Stable ABI since version 3.10.

Obtenga el código frame.

Retorna un strong reference.

El resultado (frame code) no puede ser "NULL".

Added in version 3.9.

PyObject PyFrame_GetGenerator(PyFrameObject frame) Return value: New reference.

Obtiene el generador, rutina o generador asíncrono al que pertenece este frame, o "NULL" si este frame no es propiedad de un generador. No lanza una excepción, incluso si el valor de retorno es "NULL".

Retorna un strong reference, o "NULL".

Added in version 3.11.

PyObject PyFrame_GetGlobals(PyFrameObject frame) Return value: New reference.

Get the frame's "f_globals" attribute.

Retorna una strong reference, o "NULL" si frame no tiene frame exterior.

Added in version 3.11.

int PyFrame_GetLasti(PyFrameObject *frame)

Get the frame's "f_lasti" attribute.

Retorna -1 si "frame.f_lasti" es "None".

Added in version 3.11.

PyObject PyFrame_GetVar(PyFrameObject frame, PyObject name) Return value: New reference.*

Get the variable name of frame.

• Return a strong reference to the variable value on success.

• Raise "NameError" and return "NULL" if the variable does not exist.

• Raise an exception and return "NULL" on error.

name type must be a "str".

Added in version 3.12.

PyObject PyFrame_GetVarString(PyFrameObject frame, const char name) Return value: New reference.*

Similar to "PyFrame_GetVar()", but the variable name is a C string encoded in UTF-8.

Added in version 3.12.

PyObject PyFrame_GetLocals(PyFrameObject frame) Return value: New reference.

Get the frame's "f_locals" attribute. If the frame refers to an optimized scope, this returns a write-through proxy object that allows modifying the locals. In all other cases (classes, modules, "exec()", "eval()") it returns the mapping representing the frame locals directly (as described for "locals()").

Retorna un strong reference.

Added in version 3.11.

Distinto en la versión 3.13: As part of PEP 667, return an instance of "PyFrameLocalsProxy_Type".

int PyFrame_GetLineNumber(PyFrameObject frame) * Part of the Stable ABI since version 3.10.

Retorna el número de línea en la que se está ejecutando el frame.

Frame locals proxies#

Added in version 3.13.

The "f_locals" attribute on a frame object is an instance of a "frame- locals proxy". The proxy object exposes a write-through view of the underlying locals dictionary for the frame. This ensures that the variables exposed by "f_locals" are always up to date with the live local variables in the frame itself.

See PEP 667 for more information.

PyTypeObject PyFrameLocalsProxy_Type

The type of frame "locals()" proxy objects.

int PyFrameLocalsProxy_Check(PyObject *obj)

Return non-zero if obj is a frame "locals()" proxy.

Legacy local variable APIs#

These APIs are soft deprecated. As of Python 3.13, they do nothing. They exist solely for backwards compatibility.

void PyFrame_LocalsToFast(PyFrameObject *f, int clear)

Prior to Python 3.13, this function would copy the "f_locals" attribute of f to the internal "fast" array of local variables, allowing changes in frame objects to be visible to the interpreter. If clear was true, this function would process variables that were unset in the locals dictionary.

Soft deprecated since version 3.13: This function now does nothing.

void PyFrame_FastToLocals(PyFrameObject *f)

Prior to Python 3.13, this function would copy the internal "fast" array of local variables (which is used by the interpreter) to the "f_locals" attribute of f, allowing changes in local variables to be visible to frame objects.

Soft deprecated since version 3.13: This function now does nothing.

int PyFrame_FastToLocalsWithError(PyFrameObject *f)

Prior to Python 3.13, this function was similar to "PyFrame_FastToLocals()", but would return "0" on success, and "-1" with an exception set on failure.

Soft deprecated since version 3.13: This function now does nothing.

Ver también: PEP 667

Internal frames#

Unless using PEP 523, you will not need this.

struct _PyInterpreterFrame

The interpreter's internal frame representation.

Added in version 3.11.

PyObject PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame frame);

This is Unstable API. It may change without warning in minor releases.

  Return a *strong reference* to the code object for the frame.

Added in version 3.12.

int PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame);

This is Unstable API. It may change without warning in minor releases.

Return the byte offset into the last executed instruction.

Added in version 3.12.

int PyUnstable_InterpreterFrame_GetLine(struct _PyInterpreterFrame *frame);

This is Unstable API. It may change without warning in minor releases.

Return the currently executing line number, or -1 if there is no line number.

Added in version 3.12.

const PyTypeObject *PyUnstable_ExecutableKinds

This is Unstable API. It may change without warning in minor releases.

An array of executable kinds (executor types) for frames, used for internal debugging and tracing.

Tools like debuggers and profilers can use this to identify the type of execution context associated with a frame (such as to filter out internal frames). The entries are indexed by the following constants:

+----------------------------------------------------+----------------------------------------------------+ | Constant | Description | |====================================================|====================================================| | PyUnstable_EXECUTABLE_KIND_SKIP This is Unstable | The frame is internal (For example: inlined) and | | API. It may change without warning in minor | should be skipped by tools. | | releases. | | +----------------------------------------------------+----------------------------------------------------+ | PyUnstable_EXECUTABLE_KIND_PY_FUNCTION This is | The frame corresponds to a standard Python | | Unstable API. It may change without warning in | function. | | minor releases. | | +----------------------------------------------------+----------------------------------------------------+ | PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION This | The frame corresponds to a function defined in | | is Unstable API. It may change without warning in | native code. | | minor releases. | | +----------------------------------------------------+----------------------------------------------------+ | PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR | The frame corresponds to a method on a class | | This is Unstable API. It may change without | instance. | | warning in minor releases. | | +----------------------------------------------------+----------------------------------------------------+

However, Python's C API lacks a function to read the executable kind from a frame. Instead, use this recipe:

  int
  get_executable_kind(PyFrameObject *frame)
  {
     _PyInterpreterFrame *f = frame->f_frame;
     PyObject *exec = PyStackRef_AsPyObjectBorrow(f->f_executable);

     if (PyCode_Check(exec)) {
        return PyUnstable_EXECUTABLE_KIND_PY_FUNCTION;
     }
     if (PyMethod_Check(exec)) {
        return PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION;
     }
     if (Py_IS_TYPE(exec, &PyMethodDescr_Type)) {
        return PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR;
     }

     return PyUnstable_EXECUTABLE_KIND_SKIP;
  }

Added in version 3.13.

PyUnstable_EXECUTABLE_KINDS

This is Unstable API. It may change without warning in minor releases.

The number of entries in "PyUnstable_ExecutableKinds".

Added in version 3.13.