`capsule.md`

106 строк · 10.5 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.9/c-api/capsule.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Капсулы89Обратитесь к [Предоставление C API для модуля расширения](https://python-all.ru/3.9/extending/extending.html#using-capsules) для получения дополнительной информации об использовании этих объектов.1011Новое в версии 3.1.1213**`PyCapsule`**1415Этот подтип [`PyObject`](https://python-all.ru/3.9/c-api/structures.html#c.PyObject) представляет собой непрозрачное значение, полезное для C модулей расширения, которым нужно передать непрозрачное значение (в виде `void*` указателя) через код Python в другой код C. Часто используется, чтобы сделать указатель на функцию C , определённую в одном модуле, доступной для других модулей, так что обычный механизм импорта может использоваться для доступа к C API, определённым в динамически загружаемых модулях.1617**`PyCapsule_Destructor`**1819Тип колбэка-деструктора для капсулы. Определяется как:2021```c22typedef void (*PyCapsule_Destructor)(PyObject *);23```2425См. [`PyCapsule_New()`](https://python-all.ru/3.9/c-api/capsule.html#c.PyCapsule_New) для описания семантики колбэков PyCapsule\_Destructor.2627#### `int PyCapsule_CheckExact(PyObject *p)`2829Возвращает истину, если аргумент является [`PyCapsule`](https://python-all.ru/3.9/c-api/capsule.html#c.PyCapsule). Эта функция всегда выполняется успешно.3031#### `PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)`3233*Возвращаемое значение: новая ссылка.*3435Создаёт [`PyCapsule`](https://python-all.ru/3.9/c-api/capsule.html#c.PyCapsule), инкапсулирующий *указатель*. Аргумент *указатель* не может быть `NULL`.3637При ошибке устанавливает исключение и возвращает `NULL`.3839Строка *имя* может быть либо `NULL`, либо указателем на допустимую C-строку. Если не `NULL`, эта строка должна пережить капсулу. (Хотя разрешается освободить её внутри *деструктора*.)4041Если аргумент *деструктор* не равен `NULL`, то он будет вызван с капсулой в качестве аргумента при её уничтожении.4243Если эта капсула будет храниться как атрибут модуля, *имя* следует указать как `modulename.attributename`. Это позволит другим модулям импортировать капсулу с помощью [`PyCapsule_Import()`](https://python-all.ru/3.9/c-api/capsule.html#c.PyCapsule_Import).4445#### `void* PyCapsule_GetPointer(PyObject *capsule, const char *name)`4647Извлекает *указатель*, хранящийся в капсуле. При ошибке устанавливает исключение и возвращает `NULL`.4849Параметр *имя* должен точно совпадать с именем, хранящимся в капсуле. Если имя, хранящееся в капсуле, равно `NULL`, то переданное *имя* также должно быть `NULL`. Python использует C-функцию `strcmp()` для сравнения имён капсул.5051#### `PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)`5253Возвращает текущий деструктор, хранящийся в капсуле. При ошибке устанавливает исключение и возвращает `NULL`.5455Капсула может иметь деструктор `NULL`. Это делает код возврата `NULL` несколько неоднозначным; используйте [`PyCapsule_IsValid()`](https://python-all.ru/3.9/c-api/capsule.html#c.PyCapsule_IsValid) или [`PyErr_Occurred()`](https://python-all.ru/3.9/c-api/exceptions.html#c.PyErr_Occurred) для устранения неоднозначности.5657#### `void* PyCapsule_GetContext(PyObject *capsule)`5859Возвращает текущий контекст, хранящийся в капсуле. В случае ошибки устанавливает исключение и возвращает `NULL`.6061Капсула может иметь контекст `NULL`. Это делает код возврата `NULL` несколько неоднозначным; используйте [`PyCapsule_IsValid()`](https://python-all.ru/3.9/c-api/capsule.html#c.PyCapsule_IsValid) или [`PyErr_Occurred()`](https://python-all.ru/3.9/c-api/exceptions.html#c.PyErr_Occurred) для устранения неоднозначности.6263#### `const char* PyCapsule_GetName(PyObject *capsule)`6465Возвращает текущее имя, хранящееся в капсуле. В случае ошибки устанавливает исключение и возвращает `NULL`.6667Капсула может иметь имя `NULL`. Это делает код возврата `NULL` несколько неоднозначным; используйте [`PyCapsule_IsValid()`](https://python-all.ru/3.9/c-api/capsule.html#c.PyCapsule_IsValid) или [`PyErr_Occurred()`](https://python-all.ru/3.9/c-api/exceptions.html#c.PyErr_Occurred) для устранения неоднозначности.6869#### `void* PyCapsule_Import(const char *name, int no_block)`7071Импортирует указатель на объект C из атрибута-капсулы в модуле. Параметр *name* должен задавать полное имя атрибута, как в `module.attribute`. *name*, хранящееся в капсуле, должно точно совпадать с этой строкой. Если *no\_block* равно true, импорт модуля выполняется без блокировки (с использованием [`PyImport_ImportModuleNoBlock()`](https://python-all.ru/3.9/c-api/import.html#c.PyImport_ImportModuleNoBlock)). Если *no\_block* равно false, импорт модуля выполняется обычным способом (с использованием [`PyImport_ImportModule()`](https://python-all.ru/3.9/c-api/import.html#c.PyImport_ImportModule)).7273Возвращает внутренний *указатель* капсулы в случае успеха. В случае ошибки устанавливает исключение и возвращает `NULL`.7475#### `int PyCapsule_IsValid(PyObject *capsule, const char *name)`7677Определяет, является ли *capsule* допустимой капсулой. Допустимая капсула не является `NULL`, проходит [`PyCapsule_CheckExact()`](https://python-all.ru/3.9/c-api/capsule.html#c.PyCapsule_CheckExact), содержит ненулевой `NULL` указатель, и её внутреннее имя совпадает с параметром *name*. (См. [`PyCapsule_GetPointer()`](https://python-all.ru/3.9/c-api/capsule.html#c.PyCapsule_GetPointer) для информации о том, как сравниваются имена капсул.)7879Другими словами, если [`PyCapsule_IsValid()`](https://python-all.ru/3.9/c-api/capsule.html#c.PyCapsule_IsValid) возвращает истинное значение, вызовы любых функций доступа (любой функции, начинающейся с `PyCapsule_Get()`) гарантированно завершаются успешно.8081Возвращает ненулевое значение, если объект допустим и соответствует переданному имени. В противном случае возвращает `0`. Эта функция не завершается ошибкой.8283#### `int PyCapsule_SetContext(PyObject *capsule, void *context)`8485Устанавливает указатель контекста внутри *capsule* в значение *context*.8687Возвращает `0` в случае успеха. В случае неудачи возвращает ненулевое значение и устанавливает исключение.8889#### `int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)`9091Устанавливает деструктор внутри *capsule* в значение *destructor*.9293Возвращает `0` в случае успеха. В случае неудачи возвращает ненулевое значение и устанавливает исключение.9495#### `int PyCapsule_SetName(PyObject *capsule, const char *name)`9697Устанавливает имя внутри *capsule* в значение *name*. Если не `NULL`, имя должно пережить капсулу. Если предыдущее *name*, хранящееся в капсуле, не было `NULL`, попытка его освобождения не предпринимается.9899Возвращает `0` в случае успеха. В случае неудачи возвращает ненулевое значение и устанавливает исключение.100101#### `int PyCapsule_SetPointer(PyObject *capsule, void *pointer)`102103Устанавливает указатель void внутри *capsule* на *pointer*. Указатель не может быть `NULL`.104105Возвращает `0` в случае успеха. В случае неудачи возвращает ненулевое значение и устанавливает исключение.106