# 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`.

int PyFunction_SetKwDefaults(PyObject *op, PyObject *defaults)

  Define os valores padrão dos argumentos somente-nomeados do objeto função op. defaults deve ser um dicionário de argumentos somente-nomeados ou `Py_None`.

  Esta função retorna `0` em caso de sucesso e retorna `-1` com uma exceção definida em caso de falha.

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.