# Капсули

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

Added in version 3.1.

type PyCapsule

  This subtype of `PyObject` represents an opaque value, useful for C extension modules which 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.

PyTypeObject PyCapsule_Type
  Part of the Stable ABI.

  The type object corresponding to capsule objects. This is the same object as `types.CapsuleType` in the Python layer.

type PyCapsule_Destructor
  Part of the Stable ABI.

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

      typedef void (*PyCapsule_Destructor)(PyObject *);

  Перегляньте `PyCapsule_New()` для семантики зворотних викликів PyCapsule_Destructor.

int PyCapsule_CheckExact(PyObject *p)
  Thread safety: Atomic.

  Повертає true, якщо його аргумент `PyCapsule`. Ця функція завжди успішна.

PyObject *PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
  Return value: New reference. Part of the Stable ABI. Thread safety: Atomic.

  Створіть `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. Thread safety: Safe to call without external synchronization on distinct objects.

  Отримайте вказівник, що зберігається в капсулі. У разі помилки встановіть виняток і поверніть `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. Thread safety: Safe to call without external synchronization on distinct objects.

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

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

void *PyCapsule_GetContext(PyObject *capsule)
  Part of the Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

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

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

const char *PyCapsule_GetName(PyObject *capsule)
  Part of the Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

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

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

void *PyCapsule_Import(const char *name, int no_block)
  Part of the Stable ABI. Thread safety: Safe to call from multiple threads with external synchronization only.

  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.

  This function splits name on the `.` character, and imports the first element. It then processes further elements using attribute lookups.

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

  Примітка

  If name points to an attribute of some submodule or subpackage, this submodule or subpackage must be previously imported using other means (for example, by using `PyImport_ImportModule()`) for the attribute lookups to succeed.

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

int PyCapsule_IsValid(PyObject *capsule, const char *name)
  Part of the Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

  Визначає, чи є 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. Thread safety: Safe to call without external synchronization on distinct objects.

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

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

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
  Part of the Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

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

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

int PyCapsule_SetName(PyObject *capsule, const char *name)
  Part of the Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

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

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

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
  Part of the Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

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

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