`function.md`

174 строк · 13.8 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3/c-api/function.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты функций89Есть несколько функций, специфичных для функций Python.1011#### `type PyFunctionObject`1213C-структура, используемая для функций.1415#### `PyTypeObject PyFunction_Type`1617Это экземпляр [`PyTypeObject`](https://python-all.ru/3/c-api/type.html#c.PyTypeObject) и представляет тип функции Python. Он доступен программистам на Python как `types.FunctionType`.1819#### `int PyFunction_Check(PyObject *o)`2021Возвращает true, если *o* является объектом функции (имеет тип [`PyFunction_Type`](https://python-all.ru/3/c-api/function.html#c.PyFunction_Type)). Параметр не должен быть `NULL`. Эта функция всегда выполняется успешно.2223#### `PyObject *PyFunction_New(PyObject *code, PyObject *globals)`2425*Возвращаемое значение: новая ссылка.*2627Возвращает новый объект функции, связанный с объектом кода *code*. *globals* должен быть словарём с глобальными переменными, доступными функции.2829Докстринг и имя функции извлекаются из объекта кода. [`__module__`](https://python-all.ru/3/reference/datamodel.html#function.__module__) извлекается из *globals*. Значения аргументов по умолчанию, аннотации и замыкание устанавливаются в `NULL`. [`__qualname__`](https://python-all.ru/3/reference/datamodel.html#function.__qualname__) устанавливается в то же значение, что и поле [`co_qualname`](https://python-all.ru/3/reference/datamodel.html#codeobject.co_qualname) объекта кода.3031#### `PyObject *PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)`3233*Возвращаемое значение: новая ссылка.*3435Как [`PyFunction_New()`](https://python-all.ru/3/c-api/function.html#c.PyFunction_New), но также позволяет задать атрибут [`__qualname__`](https://python-all.ru/3/reference/datamodel.html#function.__qualname__) объекта функции. *qualname* должен быть объектом unicode или `NULL`; если `NULL`, атрибут `__qualname__` устанавливается в то же значение, что и поле [`co_qualname`](https://python-all.ru/3/reference/datamodel.html#codeobject.co_qualname) объекта кода.3637Добавлено в версии 3.3.3839#### `PyObject *PyFunction_GetCode(PyObject *op)`4041*Возвращаемое значение: заимствованная ссылка.*4243Возвращает объект кода, связанный с объектом функции *op*.4445#### `PyObject *PyFunction_GetGlobals(PyObject *op)`4647*Возвращаемое значение: заимствованная ссылка.*4849Возвращает словарь глобальных переменных, связанный с объектом функции *op*.5051#### `PyObject *PyFunction_GetModule(PyObject *op)`5253*Возвращаемое значение: заимствованная ссылка.*5455Возвращает [заимствованную ссылку](https://python-all.ru/3/glossary.html#term-borrowed-reference) на атрибут [`__module__`](https://python-all.ru/3/reference/datamodel.html#function.__module__) объекта функции [https://python-all.ru/3/reference/datamodel.html#user-defined-funcs](https://python-all.ru/3/reference/datamodel.html#user-defined-funcs) *op*. Она может быть *NULL*.5657Обычно это [`string`](https://python-all.ru/3/library/stdtypes.html#str), содержащая имя модуля, но может быть установлена в любой другой объект кодом на Python.5859#### `PyObject *PyFunction_GetDefaults(PyObject *op)`6061*Возвращаемое значение: заимствованная ссылка.*6263Возвращает значения аргументов по умолчанию объекта функции *op*. Это может быть кортеж аргументов или `NULL`.6465#### `int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)`6667Устанавливает значения аргументов по умолчанию для объекта функции *op*. *defaults* должен быть `Py_None` или кортежем.6869В случае ошибки возбуждает [`SystemError`](https://python-all.ru/3/library/exceptions.html#SystemError) и возвращает `-1`.7071#### `void PyFunction_SetVectorcall(PyFunctionObject *func, vectorcallfunc vectorcall)`7273Устанавливает поле vectorcall для заданного объекта функции *func*.7475Предупреждение: расширения, использующие этот API, должны сохранять поведение неизменённой (стандартной) функции vectorcall!7677Добавлено в версии 3.12.7879#### `PyObject *PyFunction_GetKwDefaults(PyObject *op)`8081*Возвращаемое значение: заимствованная ссылка.*8283Возвращает значения по умолчанию для аргументов, передаваемых только по ключу, объекта функции *op*. Это может быть словарь аргументов или `NULL`.8485#### `int PyFunction_SetKwDefaults(PyObject *op, PyObject *defaults)`8687Устанавливает значения по умолчанию для именованных аргументов функции *op*. *defaults* должен быть словарём именованных аргументов или `Py_None`.8889Эта функция возвращает `0` при успехе и `-1` с установленным исключением при ошибке.9091#### `PyObject *PyFunction_GetClosure(PyObject *op)`9293*Возвращаемое значение: заимствованная ссылка.*9495Возвращает замыкание, связанное с функцией *op*. Может быть `NULL` или кортежем объектов-ячеек.9697#### `int PyFunction_SetClosure(PyObject *op, PyObject *closure)`9899Устанавливает замыкание для функции *op*. *closure* должен быть `Py_None` или кортежем объектов-ячеек.100101В случае ошибки возбуждает [`SystemError`](https://python-all.ru/3/library/exceptions.html#SystemError) и возвращает `-1`.102103#### `PyObject *PyFunction_GetAnnotations(PyObject *op)`104105*Возвращаемое значение: заимствованная ссылка.*106107Возвращает аннотации функции *op*. Может быть изменяемым словарём или `NULL`.108109#### `int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)`110111Устанавливает аннотации для функции *op*. *annotations* должен быть словарём или `Py_None`.112113В случае ошибки возбуждает [`SystemError`](https://python-all.ru/3/library/exceptions.html#SystemError) и возвращает `-1`.114115#### `PyObject *PyFunction_GET_CODE(PyObject *op)`116117#### `PyObject *PyFunction_GET_GLOBALS(PyObject *op)`118119#### `PyObject *PyFunction_GET_MODULE(PyObject *op)`120121#### `PyObject *PyFunction_GET_DEFAULTS(PyObject *op)`122123#### `PyObject *PyFunction_GET_KW_DEFAULTS(PyObject *op)`124125#### `PyObject *PyFunction_GET_CLOSURE(PyObject *op)`126127#### `PyObject *PyFunction_GET_ANNOTATIONS(PyObject *op)`128129*Возвращаемое значение: заимствованная ссылка.*130131Эти функции похожи на свои аналоги `PyFunction_Get*`, но не проверяют типы. Передача чего-либо, кроме экземпляра [`PyFunction_Type`](https://python-all.ru/3/c-api/function.html#c.PyFunction_Type), приводит к неопределённому поведению.132133#### `int PyFunction_AddWatcher(PyFunction_WatchCallback callback)`134135Регистрирует *колбэк* как наблюдатель за функциями для текущего интерпретатора. Возвращает идентификатор, который можно передать в [`PyFunction_ClearWatcher()`](https://python-all.ru/3/c-api/function.html#c.PyFunction_ClearWatcher). При ошибке (например, закончились свободные идентификаторы наблюдателей) возвращает `-1` и устанавливает исключение.136137Добавлено в версии 3.12.138139#### `int PyFunction_ClearWatcher(int watcher_id)`140141Удаляет наблюдателя с идентификатором *watcher\_id*, который был ранее получен из [`PyFunction_AddWatcher()`](https://python-all.ru/3/c-api/function.html#c.PyFunction_AddWatcher) для текущего интерпретатора. Возвращает `0` при успехе или `-1` и устанавливает исключение при ошибке (например, если указанный *watcher\_id* никогда не регистрировался).142143Добавлено в версии 3.12.144145#### `type PyFunction_WatchEvent`146147> Перечисление возможных событий наблюдателя за функциями:148>149> - `PyFunction_EVENT_CREATE`150> - `PyFunction_EVENT_DESTROY`151> - `PyFunction_EVENT_MODIFY_CODE`152> - `PyFunction_EVENT_MODIFY_DEFAULTS`153> - `PyFunction_EVENT_MODIFY_KWDEFAULTS`154155Добавлено в версии 3.12.156157#### `typedef int (*PyFunction_WatchCallback)(PyFunction_WatchEvent event, PyFunctionObject *func, PyObject *new_value)`158159Тип функции обратного вызова наблюдателя за функциями.160161Если *event* равен `PyFunction_EVENT_CREATE` или `PyFunction_EVENT_DESTROY`, то *new\_value* будет `NULL`. В остальных случаях *new\_value* будет содержать [заимствованную ссылку](https://python-all.ru/3/glossary.html#term-borrowed-reference) на новое значение, которое будет сохранено в *func* для изменяемого атрибута.162163Колбэк может просматривать *func*, но не должен его изменять; это может привести к непредсказуемым последствиям, включая бесконечную рекурсию.164165Если *event* равен `PyFunction_EVENT_CREATE`, то колбэк вызывается после полной инициализации *func*. В остальных случаях колбэк вызывается до изменения *func*, так что можно просмотреть предыдущее состояние *func*. Среда выполнения может оптимизировать создание объектов-функций, когда это возможно. В таких случаях никакого события не возникает. Хотя это может привести к наблюдаемым различиям в поведении во время выполнения в зависимости от решений оптимизатора, семантика выполняемого кода Python не меняется.166167Если *событие* равно `PyFunction_EVENT_DESTROY`, взятие ссылки в колбэке на функцию, которая вот-вот будет уничтожена, воскресит её, предотвратив её освобождение в этот момент. Когда воскрешённый объект будет уничтожен позже, все активные на тот момент колбэки наблюдателя будут вызваны снова.168169Если обратный вызов устанавливает исключение, он должен вернуть `-1`; это исключение будет выведено как неподнимаемое исключение с помощью [`PyErr_WriteUnraisable()`](https://python-all.ru/3/c-api/exceptions.html#c.PyErr_WriteUnraisable). В противном случае он должен вернуть `0`.170171На момент входа в обратный вызов уже может быть установлено отложенное исключение. В этом случае обратный вызов должен вернуть `0`, оставив то же исключение установленным. Это означает, что обратный вызов не может вызывать никакой другой API, который может установить исключение, если только он сначала не сохранит и не очистит состояние исключения, а затем не восстановит его перед возвратом.172173Добавлено в версии 3.12.174