`capsule.md`

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