Документация Python неофициальный перевод

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

Есть несколько функций, специфичных для функций 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)

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

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

int PyFunction_ClearWatcher(int watcher_id)

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

Добавлено в версии 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, так что можно просмотреть предыдущее состояние func. Среда выполнения может оптимизировать создание объектов-функций, когда это возможно. В таких случаях никакого события не возникает. Хотя это может привести к наблюдаемым различиям в поведении во время выполнения в зависимости от решений оптимизатора, семантика выполняемого кода Python не меняется.

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

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

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

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