Объекты функций

В Python есть несколько функций, специфичных для функций.

type PyFunctionObject: Структура C, используемая для функций.

PyTypeObject PyFunction_Type: Это экземпляр PyTypeObject, представляющий тип функции Python. Программистам на Python он доступен как types.FunctionType.

int PyFunction_Check(PyObject *o): Возвращает true, если o является объектом-функцией (имеет тип PyFunction_Type). Параметр не должен быть NULL. Эта функция всегда завершается успешно.

PyObject *PyFunction_New(PyObject *code, PyObject *globals)

Возвращаемое значение: новая ссылка.

Возвращает новый объект-функцию, связанный с объектом кода code. globals должен быть словарём с глобальными переменными, доступными функции.

Строка документации и имя функции извлекаются из объекта кода. __module__ извлекается из globals. Значения аргументов по умолчанию, аннотации и замыкание устанавливаются в NULL. __qualname__ устанавливается в то же значение, что и поле co_qualname объекта кода.

PyObject *PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname): Возвращаемое значение: новая ссылка.
Как PyFunction_New(), но также позволяет задать атрибут __qualname__ объекта-функции. qualname должен быть объектом Unicode или NULL; если NULL, атрибут __qualname__ устанавливается в то же значение, что и поле co_qualname объекта кода.

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

PyObject *PyFunction_GetCode(PyObject *op): Возвращаемое значение: заимствованная ссылка.
Возвращает объект кода, связанный с объектом-функцией op.

PyObject *PyFunction_GetGlobals(PyObject *op): Возвращаемое значение: заимствованная ссылка.
Возвращает словарь глобальных переменных, связанный с объектом-функцией op.

PyObject *PyFunction_GetModule(PyObject *op)

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

Возвращает заимствованную ссылку на атрибут __module__ объекта-функции op. Он может быть равен NULL.

Обычно это string, содержащая имя модуля, но код Python может присвоить этому атрибуту любой другой объект.

PyObject *PyFunction_GetDefaults(PyObject *op): Возвращаемое значение: заимствованная ссылка.
Возвращает значения аргументов по умолчанию объекта-функции op. Это может быть кортеж аргументов или NULL.

int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)

Задаёт значения аргументов по умолчанию для объекта-функции op. defaults должен быть Py_None или кортежем.

При ошибке возбуждает исключение SystemError и возвращает -1.

void PyFunction_SetVectorcall(PyFunctionObject *func, vectorcallfunc vectorcall)

Задаёт поле vectorcall указанного объекта-функции func.

Предупреждение: расширения, использующие этот API, должны сохранять поведение неизменённой (стандартной) функции vectorcall!

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

PyObject *PyFunction_GetKwDefaults(PyObject *op): Возвращаемое значение: заимствованная ссылка.
Возвращает значения по умолчанию для именованных аргументов, доступных только по ключевому слову, объекта-функции op. Это может быть словарь аргументов или NULL.

int PyFunction_SetKwDefaults(PyObject *op, PyObject *defaults)

Задаёт значения по умолчанию для именованных аргументов, доступных только по ключевому слову, объекта-функции op. defaults должен быть словарём именованных аргументов, доступных только по ключевому слову, или Py_None.

При успешном выполнении эта функция возвращает 0, а при ошибке — -1 и устанавливает исключение.

PyObject *PyFunction_GetClosure(PyObject *op): Возвращаемое значение: заимствованная ссылка.
Возвращает замыкание, связанное с объектом-функцией op. Это может быть NULL или кортеж объектов ячеек.

int PyFunction_SetClosure(PyObject *op, PyObject *closure)

Задаёт замыкание, связанное с объектом-функцией op. closure должен быть Py_None или кортежем объектов ячеек.

При ошибке возбуждает исключение SystemError и возвращает -1.

PyObject *PyFunction_GetAnnotations(PyObject *op): Возвращаемое значение: заимствованная ссылка.
Возвращает аннотации объекта-функции op. Это может быть изменяемый словарь или NULL.

int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)

Задаёт аннотации объекта-функции op. annotations должен быть словарём или Py_None.

При ошибке возбуждает исключение SystemError и возвращает -1.

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): Возвращаемое значение: заимствованная ссылка.
Эти функции похожи на соответствующие функции PyFunction_Get*, но не выполняют проверку типа. Передача объекта, не являющегося экземпляром PyFunction_Type, приводит к неопределённому поведению.

int PyFunction_AddWatcher(PyFunction_WatchCallback callback): Регистрирует callback в качестве наблюдателя функций для текущего интерпретатора. Возвращает идентификатор, который можно передать в PyFunction_ClearWatcher(). В случае ошибки (например, если больше нет доступных идентификаторов наблюдателей) возвращает -1 и устанавливает исключение.

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

int PyFunction_ClearWatcher(int watcher_id): Удаляет наблюдателя с идентификатором watcher_id, ранее возвращённым функцией PyFunction_AddWatcher() для текущего интерпретатора. При успешном выполнении возвращает 0, а в случае ошибки (например, если указанный watcher_id не был зарегистрирован) возвращает -1 и устанавливает исключение.

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

type PyFunction_WatchEvent

Перечисление возможных событий наблюдателя функций:

PyFunction_EVENT_CREATE
PyFunction_EVENT_DESTROY
PyFunction_EVENT_MODIFY_CODE
PyFunction_EVENT_MODIFY_DEFAULTS
PyFunction_EVENT_MODIFY_KWDEFAULTS

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

typedef int (*PyFunction_WatchCallback)(PyFunction_WatchEvent event, PyFunctionObject *func, PyObject *new_value)

Тип функции обратного вызова наблюдателя функций.

Если event равен PyFunction_EVENT_CREATE или PyFunction_EVENT_DESTROY, то new_value будет равен NULL. В противном случае new_value будет содержать заимствованную ссылку на новое значение, которое собираются сохранить в func для изменяемого атрибута.

Функция обратного вызова может проверять func, но не должна изменять его; это может привести к непредсказуемым последствиям, включая бесконечную рекурсию.

Если event равен PyFunction_EVENT_CREATE, функция обратного вызова вызывается после полной инициализации func. В противном случае функция обратного вызова вызывается до изменения func, поэтому можно проверить его предыдущее состояние. Среде выполнения разрешено по возможности оптимизировать создание объектов-функций. В таких случаях событие не будет отправлено. Хотя из-за этого наблюдаемое поведение среды выполнения может различаться в зависимости от решений оптимизатора, семантика выполняемого кода Python не меняется.

Если event равен PyFunction_EVENT_DESTROY, создание в функции обратного вызова ссылки на функцию, которая должна быть уничтожена, воскресит её и предотвратит её освобождение в этот момент. Когда воскресший объект будет уничтожен позднее, все активные на тот момент функции обратного вызова наблюдателей будут вызваны снова.

Если функция обратного вызова устанавливает исключение, она должна вернуть -1; это исключение будет выведено как необрабатываемое с помощью PyErr_WriteUnraisable(). В противном случае она должна вернуть 0.

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

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