Objetos Função

Existem algumas funções específicas para as funções do Python.

type PyFunctionObject

A estrutura C usada para funções.

PyTypeObject PyFunction_Type

Esta é uma instância de PyTypeObject e representa o tipo de função Python. Está exposta a programadores Python como types.FunctionType.

int PyFunction_Check(PyObject *o)

Retorna verdadeiro se o for um objeto função (tem tipo PyFunction_Type). O parâmetro não deve ser NULL. Esta função sempre obtém sucesso.

PyObject *PyFunction_New(PyObject *code, PyObject *globals)
Retorna valor: Nova referência.

Retorna um novo objeto função associado ao objeto código code. globals deve ser um dicionário com as variáveis globais acessíveis à função.

O nome e docstring da função são adquiridos pelo objeto código. O atributo __module__ é adquirido por meio de globals. Os valores-padrão de argumentos, anotações, e fechamento são definidos como NULL. O atributo __qualname__ é definido com o mesmo valor do campo co_qualname de um objeto código.

PyObject *PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)
Retorna valor: Nova referência.

Similar a PyFunction_New(), mas também permite definir o atributo __qualname__ do objeto função. qualname deve ser um objeto Unicode ou NULL. Se NULL, o atributo __qualname__ é definido com o mesmo valor do campo co_qualname do objeto código.

Adicionado na versão 3.3.

PyObject *PyFunction_GetCode(PyObject *op)
Retorna valor: Referência emprestada.

Retorna o objeto código associado ao objeto função op.

PyObject *PyFunction_GetGlobals(PyObject *op)
Retorna valor: Referência emprestada.

Retorna o dicionário global associado ao objeto função op.

PyObject *PyFunction_GetModule(PyObject *op)
Retorna valor: Referência emprestada.

Retorna uma referência emprestada ao atributo __module__ do objeto função op. Pode ser NULL.

Normalmente, trata-se de um string contendo o nome do módulo, mas pode ser definido como qualquer outro objeto pelo código Python.

PyObject *PyFunction_GetDefaults(PyObject *op)
Retorna valor: Referência emprestada.

Retorna os valores-padrão de argumentos do objeto função op. Pode ser uma tupla de argumentos ou NULL.

int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)

Define os valores-padrão dos argumentos do objeto função op. defaults deve ser Py_None ou uma tupla.

Levanta SystemError e retorna -1 em caso de falha.

void PyFunction_SetVectorcall(PyFunctionObject *func, vectorcallfunc vectorcall)

Define o campo vectorcall de um objeto função func.

Atenção: extensões que usam essa API devem preservar o comportamento inalterado (padrão) de uma função vectorcall!

Adicionado na versão 3.12.

PyObject *PyFunction_GetKwDefaults(PyObject *op)
Retorna valor: Referência emprestada.

Retorna os valores-padrão de argumentos somente-nomeados do objeto função op. Pode ser um dicionário de argumentos ou NULL.

PyObject *PyFunction_GetClosure(PyObject *op)
Retorna valor: Referência emprestada.

Retorna o fechamento associado ao objeto função op. Pode ser NULL ou uma tupla de objetos célula.

int PyFunction_SetClosure(PyObject *op, PyObject *closure)

Define o fechamento associado ao objeto função op. closure deve ser Py_None ou uma tupla de objetos de célula.

Levanta SystemError e retorna -1 em caso de falha.

PyObject *PyFunction_GetAnnotations(PyObject *op)
Retorna valor: Referência emprestada.

Retorna as anotações do objeto função op. Este pode ser um dicionário mutável ou NULL.

int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)

Define as anotações para o objeto função op. annotations deve ser um dicionário ou Py_None.

Levanta SystemError e retorna -1 em caso de falha.

PyObject *PyFunction_GET_CODE(PyObject *op)
PyObject *PyFunction_GET_GLOBALS(PyObject *op)
PyObject *PyFunction_GET_MODULE(PyObject *op)
PyObject *PyFunction_GET_DEFAULTS(PyObject *op)
PyObject *PyFunction_GET_KW_DEFAULTS(PyObject *op)
PyObject *PyFunction_GET_CLOSURE(PyObject *op)
PyObject *PyFunction_GET_ANNOTATIONS(PyObject *op)
Retorna valor: Referência emprestada.

Essas funções são semelhantes às suas contrapartes PyFunction_Get*, mas não realizam verificação de tipos. Passar qualquer coisa que não seja uma instância de PyFunction_Type é um comportamento indefinido.

int PyFunction_AddWatcher(PyFunction_WatchCallback callback)

Registra callback como uma sentinela de função para o interpretador atual. Retorna um ID que pode ser passado para PyFunction_ClearWatcher(). Em caso de erro (por exemplo, sem novos IDs de sentinelas disponíveis), retorna -1 e define uma exceção.

Adicionado na versão 3.12.

int PyFunction_ClearWatcher(int watcher_id)

Cancela o registro da sentinela identificada pelo watcher_id retornado por PyFunction_AddWatcher() para o interpretador atual. Retorna 0 em caso de sucesso, ou -1 e define uma exceção em caso de erro (por exemplo, ao receber um watcher_id desconhecido.)

Adicionado na versão 3.12.

type PyFunction_WatchEvent

Enumeração de possíveis eventos do observador de funções:

  • PyFunction_EVENT_CREATE

  • PyFunction_EVENT_DESTROY

  • PyFunction_EVENT_MODIFY_CODE

  • PyFunction_EVENT_MODIFY_DEFAULTS

  • PyFunction_EVENT_MODIFY_KWDEFAULTS

Adicionado na versão 3.12:

  • PyFunction_PYFUNC_EVENT_MODIFY_QUALNAME

Adicionado na versão 3.15.

typedef int (*PyFunction_WatchCallback)(PyFunction_WatchEvent event, PyFunctionObject *func, PyObject *new_value)

Tipo de uma função de retorno de sentinela de função.

Se event for PyFunction_EVENT_CREATE ou PyFunction_EVENT_DESTROY, new_value será NULL. Senão, new_value portará uma referência emprestada ao novo valor prestes a ser guardado em func para o atributo que está sendo modificado.

A função de retorno poderá somente inspecionar, e não modificar func. Caso contrário, poderíamos ter efeitos imprevisíveis, incluindo recursão infinita.

Se event for PyFunction_EVENT_CREATE, a função de retorno será invocada após func ter sido completamente inicializada. Caso contrário, a função de retorno será invocada antes de modificar func, então o estado anterior de func poderá ser inspecionado. O ambiente de execução pode otimizar a criação de objetos função, quando possível, ao ignorá-las. Nesses casos, nenhum evento será emitido. Apesar de decisões de otimização criarem diferenças de comportamento em tempo de execução, elas não mudam a semântica do código Python sendo executado.

If event is PyFunction_EVENT_DESTROY, taking a reference in the callback to the about-to-be-destroyed function will resurrect it, preventing it from being freed at this time. When the resurrected object is destroyed later, any watcher callbacks active at that time will be called again.

Se a função de retorno definir uma exceção, ela deverá retornar -1. Essa exceção será exibida como uma exceção não levantável usando PyErr_WriteUnraisable(). Caso contrário, deverá retornar 0.

É possível que já exista uma exceção pendente definida na entrada da função de retorno. Nesse caso, a função de retorno deve retornar 0 com a mesma exceção ainda definida. Isso significa que a função de retorno não pode chamar nenhuma outra API que possa definir uma exceção, a menos que salve e limpe o estado da exceção primeiro e restaure a exceção antes de retornar.

Adicionado na versão 3.12.