`capsule.md`

168 строк · 15.1 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.15/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.15/extending/extending.html#using-capsules) для получения дополнительной информации об использовании этих объектов.1011Добавлено в версии 3.1.1213#### `type PyCapsule`1415Этот подтип [`PyObject`](https://python-all.ru/3.15/c-api/structures.html#c.PyObject) представляет непрозрачное значение, полезное для C модулей расширения, которым нужно передавать непрозрачное значение (в виде void\* указателя) через код Python другому C-коду. Он часто используется, чтобы сделать указатель на C-функцию, определенную в одном модуле, доступным для других модулей, так что обычный механизм импорта может использоваться для доступа к C API, определенным в динамически загружаемых модулях.1617#### `PyTypeObject PyCapsule_Type`1819*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*2021Объект типа, соответствующий объектам-капсулам. Это тот же объект что и [`types.CapsuleType`](https://python-all.ru/3.15/library/types.html#types.CapsuleType) на уровне Python.2223#### `type PyCapsule_Destructor`2425*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*2627Тип колбэка-деструктора для капсулы. Определяется как:2829```c30typedef void (*PyCapsule_Destructor)(PyObject *);31```3233См. [`PyCapsule_New()`](https://python-all.ru/3.15/c-api/capsule.html#c.PyCapsule_New) для описания семантики колбэков PyCapsule\_Destructor.3435#### `int PyCapsule_CheckExact(PyObject *p)`3637*Потокобезопасность: [атомарно](https://python-all.ru/3.15/library/threadsafety.html#threadsafety-level-atomic).*3839Возвращает истину, если аргумент является [`PyCapsule`](https://python-all.ru/3.15/c-api/capsule.html#c.PyCapsule). Эта функция всегда выполняется успешно.4041#### `PyObject *PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)`4243*Возвращаемое значение: новая ссылка.*4445*Часть [стабильного ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*4647*Потокобезопасность: [атомарно](https://python-all.ru/3.15/library/threadsafety.html#threadsafety-level-atomic).*4849Создаёт [`PyCapsule`](https://python-all.ru/3.15/c-api/capsule.html#c.PyCapsule), инкапсулирующий *указатель*. Аргумент *указатель* не может быть `NULL`.5051При ошибке устанавливает исключение и возвращает `NULL`.5253Строка *имя* может быть либо `NULL`, либо указателем на допустимую C-строку. Если не `NULL`, эта строка должна пережить капсулу. (Хотя разрешается освободить её внутри *деструктора*.)5455Если аргумент *деструктор* не равен `NULL`, то он будет вызван с капсулой в качестве аргумента при её уничтожении.5657Если эта капсула будет храниться как атрибут модуля, *имя* следует указать как `modulename.attributename`. Это позволит другим модулям импортировать капсулу с помощью [`PyCapsule_Import()`](https://python-all.ru/3.15/c-api/capsule.html#c.PyCapsule_Import).5859#### `void *PyCapsule_GetPointer(PyObject *capsule, const char *name)`6061*Часть [Стабильного ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*6263*Потокобезопасность: [Безопасен для вызова без внешней синхронизации для разных объектов](https://python-all.ru/3.15/library/threadsafety.html#threadsafety-level-distinct).*6465Извлекает *указатель*, хранящийся в капсуле. При ошибке устанавливает исключение и возвращает `NULL`.6667Параметр *имя* должен точно совпадать с именем, хранящимся в капсуле. Если имя, хранящееся в капсуле, равно `NULL`, то переданное *имя* также должно быть `NULL`. Python использует C-функцию `strcmp()` для сравнения имён капсул.6869#### `PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)`7071*Часть [Стабильного ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*7273*Потокобезопасность: [Безопасен для вызова без внешней синхронизации для разных объектов](https://python-all.ru/3.15/library/threadsafety.html#threadsafety-level-distinct).*7475Возвращает текущий деструктор, хранящийся в капсуле. При ошибке устанавливает исключение и возвращает `NULL`.7677Капсула может иметь деструктор `NULL`. Это делает код возврата `NULL` несколько неоднозначным; используйте [`PyCapsule_IsValid()`](https://python-all.ru/3.15/c-api/capsule.html#c.PyCapsule_IsValid) или [`PyErr_Occurred()`](https://python-all.ru/3.15/c-api/exceptions.html#c.PyErr_Occurred) для устранения неоднозначности.7879#### `void *PyCapsule_GetContext(PyObject *capsule)`8081*Часть [Стабильного ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*8283*Потокобезопасность: [Безопасен для вызова без внешней синхронизации для разных объектов](https://python-all.ru/3.15/library/threadsafety.html#threadsafety-level-distinct).*8485Возвращает текущий контекст, хранящийся в капсуле. В случае ошибки устанавливает исключение и возвращает `NULL`.8687Капсула может иметь контекст `NULL`. Это делает код возврата `NULL` несколько неоднозначным; используйте [`PyCapsule_IsValid()`](https://python-all.ru/3.15/c-api/capsule.html#c.PyCapsule_IsValid) или [`PyErr_Occurred()`](https://python-all.ru/3.15/c-api/exceptions.html#c.PyErr_Occurred) для устранения неоднозначности.8889#### `const char *PyCapsule_GetName(PyObject *capsule)`9091*Часть [Стабильного ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*9293*Потокобезопасность: [Безопасен для вызова без внешней синхронизации для разных объектов](https://python-all.ru/3.15/library/threadsafety.html#threadsafety-level-distinct).*9495Возвращает текущее имя, хранящееся в капсуле. В случае ошибки устанавливает исключение и возвращает `NULL`.9697Капсула может иметь имя `NULL`. Это делает код возврата `NULL` несколько неоднозначным; используйте [`PyCapsule_IsValid()`](https://python-all.ru/3.15/c-api/capsule.html#c.PyCapsule_IsValid) или [`PyErr_Occurred()`](https://python-all.ru/3.15/c-api/exceptions.html#c.PyErr_Occurred) для устранения неоднозначности.9899#### `void *PyCapsule_Import(const char *name, int no_block)`100101*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*102103*Потокобезопасность: [Безопасен для вызова из нескольких потоков только с внешней синхронизацией](https://python-all.ru/3.15/library/threadsafety.html#threadsafety-level-compatible).*104105Импортирует указатель на C-объект из атрибута капсулы в модуле. Параметр *name* должен указывать полное имя атрибута, например `module.attribute`. Имя *name*, хранящееся в капсуле, должно точно совпадать с этой строкой.106107Эта функция разбивает *name* по символу `.`, импортирует первый элемент, а затем обрабатывает остальные элементы с помощью поиска атрибутов.108109Возвращает внутренний *указатель* капсулы в случае успеха. В случае ошибки устанавливает исключение и возвращает `NULL`.110111> **Примечание**112>113> Если *name* указывает на атрибут какого-либо подмодуля или подпакета, этот подмодуль или подпакет должен быть предварительно импортирован другими средствами (например, с помощью [`PyImport_ImportModule()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_ImportModule)), чтобы поиск атрибутов прошёл успешно.114115Изменено в версии 3.3: *no\_block* больше не действует.116117#### `int PyCapsule_IsValid(PyObject *capsule, const char *name)`118119*Часть [Стабильного ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*120121*Потокобезопасность: [Безопасен для вызова без внешней синхронизации для разных объектов](https://python-all.ru/3.15/library/threadsafety.html#threadsafety-level-distinct).*122123Определяет, является ли *capsule* допустимой капсулой. Допустимая капсула не является `NULL`, проходит [`PyCapsule_CheckExact()`](https://python-all.ru/3.15/c-api/capsule.html#c.PyCapsule_CheckExact), содержит ненулевой `NULL` указатель, и её внутреннее имя совпадает с параметром *name*. (См. [`PyCapsule_GetPointer()`](https://python-all.ru/3.15/c-api/capsule.html#c.PyCapsule_GetPointer) для информации о том, как сравниваются имена капсул.)124125Другими словами, если [`PyCapsule_IsValid()`](https://python-all.ru/3.15/c-api/capsule.html#c.PyCapsule_IsValid) возвращает истинное значение, вызовы любых функций доступа (любой функции, начинающейся с `PyCapsule_Get`) гарантированно завершаются успешно.126127Возвращает ненулевое значение, если объект допустим и соответствует переданному имени. В противном случае возвращает `0`. Эта функция не завершается ошибкой.128129#### `int PyCapsule_SetContext(PyObject *capsule, void *context)`130131*Часть [Стабильного ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*132133*Потокобезопасность: [Безопасен для вызова без внешней синхронизации для разных объектов](https://python-all.ru/3.15/library/threadsafety.html#threadsafety-level-distinct).*134135Устанавливает указатель контекста внутри *capsule* в значение *context*.136137Возвращает `0` в случае успеха. В случае неудачи возвращает ненулевое значение и устанавливает исключение.138139#### `int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)`140141*Часть [Стабильного ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*142143*Потокобезопасность: [Безопасен для вызова без внешней синхронизации для разных объектов](https://python-all.ru/3.15/library/threadsafety.html#threadsafety-level-distinct).*144145Устанавливает деструктор внутри *capsule* в значение *destructor*.146147Возвращает `0` в случае успеха. В случае неудачи возвращает ненулевое значение и устанавливает исключение.148149#### `int PyCapsule_SetName(PyObject *capsule, const char *name)`150151*Часть [Стабильного ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*152153*Потокобезопасность: [Безопасен для вызова без внешней синхронизации для разных объектов](https://python-all.ru/3.15/library/threadsafety.html#threadsafety-level-distinct).*154155Устанавливает имя внутри *capsule* в значение *name*. Если не `NULL`, имя должно пережить капсулу. Если предыдущее *name*, хранящееся в капсуле, не было `NULL`, попытка его освобождения не предпринимается.156157Возвращает `0` в случае успеха. В случае неудачи возвращает ненулевое значение и устанавливает исключение.158159#### `int PyCapsule_SetPointer(PyObject *capsule, void *pointer)`160161*Часть [Стабильного ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*162163*Потокобезопасность: [Безопасен для вызова без внешней синхронизации для разных объектов](https://python-all.ru/3.15/library/threadsafety.html#threadsafety-level-distinct).*164165Устанавливает указатель void внутри *capsule* на *pointer*. Указатель не может быть `NULL`.166167Возвращает `0` в случае успеха. В случае неудачи возвращает ненулевое значение и устанавливает исключение.168