Капсулы

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

Изменено в версии 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. В случае сбоя возвращает ненулевое значение и устанавливает исключение.