Protocolo de chamada

O CPython permite dois protocolos de chamada: tp_call e vectorcall.

O protocolo tp_call

Instâncias de classe que definem tp_call são chamáveis. A assinatura do slot é:

PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs);

Uma chamada é feita usando uma tupla para os argumentos posicionais e um dicionário para os argumentos nomeados, similar a callable(*args, **kwargs) no Python. args não pode ser nulo (utilize uma tupla vazia se não houver argumentos), mas kwargs pode ser NULL se não houver argumentos nomeados.

Esta convenção não é somente usada por tp_call: tp_new e tp_init também passam argumento dessa forma.

Para chamar um objeto, use PyObject_Call() ou outra API de chamada.

O protocolo vectorcall

Novo na versão 3.9.

O protocolo vectorcall foi introduzido pela PEP 590 como um protocolo adicional para tornar invocações mais eficientes.

Como regra de ouro, CPython vai preferir o vectorcall para chamadas internas se o chamável suportar. Entretanto, isso não é uma regra rígida. Ademais, alguma extensões de terceiros usam tp_call diretamente (em vez de utilizar PyObject_Call()). Portanto, uma classe que suporta vectorcall precisa também implementar tp_call. Além disso, o chamável precisa se comportar da mesma forma independe de qual protocolo é utilizado. A forma recomendada de alcançar isso é definindo tp_call para PyVectorcall_Call(). Vale a pena repetir:

Aviso

Uma classe que suporte vectorcall também precisa implementar tp_call com a mesma semântica.

Uma classe não deve implementar vectorcall se for mais lento que tp_call. Por exemplo, se o chamador precisa converter os argumentos para uma tupla args e um dicionário kwargs de qualquer forma, então não é necessário implementar vectorcall.

Classes podem implementar o protocolo de chamada de vetor ativando a flag Py_TPFLAGS_HAVE_VECTORCALL e configurando tp_vectorcall_offset para o offset dentro da estrutura do objeto onde uma vectorcallfunc aparece. Este é um ponteiro para uma função com a seguinte assinatura:

typedef PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)

• callable é o objeto sendo chamado.

• args é um array C formado pelos argumentos posicionais seguidos de

  valores dos argumentos nomeados. Este pode ser NULL se não existirem argumentos.

• nargsf é o número de argumentos posicionais somado á possível

  Sinalizador PY_VECTORCALL_ARGUMENTS_OFFSET. Para obter o número real de argumentos posicionais de nargsf, use PyVectorcall_NARGS().

• kwnames é uma tupla contendo os nomes dos argumentos nomeados;

  em outras palavras, as chaves do dicionário kwargs. Estes nomes devem ser strings (instâncias de str ou uma subclasse) e eles devem ser únicos. Se não existem argumentos nomeados, então kwnames deve então ser NULL.

PY_VECTORCALL_ARGUMENTS_OFFSET

Se esse sinalizador é definido em um argumento nargsf do vectorcall, deve ser permitido ao chamado temporariamente mudar args[-1]. Em outras palavras, args aponta para o argumento 1 (não 0) no vetor alocado. O chamado deve restaurar o valor de args[-1] antes de retornar.

Para PyObject_VectorcallMethod(), este sinalizador significa que args[0] pode ser alterado.

Sempre que podem realizar a um custo tão baixo (sem alocações adicionais), invocadores são encorajados a usar PY_VECTORCALL_ARGUMENTS_OFFSET. Isso permitirá invocados como métodos vinculados a instâncias fazerem suas próprias invocações (o que inclui um argumento self) muito eficientemente.

Para invocar um objeto que implementa vectorcall, utilize a função call API como qualquer outra invocável. PyObject_Vectorcall() será normalmente mais eficiente.

Nota

No CPython 3.8, a API vectorcall e funções relacionadas estavam disponíveis provisoriamente sob nomes com um sublinhado inicial: _PyObject_Vectorcall, _Py_TPFLAGS_HAVE_VECTORCALL, _PyObject_VectorcallMethod, _PyVectorcall_Function, _PyObject_CallOneArg, _PyObject_CallMethodNoArgs, _PyObject_CallMethodOneArg. Além disso, PyObject_VectorcallDict estava disponível como _PyObject_FastCallDict. Os nomes antigos ainda estão definidos como apelidos para os novos nomes sem o sublinhado.

Controle de recursão

Quando utilizando tp_call, invocadores não precisam se preocupar sobre recursão: CPython usa Py_EnterRecursiveCall() e Py_LeaveRecursiveCall() para chamadas utilizando tp_call.

Por questão de eficiência, este não é o caso de chamadas utilizando o vectorcall: o que chama deve utilizar Py_EnterRecursiveCall e Py_LeaveRecursiveCall se necessário.

API de suporte à chamada de vetores

Py_ssize_t PyVectorcall_NARGS(size_t nargsf)

Dado um argumento de chamada de vetor nargsf, retorna o número real de argumentos. Atualmente equivalente a:

(Py_ssize_t)(nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET)

Entretanto, a função PyVectorcall_NARGS deve ser usada para permitir para futuras extensões.

Novo na versão 3.8.

vectorcallfunc PyVectorcall_Function(PyObject *op)

Se op não suporta o protocolo de chamada de vetor (seja porque o tipo ou a instância específica não suportam), retorne NULL. Se não, retorne o ponteiro da função chamada de vetor armazenado em op. Esta função nunca levanta uma exceção.

É mais útil checar se op suporta ou não chamada de vetor, o que pode ser feito checando PyVectorcall_Function(op) != NULL.

Novo na versão 3.8.

PyObject *PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict)

Chama o vectorcallfunc de callable com argumentos posicionais e nomeados dados em uma tupla e dicionário, respectivamente.

Esta é uma função especializada, feita para ser colocada no slot tp_call ou usada em uma implementação de tp_call. Ela não checa a flag Py_TPFLAGS_HAVE_VECTORCALL e não retorna para tp_call.

Novo na versão 3.8.

API de chamada de objetos

Várias funções estão disponíveis para chamar um objeto Python. Cada uma converte seus argumentos para uma convenção suportada pelo objeto chamado – seja tp_call ou chamada de vetor. Para fazer o mínimo possível de conversões, escolha um que melhor se adapte ao formato de dados que você tem disponível.

A tabela a seguir resume as funções disponíveis; por favor, veja a documentação individual para detalhes.

Função	chamável	args	kwargs
PyObject_Call()	PyObject *	tupla	dict/NULL
PyObject_CallNoArgs()	PyObject *	—	—
PyObject_CallOneArg()	PyObject *	1 objeto	—
PyObject_CallObject()	PyObject *	tupla/NULL	—
PyObject_CallFunction()	PyObject *	format	—
PyObject_CallMethod()	obj + char*	format	—
PyObject_CallFunctionObjArgs()	PyObject *	variádica	—
PyObject_CallMethodObjArgs()	obj + nome	variádica	—
PyObject_CallMethodNoArgs()	obj + nome	—	—
PyObject_CallMethodOneArg()	obj + nome	1 objeto	—
PyObject_Vectorcall()	PyObject *	vectorcall	vectorcall
PyObject_VectorcallDict()	PyObject *	vectorcall	dict/NULL
PyObject_VectorcallMethod()	arg + nome	vectorcall	vectorcall

PyObject *PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)

Retorna valor: Nova referência. Part of the Stable ABI.

Chama um objeto Python chamável de callable, com argumentos dados pela tupla args, e argumentos nomeados dados pelo dicionário kwargs.

args não deve ser NULL; use uma tupla vazia se não precisar de argumentos. Se nenhum argumento nomeado é necessário, kwargs pode ser NULL.

Retorna o resultado da chamada em sucesso, ou levanta uma exceção e retorna NULL em caso de falha.

Esse é o equivalente da expressão Python: callable(*args, **kwargs).

PyObject *PyObject_CallNoArgs(PyObject *callable)

Part of the Stable ABI since version 3.10.

Chama um objeto Python chamável de callable sem nenhum argumento. É o jeito mais eficiente de chamar um objeto Python sem nenhum argumento.

Retorna o resultado da chamada em sucesso, ou levanta uma exceção e retorna NULL em caso de falha.

Novo na versão 3.9.

PyObject *PyObject_CallOneArg(PyObject *callable, PyObject *arg)

Chama um objeto Python chamável de callable com exatamente 1 argumento posicional arg e nenhum argumento nomeado.

Retorna o resultado da chamada em sucesso, ou levanta uma exceção e retorna NULL em caso de falha.

Novo na versão 3.9.

PyObject *PyObject_CallObject(PyObject *callable, PyObject *args)

Retorna valor: Nova referência. Part of the Stable ABI.

Chama um objeto Python chamável de callable com argumentos dados pela tupla args. Se nenhum argumento é necessário, args pode ser NULL.

Retorna o resultado da chamada em sucesso, ou levanta uma exceção e retorna NULL em caso de falha.

Este é o equivalente da expressão Python: callable(*args).

PyObject *PyObject_CallFunction(PyObject *callable, const char *format, ...)

Retorna valor: Nova referência. Part of the Stable ABI.

Chama um objeto Python chamável de callable, com um número variável de argumentos C. Os argumentos C são descritos usando uma string de estilo no formato Py_BuildValue(). O formato pode ser NULL, indicando que nenhum argumento foi provido.

Retorna o resultado da chamada em sucesso, ou levanta uma exceção e retorna NULL em caso de falha.

Este é o equivalente da expressão Python: callable(*args).

Note que se você apenas passa argumentos PyObject*, PyObject_CallFunctionObjArgs() é uma alternativa mais rápida.

Alterado na versão 3.4: O tipo de format foi mudado de char *.

PyObject *PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)

Retorna valor: Nova referência. Part of the Stable ABI.

Chama o método chamado name do objeto obj com um número variável de argumentos C. Os argumentos C são descritos com uma string de formato Py_BuildValue() que deve produzir uma tupla.

O formato pode ser NULL, indicado que nenhum argumento foi provido.

Retorna o resultado da chamada em sucesso, ou levanta uma exceção e retorna NULL em caso de falha.

Este é o equivalente da expressão Python: obj.name(arg1, arg2, ...).

Note que se você apenas passa argumentos PyObject*, PyObject_CallMethodObjArgs() é uma alternativa mais rápida.

Alterado na versão 3.4: Os tipos de name e format foram mudados de char *.

PyObject *PyObject_CallFunctionObjArgs(PyObject *callable, ...)

Retorna valor: Nova referência. Part of the Stable ABI.

Chama um objeto Python chamável de callable, com um número variável de argumentos PyObject*. Os argumentos são providos como um número variável de parâmetros seguidos por um NULL.

Retorna o resultado da chamada em sucesso, ou levanta uma exceção e retorna NULL em caso de falha.

Este é o equivalente da expressão Python: callable(arg1, arg2, ...).

PyObject *PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ...)

Retorna valor: Nova referência. Part of the Stable ABI.

Chama um método do objeto Python obj, onde o nome do método é dado como um objeto string Python em name. É chamado com um número variável de argumentos PyObject*. Os argumentos são providos como um número variável de parâmetros seguidos por um NULL.

Retorna o resultado da chamada em sucesso, ou levanta uma exceção e retorna NULL em caso de falha.

PyObject *PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)

Chama um método do objeto Python obj sem argumentos, onde o nome do método é fornecido como um objeto string do Python em name.

Retorna o resultado da chamada em sucesso, ou levanta uma exceção e retorna NULL em caso de falha.

Novo na versão 3.9.

PyObject *PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)

Chama um método do objeto Python obj com um argumento posicional arg, onde o nome do método é fornecido como um objeto string do Python em name.

Retorna o resultado da chamada em sucesso, ou levanta uma exceção e retorna NULL em caso de falha.

Novo na versão 3.9.

PyObject *PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)

Chama um objeto Python chamável callable. Os argumentos são os mesmos de vectorcallfunc. Se callable tiver suporte a vectorcall, isso chamará diretamente a função vectorcall armazenada em callable.

Retorna o resultado da chamada em sucesso, ou levanta uma exceção e retorna NULL em caso de falha.

Novo na versão 3.9.

PyObject *PyObject_VectorcallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)

Chama callable com argumentos posicionais passados exatamente como no protocolo vectorcall, mas com argumentos nomeados passados como um dicionário kwdict. O array args contém apenas os argumentos posicionais.

Independentemente de qual protocolo é usado internamente, uma conversão de argumentos precisa ser feita. Portanto, esta função só deve ser usada se o chamador já tiver um dicionário pronto para usar para os argumentos nomeados, mas não uma tupla para os argumentos posicionais.

Novo na versão 3.9.

PyObject *PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)

Chama um método usando a convenção de chamada vectorcall. O nome do método é dado como uma string Python name. O objeto cujo método é chamado é args[0], e o array args começando em args[1] representa os argumentos da chamada. Deve haver pelo menos um argumento posicional. nargsf é o número de argumentos posicionais incluindo args[0], mais PY_VECTORCALL_ARGUMENTS_OFFSET se o valor de args[0] puder ser alterado temporariamente. Argumentos nomeados podem ser passados como em PyObject_Vectorcall().

Se o objeto tem a feature Py_TPFLAGS_METHOD_DESCRIPTOR, isso irá chamar o objeto de método não vinculado com o vetor args inteiro como argumentos.

Retorna o resultado da chamada em sucesso, ou levanta uma exceção e retorna NULL em caso de falha.

Novo na versão 3.9.

API de suporte a chamadas

int PyCallable_Check(PyObject *o)

Part of the Stable ABI.

Determine se o objeto o é chamável. Devolva 1 se o objeto é chamável e 0 caso contrário. Esta função sempre tem êxito.