Капсулы

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

Возвращает истину, если её аргумент является PyCapsule. Эта функция всегда выполняется успешно.

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

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

Создаёт 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)

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

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

Параметр name должен точно совпадать с именем, хранящимся в капсуле. Если имя, хранящееся в капсуле, NULL, переданное name также должно быть 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-объект из атрибута капсулы в модуле. Параметр name должен указать полное имя атрибута, как в module.attribute. Хранящееся в капсуле name должно точно совпадать с этой строкой.

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

Изменено в версии 3.3: no_block больше не имеет эффекта.

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

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

Определяет, является ли capsule корректной капсулой. Корректная капсула не 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.

Устанавливает деструктор внутри capsule на destructor.

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

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

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

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

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

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

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

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

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