Objetos Frame
*************

type PyFrameObject
    * Parte da API Limitada (como uma estrutura opaca).*

   A estrutura C dos objetos usados para descrever objetos frame.

   Não há membros públicos nesta estrutura.

   Alterado na versão 3.11: Os membros dessa estrutura foram removidos
   da API C pública. Consulte a entrada O Que há de Novo para
   detalhes.

As funções "PyEval_GetFrame()" e "PyThreadState_GetFrame()" podem ser
utilizadas para obter um objeto frame.

Veja também Reflexão.

PyTypeObject PyFrame_Type

   O tipo de objetos frame. É o mesmo objeto que "types.FrameType" na
   camada Python.

   Alterado na versão 3.11: Anteriormente, este tipo só estava
   disponível após incluir "<frameobject.h>".

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

   Cria um novo objeto quadro. Esta função retorna uma *referência
   forte* ao novo objeto quadro em caso de sucesso e retorna "NULL"
   com uma exceção definida em caso de falha.

int PyFrame_Check(PyObject *obj)

   Retorna diferente de zero se *obj* é um objeto frame

   Alterado na versão 3.11: Anteriormente, esta função só estava
   disponível após incluir "<frameobject.h>".

PyFrameObject *PyFrame_GetBack(PyFrameObject *frame)
    *Retorna valor: Nova referência.*

   Obtém o *frame* próximo ao quadro externo.

   Retorna uma *referência forte* ou "NULL" se *frame* não tiver
   quadro externo.

   Adicionado na versão 3.9.

PyObject *PyFrame_GetBuiltins(PyFrameObject *frame)
    *Retorna valor: Nova referência.*

   Obtém o atributo "f_builtins" do *frame*.

   Retorna uma *referência forte*. O resultado não pode ser "NULL".

   Adicionado na versão 3.11.

PyCodeObject *PyFrame_GetCode(PyFrameObject *frame)
    *Retorna valor: Nova referência.** Parte da ABI Estável desde a
   versão 3.10.*

   Obtém o código de *frame*.

   Retorna uma *referência forte*.

   O resultado (código do frame) não pode ser "NULL".

   Adicionado na versão 3.9.

PyObject *PyFrame_GetGenerator(PyFrameObject *frame)
    *Retorna valor: Nova referência.*

   Obtém o gerador, corrotina ou gerador assíncrono que possui este
   frame, ou "NULL" se o frame não pertence a um gerador. Não levanta
   exceção, mesmo que o valor retornado seja "NULL".

   Retorna uma *referência forte*, ou "NULL".

   Adicionado na versão 3.11.

PyObject *PyFrame_GetGlobals(PyFrameObject *frame)
    *Retorna valor: Nova referência.*

   Obtenha o atributo "f_globals" do *frame*.

   Retorna uma *referência forte*. O resultado não pode ser "NULL".

   Adicionado na versão 3.11.

int PyFrame_GetLasti(PyFrameObject *frame)

   Obtenha o atributo "f_lasti" do *frame*.

   Retorna -1 se "frame.f_lasti" é "None".

   Adicionado na versão 3.11.

PyObject *PyFrame_GetVar(PyFrameObject *frame, PyObject *name)
    *Retorna valor: Nova referência.*

   Obtém a variável *name* de *frame*.

   * Retorna uma *referência forte* ao valor da variável em caso de
     sucesso.

   * Levanta uma exceção "NameError" e retorna "NULL" se a variável
     não existir.

   * Levanta uma exceção e retorna "NULL" em caso de erro.

   Tipo de *name* deve ser um "str".

   Adicionado na versão 3.12.

PyObject *PyFrame_GetVarString(PyFrameObject *frame, const char *name)
    *Retorna valor: Nova referência.*

   Semelhante a "PyFrame_GetVar()", mas o nome da variável é uma
   string C codificada em UTF-8.

   Adicionado na versão 3.12.

PyObject *PyFrame_GetLocals(PyFrameObject *frame)
    *Retorna valor: Nova referência.*

   Obtém o atributo "f_locals" do *frame*. Se o quadro se referir a um
   *escopo otimizado*, isso retorna um objeto proxy de escrita direta
   que permite modificar as variáveis locais. Em todos os outros casos
   (classes, módulos, "exec()" e "eval()"), retorna o mapeamento que
   representa as variáveis locais do frame diretamente (como descrito
   para "locals()").

   Retorna uma *referência forte*.

   Adicionado na versão 3.11.

   Alterado na versão 3.13: Como parte de **PEP 667**, retorna uma
   instância de "PyFrameLocalsProxy_Type".

int PyFrame_GetLineNumber(PyFrameObject *frame)
    * Parte da ABI Estável desde a versão 3.10.*

   Retorna o número da linha do *frame* atualmente em execução.


Frame Locals Proxies
====================

Adicionado na versão 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)

   This function is *soft deprecated* and does nothing.

   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.

   Alterado na versão 3.13: Esta função agora não faz nada.

void PyFrame_FastToLocals(PyFrameObject *f)

   This function is *soft deprecated* and does nothing.

   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.

   Alterado na versão 3.13: Esta função agora não faz nada.

int PyFrame_FastToLocalsWithError(PyFrameObject *f)

   This function is *soft deprecated* and does nothing.

   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.

   Alterado na versão 3.13: Esta função agora não faz nada.

Ver também: **PEP 667**


Internal Frames
===============

Unless using **PEP 523**, you will not need this.

struct _PyInterpreterFrame

   The interpreter's internal frame representation.

   Adicionado na versão 3.11.

PyObject *PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame *frame);

   *Esta é uma API Instável. Isso pode se alterado sem aviso em
   lançamentos menores.*

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

   Adicionado na versão 3.12.

int PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame);

   *Esta é uma API Instável. Isso pode se alterado sem aviso em
   lançamentos menores.*

   Return the byte offset into the last executed instruction.

   Adicionado na versão 3.12.

int PyUnstable_InterpreterFrame_GetLine(struct _PyInterpreterFrame *frame);

   *Esta é uma API Instável. Isso pode se alterado sem aviso em
   lançamentos menores.*

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

   Adicionado na versão 3.12.
