Капсулы

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

Возвращает true, если аргумент является PyCapsule.

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

Значение возврата: Новый указатель.

Создаёт PyCapsule, содержащий указатель pointer. Аргумент pointer не может быть NULL.

При неудаче устанавливает исключение и возвращает NULL.

Строка name может быть NULL или указателем на допустимую C-строку. Если не NULL, эта строка должна существовать дольше, чем капсула. (Хотя разрешено освободить её внутри деструктора.)

Если аргумент 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.

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, имя должно существовать дольше, чем капсула. Если предыдущее имя, хранящееся в капсуле, не NULL, попытка его освободить не предпринимается.

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

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

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

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