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.

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.
