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.
