Капсулы

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

type PyCapsule

Этот подтип PyObject представляет собой непрозрачное значение, полезное для модулей расширения на C, которым нужно передавать непрозрачное значение (в виде указателя void*) через код Python другому коду на C. Часто он используется, чтобы сделать указатель на функцию C, определённую в одном модуле, доступным другим модулям, благодаря чему для доступа к 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, инкапсулирующую указатель. Аргумент указатель не может быть 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.

Примечание

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

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

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

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

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