Капсули

Зверніться до Надання C API для модуля розширення для отримання додаткової інформації про використання цих об’єктів.

Нове в версії 3.1.

PyCapsule

This subtype of PyObject represents an opaque value, useful for C extension modules who need to pass an opaque value (as a void* pointer) through Python code to other C code. It is often used to make a C function pointer defined in one module available to other modules, so the regular import mechanism can be used to access C APIs defined in dynamically loaded modules.

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)

Return value: New reference.

Створіть PyCapsule, що інкапсулює вказівник. Аргумент покажчик не може бути NULL.

У разі помилки встановіть виняток і поверніть NULL.

Рядок name може бути NULL або вказівником на дійсний рядок C. Якщо значення не NULL, цей рядок має пережити капсулу. (Хоча його можна звільнити всередині деструктора.)

Якщо аргумент destructor не дорівнює NULL, він буде викликаний з капсулою як аргументом під час її знищення.

Якщо ця капсула зберігатиметься як атрибут модуля, ім’я слід вказати як modulename.attributename. Це дозволить іншим модулям імпортувати капсулу за допомогою PyCapsule_Import().

void* PyCapsule_GetPointer(PyObject *capsule, const char *name)

Отримайте вказівник, що зберігається в капсулі. У разі помилки встановіть виняток і поверніть NULL.

The name parameter must compare exactly to the name stored in the capsule. If the name stored in the capsule is NULL, the name passed in must also be NULL. Python uses the C function strcmp() to compare capsule names.

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)

Import a pointer to a C object from a capsule attribute in a module. The name parameter should specify the full name to the attribute, as in module.attribute. The name stored in the capsule must match this string exactly. If no_block is true, import the module without blocking (using PyImport_ImportModuleNoBlock()). If no_block is false, import the module conventionally (using PyImport_ImportModule()).

Поверніть внутрішній покажчик капсули в разі успіху. У разі помилки встановіть виняток і поверніть NULL.

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

Визначає, чи є capsule дійсною капсулою. Дійсна капсула не є NULL, передає PyCapsule_CheckExact(), має збережений вказівник не NULL, а її внутрішнє ім’я збігається з параметром name. (Див. PyCapsule_GetPointer() для отримання інформації про те, як порівнюються назви капсул.)

In other words, if PyCapsule_IsValid() returns a true value, calls to any of the accessors (any function starting with PyCapsule_Get()) are guaranteed to succeed.

Повертає ненульове значення, якщо об’єкт дійсний і відповідає переданому імені. В іншому випадку повертає 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)

Встановіть вказівник пустоти всередині capsule на pointer. Покажчик не може бути NULL.

У разі успіху повертає 0. Повертає ненульове значення та встановлює виняток у разі помилки.