> **Источник:** https://python-all.ru/3.2/c-api/capsule.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # Капсулы Обратитесь к [*Предоставление C API для модуля расширения*](https://python-all.ru/3.2/extending/extending.html#using-capsules) для получения дополнительной информации об использовании этих объектов. **`PyCapsule`** Этот подтип [`PyObject`](https://python-all.ru/3.2/c-api/structures.html#PyObject) представляет непрозрачное значение, полезное для C-расширений, которым нужно передать непрозрачное значение (как указатель `void*`) через код Python в другой C-код. Часто используется, чтобы сделать указатель на функцию C, определённую в одном модуле, доступным для других модулей, так что обычный механизм импорта можно использовать для доступа к C API, определённым в динамически загружаемых модулях. **`PyCapsule_Destructor`** Тип колбэка-деструктора для капсулы. Определяется как: ```c typedef void (*PyCapsule_Destructor)(PyObject *); ``` Смотрите [`PyCapsule_New()`](https://python-all.ru/3.2/c-api/capsule.html#PyCapsule_New) для семантики колбэков PyCapsule\_Destructor. #### `int PyCapsule_CheckExact(PyObject *p)` Возвращает истину, если его аргумент является [`PyCapsule`](https://python-all.ru/3.2/c-api/capsule.html#PyCapsule). #### `PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)` *Возвращаемое значение: новая ссылка.* Создаёт [`PyCapsule`](https://python-all.ru/3.2/c-api/capsule.html#PyCapsule), инкапсулирующий *pointer*. Аргумент *pointer* не может быть *NULL*. В случае ошибки устанавливает исключение и возвращает *NULL*. Строка *name* может быть *NULL* или указателем на корректную C-строку. Если она не равна *NULL*, эта строка должна пережить капсулу. (Хотя допускается освободить её внутри *destructor*.) Если аргумент *destructor* не равен *NULL*, он будет вызван с капсулой в качестве аргумента при её уничтожении. Если эта капсула будет сохранена как атрибут модуля, *name* должен быть указан как `modulename.attributename`. Это позволит другим модулям импортировать капсулу с помощью [`PyCapsule_Import()`](https://python-all.ru/3.2/c-api/capsule.html#PyCapsule_Import). #### `void* PyCapsule_GetPointer(PyObject *capsule, const char *name)` Извлекает *pointer*, хранящийся в капсуле. В случае ошибки устанавливает исключение и возвращает *NULL*. Параметр *name* должен точно совпадать с именем, хранящимся в капсуле. Если имя, хранящееся в капсуле, равно *NULL*, то переданное *name* также должно быть *NULL*. Python использует функцию C `strcmp()` для сравнения имён капсул. #### `PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)` Возвращает текущий деструктор, хранящийся в капсуле. В случае ошибки устанавливает исключение и возвращает *NULL*. Допускается, чтобы у капсулы был деструктор *NULL*. Это делает код возврата *NULL* несколько неоднозначным; используйте [`PyCapsule_IsValid()`](https://python-all.ru/3.2/c-api/capsule.html#PyCapsule_IsValid) или [`PyErr_Occurred()`](https://python-all.ru/3.2/c-api/exceptions.html#PyErr_Occurred) для устранения неоднозначности. #### `void* PyCapsule_GetContext(PyObject *capsule)` Возвращает текущий контекст, хранящийся в капсуле. В случае ошибки устанавливает исключение и возвращает *NULL*. Допускается, чтобы у капсулы был контекст *NULL*. Это делает код возврата *NULL* несколько неоднозначным; используйте [`PyCapsule_IsValid()`](https://python-all.ru/3.2/c-api/capsule.html#PyCapsule_IsValid) или [`PyErr_Occurred()`](https://python-all.ru/3.2/c-api/exceptions.html#PyErr_Occurred) для устранения неоднозначности. #### `const char* PyCapsule_GetName(PyObject *capsule)` Возвращает текущее имя, хранящееся в капсуле. В случае ошибки устанавливает исключение и возвращает *NULL*. Допускается, чтобы у капсулы было имя *NULL*. Это делает код возврата *NULL* несколько неоднозначным; используйте [`PyCapsule_IsValid()`](https://python-all.ru/3.2/c-api/capsule.html#PyCapsule_IsValid) или [`PyErr_Occurred()`](https://python-all.ru/3.2/c-api/exceptions.html#PyErr_Occurred) для устранения неоднозначности. #### `void* PyCapsule_Import(const char *name, int no_block)` Импортирует указатель на C-объект из атрибута капсулы в модуле. Параметр *name* должен задавать полное имя атрибута, например `module.attribute`. Имя *name*, хранящееся в капсуле, должно точно совпадать с этой строкой. Если *no\_block* истинно, импортировать модуль без блокировки (используя [`PyImport_ImportModuleNoBlock()`](https://python-all.ru/3.2/c-api/import.html#PyImport_ImportModuleNoBlock)). Если *no\_block* ложно, импортировать модуль обычным способом (используя [`PyImport_ImportModule()`](https://python-all.ru/3.2/c-api/import.html#PyImport_ImportModule)). В случае успеха возвращает внутренний *pointer* капсулы. В случае неудачи устанавливает исключение и возвращает *NULL*. Однако если [`PyCapsule_Import()`](https://python-all.ru/3.2/c-api/capsule.html#PyCapsule_Import) не удалось импортировать модуль, и *no\_block* было истинно, исключение не устанавливается. #### `int PyCapsule_IsValid(PyObject *capsule, const char *name)` Определяет, является ли *capsule* допустимой капсулой. Допустимая капсула не равна *NULL*, проходит проверку [`PyCapsule_CheckExact()`](https://python-all.ru/3.2/c-api/capsule.html#PyCapsule_CheckExact), содержит ненулевой *NULL* указатель, и её внутреннее имя совпадает с параметром *name*. (Смотрите [`PyCapsule_GetPointer()`](https://python-all.ru/3.2/c-api/capsule.html#PyCapsule_GetPointer) для информации о том, как сравниваются имена капсул.) Другими словами, если [`PyCapsule_IsValid()`](https://python-all.ru/3.2/c-api/capsule.html#PyCapsule_IsValid) возвращает истинное значение, вызовы любых функций доступа (любых функций, начинающихся с `PyCapsule_Get()`) гарантированно завершатся успешно. Возвращает ненулевое значение, если объект корректен и соответствует переданному имени. В противном случае возвращает 0. Эта функция не завершается ошибкой. #### `int PyCapsule_SetContext(PyObject *capsule, void *context)` Устанавливает указатель контекста внутри *capsule* в значение *context*. Возвращает 0 при успехе. Возвращает ненулевое значение и устанавливает исключение при ошибке. #### `int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)` Устанавливает деструктор внутри *capsule* в значение *destructor*. Возвращает 0 при успехе. Возвращает ненулевое значение и устанавливает исключение при ошибке. #### `int PyCapsule_SetName(PyObject *capsule, const char *name)` Устанавливает имя внутри *capsule* равным *name*. Если оно не равно *NULL*, имя должно пережить капсулу. Если предыдущее *name*, хранящееся в капсуле, не было *NULL*, не предпринимается попыток освободить его. Возвращает 0 при успехе. Возвращает ненулевое значение и устанавливает исключение при ошибке. #### `int PyCapsule_SetPointer(PyObject *capsule, void *pointer)` Устанавливает указатель void внутри *capsule* равным *pointer*. Указатель не может быть *NULL*. Возвращает 0 при успехе. Возвращает ненулевое значение и устанавливает исключение при ошибке.