Капсулы

Дополнительные сведения об использовании этих объектов см. в разделе Предоставление C API для модуля расширения.

Добавлено в версии 3.1.

PyCapsule_Destructor

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

typedef void (*PyCapsule_Destructor)(PyObject *);

Семантику PyCapsule_New() PyCapsule_Destructor см. в разделе колбэки.

int PyCapsule_CheckExact(PyObject *p)

Возвращает true, если его аргумент является PyCapsule.

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

Return value: New reference.

Создать PyCapsule, инкапсулирующий pointer. Аргумент pointer не может быть NULL.

При сбое установит исключение и возвратит NULL.

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

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

Если эта капсула будет храниться как атрибут модуля, name следует указать как modulename.attributename. Это позволит другим модулям импортировать капсулу с помощью 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() или PyErr_Occurred() для устранения неоднозначности.

void* PyCapsule_GetContext(PyObject *capsule)

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

Капсула имеет NULL контекст. Это делает NULL код возврата несколько двусмысленным; используйте PyCapsule_IsValid() или PyErr_Occurred() для устранения неоднозначности.

const char* PyCapsule_GetName(PyObject *capsule)

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

Капсула имеет NULL имя. Это делает NULL код возврата несколько двусмысленным; используйте PyCapsule_IsValid() или PyErr_Occurred() для устранения неоднозначности.

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

Импорт указателя в объект C из капсулы, атрибут в модуле. Параметр name должен указывать полное имя атрибута, как в module.attribute. Хранящиеся в капсуле name должны точно соответствовать этой строке. Если no_block имеет значение true, импортируется модуль без блокировки (с помощью PyImport_ImportModuleNoBlock()). Если no_block имеет значение false, импортируется модуль обычным способом (с использованием PyImport_ImportModule()).

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

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

Определяет, является ли capsule допустимой капсулой. Допустимая капсула не-NULL, проходит PyCapsule_CheckExact(), в ней хранится не-NULL указатель, а ее внутреннее имя соответствует параметру name. (См. PyCapsule_GetPointer() для получения информации о том, как сравниваются названия капсул.)

Другими словами, если 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)

Установить пустой указатель внутри capsule на pointer. Возможно, не NULL указатель.

Возвращает 0 при успехе. Возвращает ненулевое значение и задание исключения при сбое.