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

Некоторые функции предназначены специально для функций 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_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.

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.