Капсулы

Обратитесь к Предоставление C API для модуля расширения для получения дополнительной информации об использовании этих объектов.

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

PyCapsule: Данный подтип PyObject представляет непрозрачное значение, полезное для модулей расширения C, которым необходимо передать непрозрачное значение (как указатель void*) через код Python в другой код C. Он часто используется для того, чтобы сделать указатель функции C, определенный в одном модуле, доступным для других модулей, поэтому для доступа к API- интерфейсам C, определенным в динамически загружаемых модулях, можно использовать обычный механизм импорта.

PyCapsule_Destructor

Тип обратного вызова деструктора для капсулы. Определяется как:

typedef void (*PyCapsule_Destructor)(PyObject *);

См. PyCapsule_New() для получения информации о семантике обратных вызовов PyCapsule_Destructor.

int PyCapsule_CheckExact(PyObject *p): Возвращает истину, если его аргумент — 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 истинно, импортировать модуль без блокировки (используя PyImport_ImportModuleNoBlock()). Если no_block ложно, импортировать модуль обычным способом (используя 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)

Устанавливает указатель void внутри capsule на pointer. Указатель может быть не NULL.

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