Протокол вызова

Протокол tp_call

Экземпляры классов, которые устанавливают tp_call, являются вызываемыми. Подпись слота:

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

Вызов выполняется с помощью кортежа для позиционных аргументов и словаря для именованных аргументов, аналогично callable(*args, **kwargs) в коде Python. args должен быть не NULL (используйте пустой кортеж, если аргументов нет), но kwargs может быть NULL, если именованных аргументов нет.

Эта соглашение используется не только в tp_call: tp_new и tp_init также передают аргументы таким образом.

Для вызова объекта используйте PyObject_Call() или другой API вызова.

Протокол Vectorcall

Протокол vectorcall был представлен в PEP 590 как дополнительный протокол для повышения эффективности вызовов.

Как правило, CPython будет отдавать предпочтение vectorcall для внутренних вызовов, если вызываемый объект его поддерживает. Однако это не жёсткое правило. Кроме того, некоторые сторонние расширения используют tp_call напрямую (а не PyObject_Call()). Поэтому класс, поддерживающий vectorcall, должен также реализовывать tp_call. Кроме того, вызываемый объект должен вести себя одинаково независимо от используемого протокола. Рекомендуемый способ достижения этого — установить tp_call в PyVectorcall_Call(). Повторим:

Класс не должен реализовывать vectorcall, если это будет медленнее, чем tp_call. Например, если вызываемому объекту все равно необходимо преобразовать аргументы в кортеж args и словарь kwargs, нет смысла реализовывать vectorcall.

Классы могут реализовывать протокол vectorcall, включив флаг Py_TPFLAGS_HAVE_VECTORCALL и установив tp_vectorcall_offset в смещение внутри структуры объекта, где появляется vectorcallfunc. Это указатель на функцию со следующей подписью:

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

Часть Стабильной ABI с версии 3.12.

• callable — вызываемый объект.

• args — массив C, состоящий из позиционных аргументов, за которыми следуют

  значения именованных аргументов. Может быть NULL, если аргументов нет.

• nargsf — количество позиционных аргументов плюс, возможно,

  флаг PY_VECTORCALL_ARGUMENTS_OFFSET. Чтобы получить фактическое количество позиционных аргументов из nargsf, используйте PyVectorcall_NARGS().

• kwnames — кортеж, содержащий имена именованных аргументов;

  другими словами, ключи словаря kwargs. Эти имена должны быть строками (экземпляры str или подкласса) и должны быть уникальными. Если именованных аргументов нет, то kwnames может быть NULL.

PY_VECTORCALL_ARGUMENTS_OFFSET

Часть Стабильной ABI с версии 3.12.

Если этот флаг установлен в аргументе nargsf vectorcall, вызываемому объекту разрешено временно изменить args[-1]. Другими словами, args указывает на аргумент 1 (а не 0) в выделенном векторе. Вызываемый объект должен восстановить значение args[-1] перед возвратом.

Для PyObject_VectorcallMethod() этот флаг означает, что args[0] может быть изменён.

В тех случаях, когда это можно сделать с небольшой затратой (без дополнительного выделения), вызывающим сторонам рекомендуется использовать PY_VECTORCALL_ARGUMENTS_OFFSET. Это позволит вызываемым объектам, таким как связанные методы, выполнять последующие вызовы (включая предварительно добавленный аргумент self) очень эффективно.

Добавлен в версии 3.8.

Для вызова объекта, реализующего vectorcall, используйте функцию API вызова, как и любой другой вызываемый объект. PyObject_Vectorcall() обычно будет наиболее эффективной.

Вызов API объекта

Для вызова объекта Python доступны различные функции. Каждая преобразует свои аргументы в конвенцию, поддерживаемую вызываемым объектом — либо tp_call, либо vectorcall. Чтобы свести к минимуму преобразования, выберите функцию, которая лучше всего соответствует формату имеющихся данных.

Следующая таблица обобщает доступные функции; подробности см. в отдельной документации.

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

Значение возврата: новая ссылка. Часть Стабильной ABI.

Вызов вызываемого объекта Python callable с аргументами, заданными кортежем args, и именованными аргументами, заданными словарем kwargs.

args не должен быть NULL; используйте пустой кортеж, если аргументы не нужны. Если именованные аргументы не нужны, kwargs может быть NULL.

Возвращает результат вызова при успехе или вызывает исключение и возвращает NULL при ошибке.

Это эквивалент выражению Python: callable(*args, **kwargs).

PyObject *PyObject_CallNoArgs(PyObject *callable)

Значение возврата: новая ссылка. Часть Стабильной ABI с версии 3.10.

Вызов вызываемого объекта Python callable без аргументов. Это наиболее эффективный способ вызова вызываемого объекта Python без аргументов.

Возвращает результат вызова при успехе или вызывает исключение и возвращает NULL при ошибке.

Добавлена в версии 3.9.

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

Значение возврата: новая ссылка.

Вызов вызываемого объекта Python callable с ровно 1 позиционным аргументом arg и без именованных аргументов.

Возвращает результат вызова при успехе или вызывает исключение и возвращает NULL при ошибке.

Добавлена в версии 3.9.

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

Значение возврата: новая ссылка. Часть Стабильной ABI.

Вызов вызываемого объекта Python callable с аргументами, заданными кортежем args. Если аргументы не нужны, то args может быть NULL.

Возвращает результат вызова при успехе или вызывает исключение и возвращает NULL при ошибке.

Это эквивалент выражению Python: callable(*args).

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

Значение возврата: новая ссылка. Часть Стабильной ABI.

Вызов вызываемого объекта Python callable с переменным числом аргументов C. Аргументы C описываются с помощью строки формата в стиле Py_BuildValue(). Формат может быть NULL, что указывает на отсутствие аргументов.

Возвращает результат вызова при успехе или вызывает исключение и возвращает NULL при ошибке.

Это эквивалент выражению Python: callable(*args).

Обратите внимание, что если вы передаете только PyObject* аргументы, PyObject_CallFunctionObjArgs() — более быстрый вариант.

Изменено в версии 3.4: Тип формат был изменен с char *.

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

Значение возврата: новая ссылка. Часть Стабильной ABI.

Вызов метода с именем name объекта obj с переменным числом аргументов C. Аргументы C описываются строкой формата в стиле Py_BuildValue(), которая должна генерировать кортеж.

Формат может быть NULL, что указывает на отсутствие аргументов.

Возвращает результат вызова при успехе или вызывает исключение и возвращает NULL при ошибке.

Это эквивалент выражению Python: obj.name(arg1, arg2, ...).

Обратите внимание, что если вы передаете только PyObject* аргументы, PyObject_CallMethodObjArgs() — более быстрый вариант.

Изменено в версии 3.4: Типы name и формат были изменены с char *.

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

Вызов метода объекта Python obj с одним позиционным аргументом arg, где имя метода задаётся как объект Python строки в name.

Возвращает результат вызова при успехе или поднимает исключение и возвращает NULL при неудаче.

Добавлена в версии 3.9.

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

Часть Стабильной ABI начиная с версии 3.12.

Вызов вызываемого объекта Python callable. Аргументы такие же, как и для vectorcallfunc. Если callable поддерживает vectorcall, это напрямую вызывает функцию vectorcall, хранящуюся в callable.

Возвращает результат вызова при успехе или поднимает исключение и возвращает NULL при неудаче.

Добавлена в версии 3.9.

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

Вызов callable с позиционными аргументами, передаваемыми точно так же, как в протоколе vectorcall, но с ключевыми аргументами, переданными как словарь kwdict. Массив args содержит только позиционные аргументы.

Независимо от используемого внутреннего протокола, требуется преобразование аргументов. Поэтому эту функцию следует использовать только в том случае, если у вызывающего уже есть словарь, готовый к использованию для ключевых аргументов, но нет кортежа для позиционных аргументов.

Добавлена в версии 3.9.

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

Часть Стабильной ABI начиная с версии 3.12.

Вызов метода, используя соглашение о вызове vectorcall. Имя метода задаётся как Python-строка name. Объект, метод которого вызывается, это args[0], а массив args, начиная с args[1], представляет аргументы вызова. Должен быть хотя бы один позиционный аргумент. nargsf — количество позиционных аргументов, включая args[0], плюс PY_VECTORCALL_ARGUMENTS_OFFSET, если значение args[0] может быть временно изменено. Ключевые аргументы могут передаваться так же, как и в PyObject_Vectorcall().

Если у объекта есть функция Py_TPFLAGS_METHOD_DESCRIPTOR, это вызовет необусловленный объект метода с полным вектором args в качестве аргументов.

Возвращает результат вызова при успехе или поднимает исключение и возвращает NULL при неудаче.

Добавлена в версии 3.9.

API Поддержки Вызова

int PyCallable_Check(PyObject *o)

Часть Стабильной ABI.

Определяет, является ли объект o вызываемым. Возвращает 1 если объект вызываемый и 0 в противном случае. Эта функция всегда выполняется успешно.