Капсулы

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

type PyCapsule

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

type PyCapsule_Destructor

Часть Стабильной ABI.

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

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)

Значение возврата: Новая ссылка. Часть Стабильной ABI.

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

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

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

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

Если эта капсула будет храниться в качестве атрибута модуля, имя должно быть указано как modulename.attributename. Это позволит другим модулям импортировать капсулу с помощью PyCapsule_Import().

void *PyCapsule_GetPointer(PyObject *capsule, const char *name)

Часть Стабильной ABI.

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

Параметр имя должен точно совпадать с именем, сохраненным в капсуле. Если имя, сохраненное в капсуле, NULL, переданное имя также должно быть NULL. Python использует функцию C 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-объект из атрибута капсулы в модуле. Параметр имя должен указывать полное имя атрибута, как в module.attribute. Хранимое в капсуле имя должно точно совпадать с этой строкой. Если no_block равно true, импортирует модуль без блокировки (используя PyImport_ImportModuleNoBlock()). Если no_block равно false, импортирует модуль стандартным способом (используя PyImport_ImportModule()).

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

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

Часть Стабильной ABI.

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

Другими словами, если PyCapsule_IsValid() возвращает true, вызовы любых функций-аксессоров (любой функции, начинающейся с PyCapsule_Get()) гарантированно выполнятся успешно.

Возвращает ненулевое значение, если объект действителен и соответствует переданному имени. Возвращает 0 в противном случае. Эта функция не потерпит сбоев.

int PyCapsule_SetContext(PyObject *capsule, void *context)

Часть Стабильной ABI.

Устанавливает указатель контекста внутри капсулы на контекст.

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

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)

Часть Стабильной ABI.

Устанавливает деструктор внутри капсулы на деструктор.

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

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

Часть Стабильной ABI.

Устанавливает имя внутри капсулы на имя. Если не NULL, имя должно существовать дольше капсулы. Если ранее хранившееся в капсуле имя не NULL, попытка освободить его не предпринимается.

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

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

Часть Стабильной ABI.

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

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