Капсулы¶
Дополнительные сведения об использовании этих объектов см. в разделе Предоставление API на языке C для модуля расширения.
Added in version 3.1.
-
type PyCapsule¶
Этот подтип
PyObject
представляет непрозрачное значение, что полезно для модулей расширения C, которым нужно передать непрозрачное значение (как указатель void*) через код Python в другой код C. Он часто используется для того, чтобы сделать указатель функции Си, определенный в одном модуле, доступным для других модулей, так что обычный механизм импорта может быть использован для доступа к API Си, определенным в динамически загружаемых модулях.
-
type PyCapsule_Destructor¶
- Часть Стабильный ABI.
Тип обратного вызова деструктора для капсулы. Определяется как:
typedef void (*PyCapsule_Destructor)(PyObject *);
Семантику обратных вызовов PyCapsule_Destructor смотрите в
PyCapsule_New()
.
-
int PyCapsule_CheckExact(PyObject *p)¶
Возвращает true, если его аргументом является
PyCapsule
. Эта функция всегда успешна.
-
PyObject *PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Создайте
PyCapsule
, заключающий в себе указатель. Аргумент pointer не может бытьNULL
.В случае неудачи создайте исключение и верните
NULL
.Строка имя может быть либо
NULL
, либо указателем на допустимую строку C. Если не``NULL``, то эта строка должна пережить капсулу. (Хотя разрешается освободить ее внутри деструктора).Если аргумент destructor не равен
NULL
, то при уничтожении капсулы он будет вызван с капсулой в качестве аргумента.Если эта капсула будет храниться как атрибут модуля, то имя должно быть указано как
modulename.attributename
. Это позволит другим модулям импортировать капсулу, используяPyCapsule_Import()
.
-
void *PyCapsule_GetPointer(PyObject *capsule, const char *name)¶
- Часть Стабильный ABI.
Получение указателя, хранящегося в капсуле. В случае неудачи создается исключение и возвращается
NULL
.Параметр name должен точно совпадать с именем, хранящимся в капсуле. Если имя, хранящееся в капсуле, равно
NULL
, то передаваемое name также должно бытьNULL
. Для сравнения имен капсул в Python используется функцияstrcmp()
на языке Си.
-
PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)¶
- Часть Стабильный ABI.
Возвращает текущий деструктор, хранящийся в капсуле. В случае неудачи создается исключение и возвращается
NULL
.Капсула может иметь деструктор
NULL
. Это делает код возвратаNULL
несколько двусмысленным; используйтеPyCapsule_IsValid()
илиPyErr_Occurred()
, чтобы не быть однозначным.
-
void *PyCapsule_GetContext(PyObject *capsule)¶
- Часть Стабильный ABI.
Возвращает текущий контекст, хранящийся в капсуле. В случае неудачи создается исключение и возвращается
NULL
.Капсула может иметь контекст
NULL
. Это делает код возвратаNULL
несколько двусмысленным; используйтеPyCapsule_IsValid()
илиPyErr_Occurred()
, чтобы не быть однозначным.
-
const char *PyCapsule_GetName(PyObject *capsule)¶
- Часть Стабильный ABI.
Возвращает текущее имя, хранящееся в капсуле. В случае неудачи создается исключение и возвращается
NULL
.Капсула может иметь имя
NULL
. Это делает код возвратаNULL
несколько двусмысленным; используйтеPyCapsule_IsValid()
илиPyErr_Occurred()
, чтобы не было разночтений.
-
void *PyCapsule_Import(const char *name, int no_block)¶
- Часть Стабильный ABI.
Импорт указателя на объект C из атрибута капсулы в модуле. Параметр name должен указывать полное имя атрибута, как в
module.attribute
. Имя name, хранящееся в капсуле, должно точно соответствовать этой строке.В случае успеха возвращает внутренний указатель капсулы. В случае неудачи создается исключение и возвращается
NULL
.Изменено в версии 3.3: no_block больше не действует.
-
int PyCapsule_IsValid(PyObject *capsule, const char *name)¶
- Часть Стабильный ABI.
Определяет, является ли капсула действительной капсулой. Действительная капсула не является``NULL``, передает
PyCapsule_CheckExact()
, в ней хранится указатель не``NULL``, а ее внутреннее имя соответствует параметру name. (Информацию о том, как сравниваются имена капсул, см. в разделеPyCapsule_GetPointer()
).Другими словами, если
PyCapsule_IsValid()
возвращает истинное значение, вызов любого из аксессоров (любой функции, начинающейся сPyCapsule_Get
) гарантированно будет успешным.Возвращает ненулевое значение, если объект действителен и соответствует переданному имени. В противном случае верните
0
. Эта функция не дает сбоев.
-
int PyCapsule_SetContext(PyObject *capsule, void *context)¶
- Часть Стабильный ABI.
Установите указатель контекста внутри capsule на context.
Возвращайте
0
при успехе. При неудаче возвращает ненулевое значение и устанавливает исключение.
-
int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)¶
- Часть Стабильный ABI.
Установите деструктор внутри капсулы на destructor.
Возвращайте
0
при успехе. При неудаче возвращает ненулевое значение и устанавливает исключение.
-
int PyCapsule_SetName(PyObject *capsule, const char *name)¶
- Часть Стабильный ABI.
Установите имя внутри капсулы на имя. Если имя не``NULL``, оно должно пережить капсулу. Если предыдущее имя, хранившееся в капсуле, не было
NULL
, попытка освободить его не предпринимается.Возвращайте
0
при успехе. При неудаче возвращает ненулевое значение и устанавливает исключение.
-
int PyCapsule_SetPointer(PyObject *capsule, void *pointer)¶
- Часть Стабильный ABI.
Установите указатель void внутри капсулы на pointer. Указатель не может быть
NULL
.Возвращайте
0
при успехе. При неудаче возвращает ненулевое значение и устанавливает исключение.