Objetos Function

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_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.

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

Listagem de possíveis eventos de sentinelas de função: - PyFunction_EVENT_CREATE; - PyFunction_EVENT_DESTROY; - PyFunction_EVENT_MODIFY_CODE; - PyFunction_EVENT_MODIFY_DEFAULTS; - PyFunction_EVENT_MODIFY_KWDEFAULTS;

Adicionado na versão 3.12.

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.

Se event for PyFunction_EVENT_DESTROY, então obter uma referência dentro da função de retorno para a função prestes a ser destruída irá revivê-la, impedindo que esta função seja liberada nesse tempo. Quando o objeto revivido for destruído, quaisquer funções de retorno sentinelas ativas nesse momento poderão ser chamadas novamente.

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.