Капсули

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

Added in version 3.1.

type 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.

type PyCapsule_Destructor

Part of the Stable ABI.

Тип зворотного виклику деструктора для капсули. Визначається як:

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. Part of the Stable ABI.

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

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

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

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

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

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

Part of the Stable ABI.

Отримайте вказівник, що зберігається в капсулі. У разі помилки встановіть виняток і поверніть 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)

Part of the Stable ABI.

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

Для капсули допустимо мати деструктор NULL. Це робить код повернення NULL дещо неоднозначним; використовуйте PyCapsule_IsValid() або PyErr_Occurred() для усунення неоднозначності.

void *PyCapsule_GetContext(PyObject *capsule)

Part of the Stable ABI.

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

Для капсули допустимо мати контекст NULL. Це робить код повернення NULL дещо неоднозначним; використовуйте PyCapsule_IsValid() або PyErr_Occurred() для усунення неоднозначності.

const char *PyCapsule_GetName(PyObject *capsule)

Part of the Stable ABI.

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

Для капсули є законним ім’я NULL. Це робить код повернення NULL дещо неоднозначним; використовуйте PyCapsule_IsValid() або PyErr_Occurred() для усунення неоднозначності.

void *PyCapsule_Import(const char *name, int no_block)

Part of the Stable ABI.

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.

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

Змінено в версії 3.3: no_block has no effect anymore.

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

Part of the Stable ABI.

Визначає, чи є 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)

Part of the Stable ABI.

Встановіть покажчик контексту всередині capsule на context.

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

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)

Part of the Stable ABI.

Встановіть для деструктора всередині capsule значення destructor.

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

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

Part of the Stable ABI.

Встановіть назву всередині capsule на name. Якщо значення не NULL, ім’я має пережити капсулу. Якщо попереднє ім’я, збережене в капсулі, не було NULL, спроба звільнити його не робиться.

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

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

Part of the Stable ABI.

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

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