`capsule.md`

116 строк · 11.5 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.1/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.1/extending/extending.html#using-capsules) для получения дополнительной информации об использовании этих объектов.1011**`PyCapsule`**1213Этот подтип1415[`PyObject`](https://python-all.ru/3.1/c-api/structures.html#PyObject)1617представляет непрозрачное значение, полезное для C-расширений, которым нужно передать непрозрачное значение (как указатель1819`void*`2021) через код Python в другой C-код. Часто используется, чтобы сделать указатель на функцию C, определённую в одном модуле, доступным для других модулей, так что обычный механизм импорта можно использовать для доступа к C API, определённым в динамически загружаемых модулях.2223**`PyCapsule_Destructor`**2425Тип колбэка-деструктора для капсулы. Определяется как:2627```c28typedef void (*PyCapsule_Destructor)(PyObject *);29```3031Смотрите [`PyCapsule_New()`](https://python-all.ru/3.1/c-api/capsule.html#PyCapsule_New) для семантики колбэков PyCapsule\_Destructor.3233**int `PyCapsule_CheckExact`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*p*)**3435Возвращает истину, если его аргумент является3637[`PyCapsule`](https://python-all.ru/3.1/c-api/capsule.html#PyCapsule)3839.4041**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyCapsule_New`(void *\*pointer*, const char *\*name*, [PyCapsule\_Destructor](https://python-all.ru/3.1/c-api/capsule.html#PyCapsule_Destructor) *destructor*)**4243*Возвращаемое значение: новая ссылка.*4445Создаёт [`PyCapsule`](https://python-all.ru/3.1/c-api/capsule.html#PyCapsule), инкапсулирующий *pointer*. Аргумент *pointer* не может быть *NULL*.4647В случае ошибки устанавливает исключение и возвращает *NULL*.4849Строка *name* может быть *NULL* или указателем на корректную C-строку. Если она не равна *NULL*, эта строка должна пережить капсулу. (Хотя допускается освободить её внутри *destructor*.)5051Если аргумент *destructor* не равен *NULL*, он будет вызван с капсулой в качестве аргумента при её уничтожении.5253Если эта капсула будет сохранена как атрибут модуля, *name* должен быть указан как `modulename.attributename`. Это позволит другим модулям импортировать капсулу с помощью [`PyCapsule_Import()`](https://python-all.ru/3.1/c-api/capsule.html#PyCapsule_Import).5455**void\* `PyCapsule_GetPointer`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*capsule*, const char *\*name*)**5657Извлекает *pointer*, хранящийся в капсуле. В случае ошибки устанавливает исключение и возвращает *NULL*.5859Параметр *name* должен точно совпадать с именем, хранящимся в капсуле. Если имя, хранящееся в капсуле, равно *NULL*, то переданное *name* также должно быть *NULL*. Python использует функцию C `strcmp()` для сравнения имён капсул.6061**[PyCapsule\_Destructor](https://python-all.ru/3.1/c-api/capsule.html#PyCapsule_Destructor) `PyCapsule_GetDestructor`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*capsule*)**6263Возвращает текущий деструктор, хранящийся в капсуле. В случае ошибки устанавливает исключение и возвращает *NULL*.6465Допускается, чтобы у капсулы был деструктор *NULL*. Это делает код возврата *NULL* несколько неоднозначным; используйте [`PyCapsule_IsValid()`](https://python-all.ru/3.1/c-api/capsule.html#PyCapsule_IsValid) или [`PyErr_Occurred()`](https://python-all.ru/3.1/c-api/exceptions.html#PyErr_Occurred) для устранения неоднозначности.6667**void\* `PyCapsule_GetContext`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*capsule*)**6869Возвращает текущий контекст, хранящийся в капсуле. В случае ошибки устанавливает исключение и возвращает *NULL*.7071Допускается, чтобы у капсулы был контекст *NULL*. Это делает код возврата *NULL* несколько неоднозначным; используйте [`PyCapsule_IsValid()`](https://python-all.ru/3.1/c-api/capsule.html#PyCapsule_IsValid) или [`PyErr_Occurred()`](https://python-all.ru/3.1/c-api/exceptions.html#PyErr_Occurred) для устранения неоднозначности.7273**const char\* `PyCapsule_GetName`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*capsule*)**7475Возвращает текущее имя, хранящееся в капсуле. В случае ошибки устанавливает исключение и возвращает *NULL*.7677Допускается, чтобы у капсулы было имя *NULL*. Это делает код возврата *NULL* несколько неоднозначным; используйте [`PyCapsule_IsValid()`](https://python-all.ru/3.1/c-api/capsule.html#PyCapsule_IsValid) или [`PyErr_Occurred()`](https://python-all.ru/3.1/c-api/exceptions.html#PyErr_Occurred) для устранения неоднозначности.7879**void\* `PyCapsule_Import`(const char *\*name*, int *no\_block*)**8081Импортирует указатель на C-объект из атрибута капсулы в модуле. Параметр *name* должен задавать полное имя атрибута, например `module.attribute`. Имя *name*, хранящееся в капсуле, должно точно совпадать с этой строкой. Если *no\_block* истинно, импортировать модуль без блокировки (используя [`PyImport_ImportModuleNoBlock()`](https://python-all.ru/3.1/c-api/import.html#PyImport_ImportModuleNoBlock)). Если *no\_block* ложно, импортировать модуль обычным способом (используя [`PyImport_ImportModule()`](https://python-all.ru/3.1/c-api/import.html#PyImport_ImportModule)).8283В случае успеха возвращает внутренний *pointer* капсулы. В случае неудачи устанавливает исключение и возвращает *NULL*. Однако если [`PyCapsule_Import()`](https://python-all.ru/3.1/c-api/capsule.html#PyCapsule_Import) не удалось импортировать модуль, и *no\_block* было истинно, исключение не устанавливается.8485**int `PyCapsule_IsValid`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*capsule*, const char *\*name*)**8687Определяет, является ли *capsule* допустимой капсулой. Допустимая капсула не равна *NULL*, проходит проверку [`PyCapsule_CheckExact()`](https://python-all.ru/3.1/c-api/capsule.html#PyCapsule_CheckExact), содержит ненулевой *NULL* указатель, и её внутреннее имя совпадает с параметром *name*. (Смотрите [`PyCapsule_GetPointer()`](https://python-all.ru/3.1/c-api/capsule.html#PyCapsule_GetPointer) для информации о том, как сравниваются имена капсул.)8889Другими словами, если [`PyCapsule_IsValid()`](https://python-all.ru/3.1/c-api/capsule.html#PyCapsule_IsValid) возвращает истинное значение, вызовы любых функций доступа (любых функций, начинающихся с `PyCapsule_Get()`) гарантированно завершатся успешно.9091Возвращает ненулевое значение, если объект корректен и соответствует переданному имени. В противном случае возвращает 0. Эта функция не завершается ошибкой.9293**int `PyCapsule_SetContext`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*capsule*, void *\*context*)**9495Устанавливает указатель контекста внутри *capsule* в значение *context*.9697Возвращает 0 при успехе. Возвращает ненулевое значение и устанавливает исключение при ошибке.9899**int `PyCapsule_SetDestructor`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*capsule*, [PyCapsule\_Destructor](https://python-all.ru/3.1/c-api/capsule.html#PyCapsule_Destructor) *destructor*)**100101Устанавливает деструктор внутри *capsule* в значение *destructor*.102103Возвращает 0 при успехе. Возвращает ненулевое значение и устанавливает исключение при ошибке.104105**int `PyCapsule_SetName`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*capsule*, const char *\*name*)**106107Устанавливает имя внутри *capsule* равным *name*. Если оно не равно *NULL*, имя должно пережить капсулу. Если предыдущее *name*, хранящееся в капсуле, не было *NULL*, не предпринимается попыток освободить его.108109Возвращает 0 при успехе. Возвращает ненулевое значение и устанавливает исключение при ошибке.110111**int `PyCapsule_SetPointer`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*capsule*, void *\*pointer*)**112113Устанавливает указатель void внутри *capsule* равным *pointer*. Указатель не может быть *NULL*.114115Возвращает 0 при успехе. Возвращает ненулевое значение и устанавливает исключение при ошибке.116