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.