Капсулы¶Capsules

Обратитесь к Предоставление 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)¶

Возвращает истину, если его аргумент является 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 истинно, импортировать модуль без блокировки (используя PyImport_ImportModuleNoBlock()). Если no_block ложно, импортировать модуль обычным способом (используя PyImport_ImportModule()).

В случае успеха возвращает внутренний pointer капсулы. В случае неудачи устанавливает исключение и возвращает NULL. Однако если PyCapsule_Import() не удалось импортировать модуль, и no_block было истинно, исключение не устанавливается.

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

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

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

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)¶

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

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