Капсулы

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

PyCapsule

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

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)

Возвращаемое значение: новая ссылка.

Создаёт 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(), имеет не нулевой указатель, хранящийся внутри, и её внутреннее имя соответствует параметру 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, имя должно существовать дольше, чем капсула. Если предыдущее имя, хранящееся в капсуле, не было NULL, попытка освободить его не делается.

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

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

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

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