> **Источник:** https://python-all.ru/2.7/c-api/capsule.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# Капсулы

Обратитесь к [Предоставление C API для модуля расширения](https://python-all.ru/2.7/extending/extending.html#using-capsules) для получения дополнительной информации об использовании этих объектов.

Новое в версии 2.7.

**`PyCapsule`**

Этот подтип [`PyObject`](https://python-all.ru/2.7/c-api/structures.html#c.PyObject) представляет собой непрозрачное значение, полезное для C модулей расширения, которым нужно передать непрозрачное значение (в виде `void*` указателя) через код Python в другой код C. Часто используется, чтобы сделать указатель на функцию C , определённую в одном модуле, доступной для других модулей, так что обычный механизм импорта может использоваться для доступа к C API, определённым в динамически загружаемых модулях.

**`PyCapsule_Destructor`**

Тип колбэка-деструктора для капсулы. Определяется как:

```c
typedef void (*PyCapsule_Destructor)(PyObject *);
```

См. [`PyCapsule_New()`](https://python-all.ru/2.7/c-api/capsule.html#c.PyCapsule_New) для описания семантики колбэков PyCapsule\_Destructor.

#### `int PyCapsule_CheckExact(PyObject *p)`

Возвращает true, если аргумент является объектом [`PyCapsule`](https://python-all.ru/2.7/c-api/capsule.html#c.PyCapsule).

#### `PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)`

*Возвращаемое значение: новая ссылка.*

Создаёт [`PyCapsule`](https://python-all.ru/2.7/c-api/capsule.html#c.PyCapsule), инкапсулирующий *pointer*. Аргумент *pointer* не может быть *NULL*.

В случае ошибки устанавливает исключение и возвращает *NULL*.

Строка *name* может быть *NULL* или указателем на корректную C-строку. Если она не равна *NULL*, эта строка должна пережить капсулу. (Хотя допускается освободить её внутри *destructor*.)

Если аргумент *destructor* не равен *NULL*, он будет вызван с капсулой в качестве аргумента при её уничтожении.

Если эта капсула будет храниться как атрибут модуля, *имя* следует указать как `modulename.attributename`. Это позволит другим модулям импортировать капсулу с помощью [`PyCapsule_Import()`](https://python-all.ru/2.7/c-api/capsule.html#c.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/2.7/c-api/capsule.html#c.PyCapsule_IsValid) или [`PyErr_Occurred()`](https://python-all.ru/2.7/c-api/exceptions.html#c.PyErr_Occurred) для устранения неоднозначности.

#### `void* PyCapsule_GetContext(PyObject *capsule)`

Возвращает текущий контекст, хранящийся в капсуле. В случае ошибки устанавливает исключение и возвращает *NULL*.

Для капсулы допустимо иметь *NULL*-контекст. Это делает код возврата *NULL* несколько двусмысленным; используйте [`PyCapsule_IsValid()`](https://python-all.ru/2.7/c-api/capsule.html#c.PyCapsule_IsValid) или [`PyErr_Occurred()`](https://python-all.ru/2.7/c-api/exceptions.html#c.PyErr_Occurred) для устранения неоднозначности.

#### `const char* PyCapsule_GetName(PyObject *capsule)`

Возвращает текущее имя, хранящееся в капсуле. В случае ошибки устанавливает исключение и возвращает *NULL*.

Для капсулы допустимо иметь *NULL*-имя. Это делает код возврата *NULL* несколько двусмысленным; используйте [`PyCapsule_IsValid()`](https://python-all.ru/2.7/c-api/capsule.html#c.PyCapsule_IsValid) или [`PyErr_Occurred()`](https://python-all.ru/2.7/c-api/exceptions.html#c.PyErr_Occurred) для устранения неоднозначности.

#### `void* PyCapsule_Import(const char *name, int no_block)`

Импортирует указатель на объект C из атрибута-капсулы в модуле. Параметр *name* должен задавать полное имя атрибута, как в `module.attribute`. *name*, хранящееся в капсуле, должно точно совпадать с этой строкой. Если *no\_block* равно true, импорт модуля выполняется без блокировки (с использованием [`PyImport_ImportModuleNoBlock()`](https://python-all.ru/2.7/c-api/import.html#c.PyImport_ImportModuleNoBlock)). Если *no\_block* равно false, импорт модуля выполняется обычным способом (с использованием [`PyImport_ImportModule()`](https://python-all.ru/2.7/c-api/import.html#c.PyImport_ImportModule)).

При успехе возвращает внутренний *pointer* капсулы. В случае ошибки устанавливает исключение и возвращает *NULL*.

#### `int PyCapsule_IsValid(PyObject *capsule, const char *name)`

Определяет, является ли *capsule* допустимой капсулой. Допустимая капсула не равна *NULL*, проходит проверку [`PyCapsule_CheckExact()`](https://python-all.ru/2.7/c-api/capsule.html#c.PyCapsule_CheckExact), хранит не-*NULL* указатель, и её внутреннее имя соответствует параметру *name*. (См. [`PyCapsule_GetPointer()`](https://python-all.ru/2.7/c-api/capsule.html#c.PyCapsule_GetPointer) для информации о том, как сравниваются имена капсул.)

Другими словами, если [`PyCapsule_IsValid()`](https://python-all.ru/2.7/c-api/capsule.html#c.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` в случае успеха. В случае неудачи возвращает ненулевое значение и устанавливает исключение.