Капсулы

Дополнительные сведения об использовании этих объектов см. в разделе Предоставление 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 при успехе. При неудаче возвращает ненулевое значение и устанавливает исключение.