Frame objects
*************

type PyFrameObject
    * Part of the Stable ABI (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 "<frameobject.h>".

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 "<frameobject.h>".

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.
