Капсулы

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

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

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

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

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

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

Другими словами, если PyCapsule_IsValid() возвращает истинное значение, вызовы к любым из функций-доступа (любая функция, начинающаяся с 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 при успехе. Возвращает ненулевое значение и устанавливает исключение при ошибке.