`capsule.md`

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