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

Для функций 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.

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.